Mirage ORM

Phenomine includes Mirage, an object-relational mapper (ORM) that makes it enjoyable to interact with your database. When using Mirage, each database table has a corresponding "Model" that is used to interact with that table. In addition to retrieving records from the database table, Mirage models allow you to insert, update, and delete records from the table as well.

Generating Model Classes

To get started, let's create a Mirage model. Models are typically stored in the app/Models directory and extend the Phenomine\Support\Database\Mirage\Model class. You may use the make:model command to generate a new model class. The generated model will be placed in the app/Models directory:

php phenomine make:model User

If you would like to generate a database migration when you generate the model, you may use the --m option:

php phenomine make:model User --m

Mirage Model Conventions

Models generated by the make:model command will be placed in the app/Models directory. Let's examine a basic model class and discuss some of Mirage's key conventions:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class User extends Model
{
    // ...
}

Table Names

By default, Mirage assumes the table associated with the model is the plural form of the model name. For example, a User model would correspond to a users table. If you would like to specify a custom table name, you may override the $table property on the model:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class User extends Model
{
    /**
     * The table associated with the model.
     *
     * @var string
     */
    protected $table = 'my_users';
}

Primary Keys

Mirage will also assume that each model's corresponding database table has a primary key column named id. If necessary, you may define a protected $primaryKey property on your model to specify a different column that serves as your model's primary key:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class User extends Model
{
    /**
     * The primary key associated with the table.
     *
     * @var string
     */
    protected $primaryKey = 'user_id';
}

In addition, Mirage assumes that the primary key is an incrementing integer value, which means that Mirage will automatically cast the primary key to an integer. If you wish to use a non-incrementing or a non-numeric primary key you must define a protected $incrementing property on your model that is set to false:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class User extends Model
{
    /**
     * Indicates if the model's ID is auto-incrementing.
     *
     * @var bool
     */
    protected $incrementing = false;
}

If your model's primary key is not an integer, you should define a protected $keyType property on your model. This property should have a value of string:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class User extends Model
{
    /**
     * The data type of the primary key ID.
     *
     * @var string
     */
    protected $keyType = 'string';
}

UUID Primary Keys

Instead of using auto-incrementing integers as your Mirage model's primary keys, you may choose to use UUIDs instead. UUIDs are universally unique alpha-numeric identifiers that are 36 characters long.

If you would like a model to use a UUID key instead of an auto-incrementing integer key, you may use the Phenomine\Support\Database\Traits\HasUuids trait on the model. Of course, you should ensure that the model has a UUID equivalent primary key column:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;
use Phenomine\Support\Database\Traits\HasUuids;
use Phenomine\Support\Str;

class Post extends Model
{
    use HasUuids;

    // ...
}

$post = Article::create(['title' => 'Moving to Phenomine']);

$post->id; // "f47ac10b-58cc-4372-a567-0e02b2c3d479"

Timestamps

By default, Mirage expects created_at and updated_at columns to exist on your model's corresponding database table. Model will automatically set these column's values when models are created or updated. If you do not want these columns to be automatically managed by Model, you should define a $timestamps property on your model with a value of false:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class Post extends Model
{
    /**
     * Indicates if the model should be timestamped.
     *
     * @var bool
     */
    public $timestamps = false;
}

If you need to customize the names of the columns used to store the timestamps, you may define CREATED_AT and UPDATED_AT constants on your model:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class Post extends Model
{
    const CREATED_AT = 'creation_date';
    const UPDATED_AT = 'last_update';
}

Database Connection

By default, Mirage will use the default database connection defined in your config/database.php configuration file. If you would like to specify a different connection for the model, you may use the $connection property:

<?php

namespace App\Models;

use Phenomine\Support\Database\Mirage\Model;

class Post extends Model
{
    /**
     * The connection name for the model.
     *
     * @var string|null
     */
    protected $connection = 'pgsql';
}