Creating a migration

As you will see in Chapter 8, Laravel provides a series of command-line tools you can use to interact with your app and generate boilerplate files. One of these commands allows you to create a migration file. You can run it using php artisan make:migration, and it has a single parameter, which is the name of the migration. For example, to create the table we just covered, you would run php artisan make:migration create_users_table.

There are two flags you can optionally pass to this command. --create=table_name prefills the migration with code designed to create a table named table_name, and --table=table_name just prefills the migration for modifications to an existing table. Here are a few examples:

php artisan make:migration create_users_table
php artisan make:migration add_votes_to_users_table --table=users
php artisan make:migration create_users_table --create=users

Creating tables

We already saw in the default create_users_table migration that our migrations depend on the Schema facade and its methods. Everything we can do in these migrations will rely on the methods of Schema.

To create a new table in a migration, use the create() method—the first parameter is the table name, and the second is a closure that defines its columns:

Schema::create('users', function (Blueprint $table) {
    // Create columns here
});

Creating columns

To create new columns in a table, whether in a create table call or a modify table call, use the instance of Blueprint that’s passed into your closure:

Schema::create('users', function (Blueprint $table) {
    $table->string('name');
});

Let’s look at the various methods available on Blueprint instances for creating columns. I’ll describe how they work in MySQL, but if you’re using another database, Laravel will just use the closest equivalent.

The following are the simple field Blueprint methods:

integer(colName), tinyInteger(colName), smallInteger(colName), mediumInteger(colName), bigInteger(colName)

Adds an INTEGER type column, or one of its many variations

string(colName, length)

Adds a VARCHAR type column with an optional length

binary(colName)

Adds a BLOB type column

boolean(colName)

Adds a BOOLEAN type column (a TINYINT(1) in MySQL)

char(colName, length)

Adds a CHAR column with an optional length

datetime(colName)

Adds a DATETIME column

decimal(colName, precision, scale)

Adds a DECIMAL column, with precision and scale—for example, decimal('amount', 5, 2) specifies a precision of 5 and a scale of 2

double(colName, total digits, digits after decimal)

Adds a DOUBLE column—for example, double('tolerance', 12, 8) specifies 12 digits long, with 8 of those digits to the right of the decimal place, as in 7204.05691739

enum(colName, [choiceOne, choiceTwo])

Adds an ENUM column, with provided choices

float(colName, precision, scale)

Adds a FLOAT column (same as double in MySQL)

json(colName) and jsonb(colName)

Adds a JSON or JSONB column (or a TEXT column in Laravel 5.1)

text(colName), mediumText(colName), longText(colName)

Adds a TEXT column (or its various sizes)

time(colName)

Adds a TIME column

timestamp(colName)

Adds a TIMESTAMP column

uuid(colName)

Adds a UUID column (CHAR(36) in MySQL)

And these are the special (joined) Blueprint methods:

increments(colName) and bigIncrements(colName)

Add an unsigned incrementing INTEGER or BIG INTEGER primary key ID

timestamps() and nullableTimestamps()

Adds created_at and updated_at timestamp columns

rememberToken()

Adds a remember_token column (VARCHAR(100)) for user “remember me” tokens

softDeletes()

Adds a deleted_at timestamp for use with soft deletes

morphs(colName)

For a provided colName, adds an integer colName_id and a string colName_type (e.g., morphs(tag) adds integer tag_id and string tag_type); for use in polymorphic relationships

Building extra properties fluently

Most of the properties of a field definition—its length, for example—are set as the second parameter of the field creation method, as we saw in the previous section. But there are a few other properties that we’ll set by chaining more method calls after the creation of the column. For example, this email field is nullable and will be placed (in MySQL) right after the last_name field:

Schema::table('users', function (Blueprint $table) {
    $table->string('email')->nullable()->after('last_name');
});

The following methods are used to set additional properties of a field:

nullable()

Allows NULL values to be inserted into this column

default('default content')

Specifies the default content for this column if no value is provided

unsigned()

Marks integer columns as unsigned (not negative or positive, but just an integer)

first() (MySQL only)

Places the column first in the column order

after(colName) (MySQL only)

Places the column after another column in the column order

unique()

Adds a UNIQUE index

primary()

Adds a primary key index

index()

Adds a basic index

Note that unique(), primary(), and index() can also be used outside of the fluent column building context, which we’ll cover later.

Dropping tables

If you want to drop a table, there’s a dropIfExists() method on Schema that takes one parameter, the table name:

Schema::dropIfExists('contacts');

Modifying columns

To modify a column, just write the code you would write to create the column as if it were new, and then append a call to the change() method after it.

So, if we have a string column named name that has a length of 255 and we want to change its length to 100, this is how we would write it:

Schema::table('users', function (Blueprint $table) {
    $table->string('name', 100)->change();
});

The same is true if we want to adjust any of its properties that aren’t defined in the method name. To make a field nullable, we do this:

Schema::table('contacts', function (Blueprint $table) {
    $table->string('deleted_at')->nullable()->change();
});

Here’s how we rename a column:

Schema::table('contacts', function (Blueprint $table)
{
    $table->renameColumn('promoted', 'is_promoted');
});

And this is how we drop a column:

Schema::table('contacts', function (Blueprint $table)
{
    $table->dropColumn('votes');
});

public function up()
{
    Schema::table('contacts', function (Blueprint $table)
    {
        $table->dropColumn('is_promoted');
    });

    Schema::table('contacts', function (Blueprint $table)
    {
        $table->dropColumn('alternate_email');
    });
}

Indexes and foreign keys

We’ve covered how to create, modify, and delete columns. Let’s move on to indexing and relating them.

If you’re not familiar with indexes, your databases can survive if you just never use them, but they’re pretty important for performance optimization and for some data integrity controls with regard to related tables. I’d recommend reading up on them, but if you absolutely must, you can skip this section for now.

// After columns are created...
$table->primary('primary_id'); // Primary key; unnecessary if used increments()
$table->primary(['first_name', 'last_name']); // Composite keys
$table->unique('email'); // Unique index
$table->unique('email', 'optional_custom_index_name'); // Unique index
$table->index('amount'); // Basic index
$table->index('amount', 'optional_custom_index_name'); // Basic index

$table->dropPrimary('contacts_id_primary');
$table->dropUnique('contacts_email_unique');
$table->dropIndex('optional_custom_index_name');

// If you pass an array of column names to dropIndex, it will
// guess the index names for you based on the generation rules
$table->dropIndex(['email', 'amount']);

$table->foreign('user_id')->references('id')->on('users');

$table->foreign('user_id')
    ->references('id')
    ->on('users')
    ->onDelete('cascade');

$table->dropForeign('contacts_user_id_foreign');

$table->dropForeign(['user_id']);

Creating a model factory

Model factories are located in database/factories. In Laravel 5.5 and later each factory is usually defined in its own class, with a key (name) and a closure defining how to create a new instance of the defined class. The $factory->define() method takes the factory name as the first parameter and a closure that’s run for each generation as the second parameter.

To generate a new factory class, use the Artisan make:factory command; just like with naming the factory keys, it’s also most common to name factory classes after the Eloquent models they’re meant to generate instances of:

php artisan make:factory ContactFactory

This will generate a new file within the database/factories directory called ContactFactory.php. The simplest factory we could define for a contact might look something like Example 5-8:

$factory->define(Contact::class, function (FakerGenerator $faker) {
    return [
        'name' => 'Lupita Smith',
        'email' => '[email protected]',
    ];
});

Now we can use the factory() global helper to create an instance of Contact in our seeding and testing:

// Create one
$contact = factory(Contact::class)->create();

// Create many
factory(Contact::class, 20)->create();

However, if we used that factory to create 20 contacts, all 20 would have the same information. That’s less useful.

We will get even more benefit from model factories when we take advantage of the instance of Faker that’s passed into the closure; Faker makes it easy to randomize the creation of structured fake data. The previous example now turns into Example 5-9.

$factory->define(Contact::class, function (FakerGenerator $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->email,
    ];
});

Now, every time we create a fake contact using this model factory, all of our properties will be randomly generated.

return ['email' => $faker->unique()->email];

Using a model factory

There are two primary contexts in which we’ll use model factories: testing, which we’ll cover in Chapter 12, and seeding, which we’ll cover here. Let’s write a seeder using a model factory; take a look at Example 5-10.

$post = factory(Post::class)->create([
    'title' => 'My greatest post ever',
]);

// Pro-level factory; but don't get overwhelmed!
factory(User::class, 20)->create()->each(function ($u) use ($post) {
    $post->comments()->save(factory(Comment::class)->make([
        'user_id' => $u->id,
    ]));
});

To create an object, we use the factory() global helper and pass it the name of the factory—which, as we just saw, is the name of the Eloquent class we’re generating an instance of. That returns the factory, and then we can run one of two methods on it: make() or create().

Both methods generate an instance of this specified model, using the definition in the factory file. The difference is that make() creates the instance but doesn’t (yet) save it to the database, whereas create() saves it to the database instantly. You can see both in use in the two examples in Example 5-10.

The second example will make more sense once we cover relationships in Eloquent later in this chapter.

Pro-level model factories

Now that we’ve covered the most common uses for and arrangements of model factories, let’s dive into some of the more complicated ways we can use them.

$factory->define(Contact::class, function (FakerGenerator $faker) {
    return [
        'name' => 'Lupita Smith',
        'email' => '[email protected]',
        'company_id' => function () {
            return factory(AppCompany::class)->create()->id;
        },
    ];
});

$factory->define(Contact::class, function (FakerGenerator $faker) {
    return [
        'name' => 'Lupita Smith',
        'email' => '[email protected]',
        'company_id' => function () {
            return factory(AppCompany::class)->create()->id;
        },
        'company_size' => function ($contact) {
            // Uses the "company_id" property generated above
            return AppCompany::find($contact['company_id'])->size;
        },
    ];
});

$factory->define(Contact::class, function (FakerGenerator $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->email,
    ];
});

$factory->define(Contact::class, function (FakerGenerator $faker) {
    return [
        'name' => $faker->name,
        'email' => $faker->email,
    ];
});

$factory->state(Contact::class, 'vip', [
    'vip' => true,
]);

$factory->state(Contact::class, 'vip', function (FakerGenerator $faker) {
    return [
        'vip' => true,
        'company' => $faker->company,
    ];
});

$vip = factory(Contact::class)->state('vip')->create();

$vips = factory(Contact::class, 3)->state('vip')->create();

Raw selects

The simplest of the specific DB methods is select(). You can run it without any additional parameters:

$users = DB::select('select * from users');

This will return an array of stdClass objects.

Parameter bindings and named bindings

Laravel’s database architecture allows for the use of PDO parameter binding, which protects your queries from potential SQL attacks. Passing a parameter to a statement is as simple as replacing the value in your statement with a ?, then adding the value to the second parameter of your call:

$usersOfType = DB::select(
    'select * from users where type = ?',
    [$type]
);

You can also name those parameters for clarity:

$usersOfType = DB::select(
    'select * from users where type = :type',
    ['type' => $userType]
);

Raw inserts

From here, the raw commands all look pretty much the same. Raw inserts look like this:

DB::insert(
    'insert into contacts (name, email) values (?, ?)',
    ['sally', '[email protected]']
);

Raw updates

Updates look like this:

$countUpdated = DB::update(
    'update contacts set status = ? where id = ?',
    ['donor', $id]
);

Raw deletes

And deletes look like this:

$countDeleted = DB::delete(
    'delete from contacts where archived = ?',
    [true]
);

Constraining methods

These methods take the query as it is and constrain it to return a smaller subset of possible data:

select()

Allows you to choose which columns you’re selecting:

$emails = DB::table('contacts')
    ->select('email', 'email2 as second_email')
    ->get();
// Or
$emails = DB::table('contacts')
    ->select('email')
    ->addSelect('email2 as second_email')
    ->get();

where()

Allows you to limit the scope of what’s being returned using WHERE. By default, the signature of the where() method is that it takes three parameters—the column, the comparison operator, and the value:

$newContacts = DB::table('contact')
    ->where('created_at', '>', now()->subDay())
    ->get();

However, if your comparison is =, which is the most common comparison, you can drop the second operator:

$vipContacts = DB::table('contacts')->where('vip',true)->get();

If you want to combine where() statements, you can either chain them after each other, or pass an array of arrays:

$newVips = DB::table('contacts')
    ->where('vip', true)
    ->where('created_at', '>', now()->subDay());
// Or
$newVips = DB::table('contacts')->where([
    ['vip', true],
    ['created_at', '>', now()->subDay()],
]);

orWhere()

Creates simple OR WHERE statements:

$priorityContacts = DB::table('contacts')
    ->where('vip', true)
    ->orWhere('created_at', '>', now()->subDay())
    ->get();

To create a more complex OR WHERE statement with multiple conditions, pass orWhere() a closure:

$contacts = DB::table('contacts')
    ->where('vip', true)
    ->orWhere(function ($query) {
        $query->where('created_at', '>', now()->subDay())
            ->where('trial', false);
    })
    ->get();

$canEdit = DB::table('users')
    ->where('admin', true)
    ->orWhere('plan', 'premium')
    ->where('is_plan_owner', true)
    ->get();

SELECT * FROM users
    WHERE admin = 1
    OR plan = 'premium'
    AND is_plan_owner = 1;

$canEdit = DB::table('users')
    ->where('admin', true)
    ->orWhere(function ($query) {
        $query->where('plan', 'premium')
            ->where('is_plan_owner', true);
    })
    ->get();

SELECT * FROM users
    WHERE admin = 1
    OR (plan = 'premium' AND is_plan_owner = 1);

whereBetween(colName, [low, high])

Allows you to scope a query to return only rows where a column is between two values (inclusive of the two values):

$mediumDrinks = DB::table('drinks')
    ->whereBetween('size', [6, 12])
    ->get();

The same works for whereNotBetween(), but it will select the inverse.

whereIn(colName, [1, 2, 3])

Allows you to scope a query to return only rows where a column value is in an explicitly provided list of options:

$closeBy = DB::table('contacts')
    ->whereIn('state', ['FL', 'GA', 'AL'])
    ->get();

The same works for whereNotIn(), but it will select the inverse.

whereNull(colName) and whereNotNull(colName)

Allow you to select only rows where a given column is NULL or is NOT NULL, respectively.

whereRaw()

Allows you to pass in a raw, unescaped string to be added after the WHERE statement:

$goofs = DB::table('contacts')->whereRaw('id = 12345')->get()

whereExists()

Allows you to select only rows that, when passed into a provided subquery, return at least one row. Imagine you only want to get those users who have left at least one comment:

$commenters = DB::table('users')
    ->whereExists(function ($query) {
        $query->select('id')
            ->from('comments')
            ->whereRaw('comments.user_id = users.id');
    })
    ->get();

distinct()

Selects only rows where the selected data is unique when compared to the other rows in the returned data. Usually this is paired with select(), because if you use a primary key, there will be no duplicated rows:

$lastNames = DB::table('contacts')->select('city')->distinct()->get();

Modifying methods

These methods change the way the query’s results will be output, rather than just limiting its results:

orderBy(colName, direction)

Orders the results. The second parameter may be either asc (the default, ascending order) or desc (descending order):

$contacts = DB::table('contacts')
    ->orderBy('last_name', 'asc')
    ->get();

groupBy() and having() or havingRaw()

Groups your results by a column. Optionally, having() and havingRaw() allow you to filter your results based on properties of the groups. For example, you could look for only cities with at least 30 people in them:

$populousCities = DB::table('contacts')
    ->groupBy('city')
    ->havingRaw('count(contact_id) > 30')
    ->get();

skip() and take()

Most often used for pagination, these allow you to define how many rows to return and how many to skip before starting the return—like a page number and a page size in a pagination system:

// returns rows 31-40
$page4 = DB::table('contacts')->skip(30)->take(10)->get();

latest(colName) and oldest(colName)

Sort by the passed column (or created_at if no column name is passed) in descending (latest()) or ascending (oldest()) order.

inRandomOrder()

Sorts the result randomly.

Conditional methods

There are two methods, available in Laravel 5.2 and later, that allow you to conditionally apply their “contents” (a closure you pass to them) based on the Boolean state of a value you pass in:

when()

Given a truthy first parameter, applies the query modification contained in the closure; given a falsy first parameter, it does nothing. Note that the first parameter could be a Boolean (e.g., $ignoreDrafts, set to true or false), an optional value ($status, pulled from user input and defaulting to null), or a closure that returns either; what matters is that it evaluates to truthy or falsy. For example:

$status = request('status'); // Defaults to null if not set

$posts = DB::table('posts')
    ->when($status, function ($query) use ($status) {
        return $query->where('status', $status);
    })
    ->get();

// Or
$posts = DB::table('posts')
    ->when($ignoreDrafts, function ($query) {
        return $query->where('draft', false);
    })
    ->get();

You can also pass a third parameter, another closure, which will only be applied if the first parameter is falsy.

unless()

The exact inverse of when(). If the first parameter is falsy, it will run the second closure.

Ending/returning methods

These methods stop the query chain and trigger the execution of the SQL query. Without one of these at the end of the query chain, your return will always just be an instance of the query builder; chain one of these onto a query builder and you’ll actually get a result:

get()

Gets all results for the built query:

$contacts = DB::table('contacts')->get();
$vipContacts = DB::table('contacts')->where('vip', true)->get();

first() and firstOrFail()

Get only the first result—like get(), but with a LIMIT 1 added:

$newestContact = DB::table('contacts')
    ->orderBy('created_at', 'desc')
    ->first();

first() fails silently if there are no results, whereas firstOrFail() will throw an exception.

If you pass an array of column names to either method, it will return the data for just those columns instead of all columns.

find(id) and findOrFail(id)

Like first(), but you pass in an ID value that corresponds to the primary key to look up. find() fails silently if a row with that ID doesn’t exist, while findOrFail() will throw an exception:

$contactFive = DB::table('contacts')->find(5);

value()

Plucks just the value from a single field from the first row. Like first(), but if you only want a single column:

$newestContactEmail = DB::table('contacts')
    ->orderBy('created_at', 'desc')
    ->value('email');

count()

Returns an integer count of all of the matching results:

$countVips = DB::table('contacts')
    ->where('vip', true)
    ->count();

min() and max()

Return the minimum or maximum value of a particular column:

$highestCost = DB::table('orders')->max('amount');

sum() and avg()

Return the sum or average of all of the values in a particular column:

$averageCost = DB::table('orders')
    ->where('status', 'completed')
    ->avg('amount');

dd() and dump()

Dump the underlying the underlying SQL query and the bindings, and, if using dd(), ends the script.

DB::table('users')->where('name', 'Wilbur Powery')->dd();

// "select * from "users" where "name" = ?"
// array:1 [ 0 => "Wilbur Powery"]

Writing raw queries inside query builder methods with DB::raw

You’ve already seen a few custom methods for raw statements—for example, select() has a selectRaw() counterpart that allows you to pass in a string for the query builder to place after the WHERE statement.

You can also, however, pass in the result of a DB::raw() call to almost any method in the query builder to achieve the same result:

$contacts = DB::table('contacts')
    ->select(DB::raw('*, (score * 100) AS integer_score'))
    ->get();

Joins

Joins can sometimes be a pain to define, and there’s only so much a framework can do to make them simpler, but the query builder does its best. Let’s look at a sample:

$users = DB::table('users')
    ->join('contacts', 'users.id', '=', 'contacts.user_id')
    ->select('users.*', 'contacts.name', 'contacts.status')
    ->get();

The join() method creates an inner join. You can also chain together multiple joins one after another, or use leftJoin() to get a left join.

Finally, you can create more complex joins by passing a closure into the join() method:

DB::table('users')
    ->join('contacts', function ($join) {
        $join
            ->on('users.id', '=', 'contacts.user_id')
            ->orOn('users.id', '=', 'contacts.proxy_user_id');
    })
    ->get();

Unions

You can union two queries (join their results together into one result set) by creating them first and then using the union() or unionAll() method:

$first = DB::table('contacts')
    ->whereNull('first_name');

$contacts = DB::table('contacts')
    ->whereNull('last_name')
    ->union($first)
    ->get();

Inserts

The insert() method is pretty simple. Pass it an array to insert a single row or an array of arrays to insert multiple rows, and use insertGetId() instead of insert() to get the autoincrementing primary key ID back as a return:

$id = DB::table('contacts')->insertGetId([
    'name' => 'Abe Thomas',
    'email' => '[email protected]',
]);

DB::table('contacts')->insert([
    ['name' => 'Tamika Johnson', 'email' => '[email protected]'],
    ['name' => 'Jim Patterson', 'email' => '[email protected]'],
]);

Updates

Updates are also simple. Create your update query and, instead of get() or first(), just use update() and pass it an array of parameters:

DB::table('contacts')
    ->where('points', '>', 100)
    ->update(['status' => 'vip']);

You can also quickly increment and decrement columns using the increment() and decrement() methods. The first parameter of each is the column name, and the second (optional) is the number to increment/decrement by:

DB::table('contacts')->increment('tokens', 5);
DB::table('contacts')->decrement('tokens');

Deletes

Deletes are even simpler. Build your query and then end it with delete():

DB::table('users')
    ->where('last_login', '<', now()->subYear())
    ->delete();

You can also truncate the table, which deletes every row and also resets the autoincrementing ID:

DB::table('contacts')->truncate();

JSON operations

If you have JSON columns, you can update or select rows based on aspects of the JSON structure by using the arrow syntax to traverse children:

// Select all records where the "isAdmin" property of the "options"
// JSON column is set to true
DB::table('users')->where('options->isAdmin', true)->get();

// Update all records, setting the "verified" property
// of the "options" JSON column to true
DB::table('users')->update(['options->isVerified', true]);

This is a new feature since Laravel 5.3.

Table name

The default behavior for table names is that Laravel “snake cases” and pluralizes your class name, so SecondaryContact would access a table named secondary_contacts. If you’d like to customize the name, set the $table property explicitly on the model:

    protected $table = 'contacts_secondary';

Primary key

Laravel assumes, by default, that each table will have an autoincrementing integer primary key, and it will be named id.

If you want to change the name of your primary key, change the $primaryKey property:

    protected $primaryKey = 'contact_id';

And if you want to set it to be nonincrementing, use:

    public $incrementing = false;

    public $timestamps = false;

    protected $dateFormat = 'U';

Get one

Like we covered earlier in the chapter, you can use first() to return only the first record from a query, or find() to pull just the record with the provided ID. For either, if you append “OrFail” to the method name, it will throw an exception if there are no matching results. This makes findOrFail() a common tool for looking up an entity by a URL segment (or throwing an exception if a matching entity doesn’t exist), like you can see in Example 5-19.

// ContactController
public function show($contactId)
{
    return view('contacts.show')
        ->with('contact', Contact::findOrFail($contactId));
}

Any method intended to return a single record (first(), firstOrFail(), find(), or findOrFail()) will return an instance of the Eloquent class. So, Contact::first() will return an instance of the class Contact with the data from the first row in the table filling it out.

Get many

get() works with Eloquent just like it does in normal query builder calls—build a query and call get() at the end to get the results:

$vipContacts = Contact::where('vip', true)->get();

However, there is an Eloquent-only method, all(), which you’ll often see people use when they want to get an unfiltered list of all data in the table:

$contacts = Contact::all();

The other thing that’s different about Eloquent’s get() method (versus all()) is that, prior to Laravel 5.3, it returned an array of models instead of a collection. In 5.3 and later, they both return collections.

Chunking responses with chunk()

If you’ve ever needed to process a large amount (thousands or more) of records at a time, you may have run into memory or locking issues. Laravel makes it possible to break your requests into smaller pieces (chunks) and process them in batches, keeping the memory load of your large request smaller. Example 5-20 illustrates the use of chunk() to split a query into “chunks” of 100 records each.

Contact::chunk(100, function ($contacts) {
    foreach ($contacts as $contact)  {
        // Do something with $contact
    }
});

Aggregates

The aggregates that are available on the query builder are available on Eloquent queries as well. For example:

$countVips = Contact::where('vip', true)->count();
$sumVotes = Contact::sum('votes');
$averageSkill = User::avg('skill_level');

Inserts

There are two primary ways to insert a new record using Eloquent.

First, you can create a new instance of your Eloquent class, set your properties manually, and call save() on that instance, like in Example 5-21.

$contact = new Contact;
$contact->name = 'Ken Hirata';
$contact->email = '[email protected]';
$contact->save();

// or

$contact = new Contact([
    'name' => 'Ken Hirata',
    'email' => '[email protected]',
]);
$contact->save();

// or

$contact = Contact::make([
    'name' => 'Ken Hirata',
    'email' => '[email protected]',
]);
$contact->save();

Until you save(), this instance of Contact represents the contact fully—except it has never been saved to the database. That means it doesn’t have an id, if the application quits it won’t persist, and it doesn’t have its created_at and updated_at values set.

You can also pass an array to Model::create(), as shown in Example 5-22. Unlike make(), create() saves the instance to the database as soon as it’s called.

$contact = Contact::create([
    'name' => 'Keahi Hale',
    'email' => '[email protected]',
]);

Also be aware that in any context where you are passing an array (to new Model(), Model::make(), Model::create(), or Model::update()), every property you set via Model::create() has to be approved for “mass assignment,” which we’ll cover shortly. This is not necessary with the first example in Example 5-21, where you assign each property individually.

Note that if you’re using Model::create(), you don’t need to save() the instance—that’s handled as a part of the model’s create() method.

Updates

Updating records looks very similar to inserting. You can get a specific instance, change its properties, and then save, or you can make a single call and pass an array of updated properties. Example 5-23 illustrates the first approach.

$contact = Contact::find(1);
$contact->email = '[email protected]';
$contact->save();

Since this record already exists, it will already have a created_at timestamp and an id, which will stay the same, but the updated_at field will be changed to the current date and time. Example 5-24 illustrates the second approach.

Contact::where('created_at', '<', now()->subYear())
    ->update(['longevity' => 'ancient']);

// or

$contact = Contact::find(1);
$contact->update(['longevity' => 'ancient']);

This method expects an array where each key is the column name and each value is the column value.

Mass assignment

We’ve looked at a few examples of how to pass arrays of values into Eloquent class methods. However, none of these will actually work until you define which fields are “fillable” on the model.

The goal of this is to protect you from (possibly malicious) user input accidentally setting new values on fields you don’t want changed. Consider the common scenario in Example 5-25.

// ContactController
public function update(Contact $contact, Request $request)
{
    $contact->update($request->all());
}

If you’re not familiar with the Illuminate Request object, Example 5-25 will take every piece of user input and pass it to the update() method. That all() method includes things like URL parameters and form inputs, so a malicious user could easily add some things in there, like id and owner_id, that you likely don’t want updated.

Thankfully, that won’t actually work until you define your model’s fillable fields. You can either whitelist the fillable fields, or blacklist the “guarded” fields to determine which fields can or cannot be edited via “mass assignment”—that is, by passing an array of values into either create() or update(). Note that nonfillable properties can still be changed by direct assignment (e.g., $contact->password = 'abc';). Example 5-26 shows both approaches.

class Contact
{
    protected $fillable = ['name', 'email'];

    // or

    protected $guarded = ['id', 'created_at', 'updated_at', 'owner_id'];
}

Contact::create($request->only('name', 'email'));

firstOrCreate() and firstOrNew()

Sometimes you want to tell your application, “Get me an instance with these properties, or if it doesn’t exist, create it.” This is where the firstOr*() methods come in.

The firstOrCreate() and firstOrNew() methods take an array of keys and values as their first parameter:

$contact = Contact::firstOrCreate(['email' => '[email protected]']);

They’ll both look for and retrieve the first record matching those parameters, and if there are no matching records, they’ll create an instance with those properties; firstOrCreate() will persist that instance to the database and then return it, while firstOrNew() will return it without saving it.

If you pass an array of values as the second parameter, those values will be added to the created entry (if it’s created) but won’t be used to look up whether the entry exists.

Normal deletes

The simplest way to delete a model record is to call the delete() method on the instance itself:

$contact = Contact::find(5);
$contact->delete();

However, if you only have the ID, there’s no reason to look up an instance just to delete it; you can pass an ID or an array of IDs to the model’s destroy() method to delete them directly:

Contact::destroy(1);
// or
Contact::destroy([1, 5, 7]);

Finally, you can delete all of the results of a query:

Contact::where('updated_at', '<', now()->subYear())->delete();

Soft deletes

Soft deletes mark database rows as deleted without actually deleting them from the database. This gives you the ability to inspect them later, to have records that show more than “no information, deleted” when displaying historic information, and to allow your users (or admins) to restore some or all data.

The hard part about handcoding an application with soft deletes is that every query you ever write will need to exclude the soft-deleted data. Thankfully, if you use Eloquent’s soft deletes, every query you ever make will be scoped to ignore soft deletes by default, unless you explicitly ask to bring them back.

Eloquent’s soft delete functionality requires a deleted_at column to be added to the table. Once you enable soft deletes on that Eloquent model, every query you ever write (unless you explicitly include soft-deleted records) will be scoped to ignore soft-deleted rows.

Schema::table('contacts', function (Blueprint $table) {
    $table->softDeletes();
});

<?php

use IlluminateDatabaseEloquentModel;
use IlluminateDatabaseEloquentSoftDeletes;

class Contact extends Model
{
    use SoftDeletes; // use the trait

    protected $dates = ['deleted_at']; // mark this column as a date
}

$allHistoricContacts = Contact::withTrashed()->get();

if ($contact->trashed()) {
    // do something
}

$deletedContacts = Contact::onlyTrashed()->get();

$contact->restore();

// or

Contact::onlyTrashed()->where('vip', true)->restore();

$contact->forceDelete();

// or

Contact::onlyTrashed()->forceDelete();

Local scopes

Local scopes are the simplest to understand. Let’s take this example:

$activeVips = Contact::where('vip', true)->where('trial', false)->get();

First of all, if we write this combination of query methods over and over, it will get tedious. But additionally, the knowledge of how to define someone being an “active VIP” is now spread around our application. We want to centralize that knowledge. What if we could just write this?

$activeVips = Contact::activeVips()->get();

We can—it’s called a local scope. And it’s easy to define on the Contact class, as you can see in Example 5-29.

class Contact
{
    public function scopeActiveVips($query)
    {
        return $query->where('vip', true)->where('trial', false);
    }

To define a local scope, we add a method to the Eloquent class that begins with “scope” and then contains the title-cased version of the scope name. This method is passed a query builder and needs to return a query builder, but of course you can modify the query before returning—that’s the whole point.

You can also define scopes that accept parameters, as shown in Example 5-30.

class Contact
{
    public function scopeStatus($query, $status)
    {
        return $query->where('status', $status);
    }

And you use them in the same way, just passing the parameter to the scope:

$friends = Contact::status('friend')->get();

In Laravel 5.8+, you can also chain orWhere() between two local scopes.

$activeOrVips = Contact::active()->orWhere()->vip()->get();

Global scopes

Remember how we talked about soft deletes only working if you scope every query on the model to ignore the soft-deleted items? That’s a global scope. And we can define our own global scopes, which will be applied on every query made from a given model.

There are two ways to define a global scope: using a closure or using an entire class. In each, you’ll register the defined scope in the model’s boot() method. Let’s start with the closure method, illustrated in Example 5-31.

...
class Contact extends Model
{
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope('active', function (Builder $builder) {
            $builder->where('active', true);
        });
    }

That’s it. We just added a global scope named active, and now every query on this model will be scoped to only rows with active set to true.

Next, let’s try the longer way, as shown in Example 5-32. Create a class that implements IlluminateDatabaseEloquentScope, which means it will have an apply() method that takes an instance of a query builder and an instance of the model.

<?php

namespace AppScopes;

use IlluminateDatabaseEloquentScope;
use IlluminateDatabaseEloquentModel;
use IlluminateDatabaseEloquentBuilder;

class ActiveScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        return $builder->where('active', true);
    }
}

To apply this scope to a model, once again override the parent’s boot() method and call addGlobalScope() on the class using static, as shown in Example 5-33.

<?php

use AppScopesActiveScope;
use IlluminateDatabaseEloquentModel;

class Contact extends Model
{
    protected static function boot()
    {
        parent::boot();

        static::addGlobalScope(new ActiveScope);
    }
}

$allContacts = Contact::withoutGlobalScope('active')->get();

Contact::withoutGlobalScope(ActiveScope::class)->get();

Contact::withoutGlobalScopes([ActiveScope::class, VipScope::class])->get();

Contact::withoutGlobalScopes()->get();

Accessors

Accessors allow you to define custom attributes on your Eloquent models for when you are reading data from the model instance. This may be because you want to change how a particular column is output, or because you want to create a custom attribute that doesn’t exist in the database table at all.

You define an accessor by writing a method on your model with the following structure: get{PascalCasedPropertyName}Attribute. So, if your property name is first_name, the accessor method would be named getFirstNameAttribute.

Let’s try it out. First, we’ll decorate a preexisting column (Example 5-34).

// Model definition:
class Contact extends Model
{
    public function getNameAttribute($value)
    {
        return $value ?: '(No name provided)';
    }
}

// Accessor usage:
$name = $contact->name;

But we can also use accessors to define attributes that never existed in the database, as seen in Example 5-35.

// Model definition:
class Contact extends Model
{
    public function getFullNameAttribute()
    {
        return $this->first_name . ' ' . $this->last_name;
    }
}

// Accessor usage:
$fullName = $contact->full_name;

Mutators

Mutators work the same way as accessors, except they’re for determining how to process setting the data instead of getting it. Just like with accessors, you can use them to modify the process of writing data to existing columns, or to allow for setting columns that don’t exist in the database.

You define a mutator by writing a method on your model with the following structure: set{PascalCasedPropertyName}Attribute. So, if your property name is first_name, the mutator method would be named setFirstNameAttribute.

Let’s try it out. First, we’ll add a constraint to updating a preexisting column (Example 5-36).

// Defining the mutator
class Order extends Model
{
    public function setAmountAttribute($value)
    {
        $this->attributes['amount'] = $value > 0 ? $value : 0;
    }
}

// Using the mutator
$order->amount = '15';

This reveals that the way mutators are expected to “set” data on the model is by setting it in $this->attributes with the column name as the key.

Now let’s add a proxy column for setting, as shown in Example 5-37.

// Defining the mutator
class Order extends Model
{
    public function setWorkgroupNameAttribute($workgroupName)
    {
        $this->attributes['email'] = "{$workgroupName}@ourcompany.com";
    }
}

// Using the mutator
$order->workgroup_name = 'jstott';

As you can probably guess, it’s relatively uncommon to create a mutator for a non-existent column, because it can be confusing to set one property and have it change a different column—but it is possible.

Attribute casting

You can probably imagine writing accessors to cast all of your integer-type fields as integers, encode and decode JSON to store in a TEXT column, or convert TINYINT 0 and 1 to and from Boolean values.

Thankfully, there’s a system for that in Eloquent already. It’s called attribute casting, and it allows you to define that any of your columns should always be treated, both on read and on write, as if they are of a particular data type. The options are listed in Table 5-1.

Example 5-38 shows how you use attribute casting in your model.

class Contact
{
    protected $casts = [
        'vip' => 'boolean',
        'children_names' => 'array',
        'birthday' => 'date',
    ];
}

Date mutators

You can choose for particular columns to be mutated as timestamp columns by adding them to the dates array, as seen in Example 5-39.

class Contact
{
    protected $dates = [
        'met_at',
    ];
}

By default, this array contains created_at and updated_at, so adding entries to dates just adds them to the list.

However, there’s no difference between adding columns to this list and adding them to $this->casts as timestamp, so this is becoming a bit of an unnecessary feature now that attribute casting can cast timestamps (new since Laravel 5.2).

Introducing the base collection

Laravel’s Collection objects (IlluminateSupportCollection) are a little bit like arrays on steroids. The methods they expose on array-like objects are so helpful that, once you’ve been using them for a while, you’ll likely want to pull them into non-Laravel projects—which you can, with the Tightenco/Collect package.

The simplest way to create a collection is to use the collect() helper. Either pass an array in, or use it without arguments to create an empty collection and then push items into it later. Let’s try it:

$collection = collect([1, 2, 3]);

Now let’s say we want to filter out any even numbers:

$odds = $collection->reject(function ($item) {
    return $item % 2 === 0;
});

Or what if we want to get a version of the collection where each item is multiplied by 10? We can do that as follows:

$multiplied = $collection->map(function ($item) {
    return $item * 10;
});

We can even get only the even numbers, multiply them all by 10, and reduce them to a single number by sum():

$sum = $collection
    ->filter(function ($item) {
        return $item % 2 == 0;
    })->map(function ($item) {
        return $item * 10;
    })->sum();

As you can see, collections provide a series of methods, which can optionally be chained, to perform functional operations on your arrays. They provide the same functionality as native PHP methods like array_map() and array_reduce(), but you don’t have to memorize PHP’s unpredictable parameter order, and the method chaining syntax is infinitely more readable.

There are more than 60 methods available on the Collection class, including methods like max(), whereIn(), flatten(), and flip(), and there’s not enough space to cover them all here. We’ll talk about more in Chapter 17, or you can check out the Laravel collections docs to see all of the methods.

What Eloquent collections add

Each Eloquent collection is a normal collection, but extended for the particular needs of a collection of Eloquent results.

Once again, there’s not enough room here to cover all of the additions, but they’re centered around the unique aspects of interacting with a collection not just of generic objects, but objects meant to represent database rows.

For example, every Eloquent collection has a method called modelKeys() that returns an array of the primary keys of every instance in the collection. find($id) looks for an instance that has the primary key of $id.

One additional feature available here is the ability to define that any given model should return its results wrapped in a specific class of collection. So, if you want to add specific methods to any collection of objects of your Order model—possibly related to summarizing the financial details of your orders—you could create a custom OrderCollection that extends IlluminateDatabaseEloquentCollection, and then register it in your model, as shown in Example 5-40.

...
class OrderCollection extends Collection
{
    public function sumBillableAmount()
    {
        return $this->reduce(function ($carry, $order) {
            return $carry + ($order->billable ? $order->amount : 0);
        }, 0);
    }
}

...
class Order extends Model
{
    public function newCollection(array $models = [])
    {
        return new OrderCollection($models);
    }

Now, any time you get back a collection of Orders (e.g., from Order::all()), it’ll actually be an instance of the OrderCollection class:

$orders = Order::all();
$billableAmount = $orders->sumBillableAmount();

Returning models directly from route methods

Laravel’s router eventually converts everything routes return to a string, so there’s a clever trick you can use. If you return the result of an Eloquent call in a controller, it will be automatically cast to a string, and therefore returned as JSON. That means a JSON-returning route can be as simple as either of the ones in Example 5-41.

// routes/web.php
Route::get('api/contacts', function () {
    return Contact::all();
});

Route::get('api/contacts/{id}', function ($id) {
    return Contact::findOrFail($id);
});

Hiding attributes from JSON

It’s very common to use JSON returns in APIs, and it’s very common to want to hide certain attributes in these contexts, so Eloquent makes it easy to hide any attributes every time you cast to JSON.

You can either blacklist attributes, hiding the ones you list:

class Contact extends Model
{
    public $hidden = ['password', 'remember_token'];

or whitelist attributes, showing only the ones you list:

class Contact extends Model
{
    public $visible = ['name', 'email', 'status'];

This also works for relationships:

class User extends Model
{
    public $hidden = ['contacts'];

    public function contacts()
    {
        return $this->hasMany(Contact::class);
    }

$user = User::with('contacts')->first();

There might be times when you want to make an attribute visible just for a single call. That’s possible, with the Eloquent method makeVisible():

$array = $user->makeVisible('remember_token')->toArray();

class Contact extends Model
{
    protected $appends = ['full_name'];

    public function getFullNameAttribute()
    {
        return "{$this->first_name} {$this->last_name}";
    }
}