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';
}