Eloquent 0.4 is now out. This version introduces the schema builder, soft deletes, mixins and scopes.
The new schema builder is here to help manipulate your databases structure in an intuitive manner.
For that purpose you can use the
Schema class which provides a database
agnostic way of manipulating tables.
Creating and dropping tables
To create a new database table, the
create method is used:
To rename an existing database table, the
rename method can be used:
To specify which connection the schema operation should take place on, use the
To drop a table, you can use the
To update an existing table, you can use the
The table builder contains a variety of column types that you can use. See the official documentation for the full list.
Sometimes you may need to modify an existing column.
For example, you may wish to increase the size of a string column.
To do so, you can use the
The change column feature, while tested, is still considered in beta stage. Please report any encountered issue or bug on the Github Project
To rename a column, you can use use the
rename_column method on the Schema builder:
Prior to MySQL 5.6.6, foreign keys are NOT automatically updated when renaming columns. Therefore, you will need to drop the foreign key constraint, rename the column and recreate the constraint to avoid an error.
with schema.table('posts') as table: table.drop_foreign('posts_user_id_foreign') table.rename('user_id', 'author_id') table.foreign('author_id').references('id').on('users')
In future versions, Eloquent might handle this automatically.
The rename column feature, while tested, is still considered in beta stage (especially for SQLite). Please report any encountered issue or bug on the Github Project
To drop a column, you can use use the
drop_column method on the
Eloquent also provides support for adding foreign key constraints to your tables:
In this example, we are stating that the
column references the
id column on the
Make sure to create the foreign key column first!
You may also specify options for the "on delete" and "on update" actions of the constraint:
To drop a foreign key, you may use the
A similar naming convention is used for foreign keys as is used for other indexes:
There is more you can do with the schema builder, like handling indexes. Referer to the documentation to see all the available features.
When soft deleting a model, it is not actually removed from your database.
deleted_at timestamp is set on the record.
To enable soft deletes for a model, make it inherit from the
Now, when you call the
delete method on the model, the
deleted_at column will be
set to the current timestamp. When querying a model that uses soft deletes,
the "deleted" models will not be included in query results.
Forcing soft deleted models into results
To force soft deleted models to appear in a result set, use the
with_trashed method on the query:
with_trashed method may be used on a defined relationship:
Defining a query scope
Scopes allow you to easily re-use query logic in your models.
To define a scope, simply prefix a model method with
Using a query scope
Sometimes you may wish to define a scope that accepts parameters. Just add your parameters to your scope function:
Then pass the parameter into the scope call:
Sometimes you may wish to define a scope that applies to all queries performed on a model.
In essence, this is how Eloquent's own "soft delete" feature works.
Global scopes are defined using a combination of mixins and an implementation of the
First, let's define a mixin. For this example, we'll use the
SoftDeletes that ships with Eloquent:
If an Eloquent model inherits from a mixin that has a method matching the
naming convention, that mixin method will be called when the Eloquent model is booted,
giving you an opportunity to register a global scope, or do anything else you want.
A scope must be an instance of the
Scope class, which specifies two methods:
The apply method receives an
Builder query builder object and the
Model it's applied to,
and is responsible for adding any additional
where clauses that the scope wishes to add.
remove method also receives a
Builder object and
Model and is responsible
for reversing the action taken by
In other words,
remove should remove the
where clause (or any other clause) that was added.
So, for our
SoftDeletingScope, it would look something like this:
Finally, here are some features targeted for the 0.5 version:
- Database migrations based on the schema builder:
- Support for model accessors and mutators.
You can check the advancement on the Github project