Model

Introduction

Each database table has a corresponding "Model" which is used to interact with that table. Models allow you to query for data in your tables, as well as insert new records into the table.

Before getting started, be sure to configure a database connection in config/database.php.

Defining Models

All the models live in the app/custom/Models directory. All the models must extend the app\framework\Component\Database\Model\Model class.

The easiest way to create a Model is by using the Framy Command:

php Framy make:model User

Model Conventions

Now let's look at the User Model, which we will use to get retrieve and store data in the users table.

<?php
namespace app\custom\Models;

use app\framework\Component\Database\Model\Model;

class User extends Model
{
    //
}

Table Names

Note that we did not specify the table name. By convention, the "snake case", plural name of the class will be used as the table name unless another name is explicitly specified. But this pluralization is currently very basic its just a snake case formatting and an appending "s".

So in this case Framy assumes that the User Model stores records in the users table. You may specify a custom table by defining a table property on your model:

<?php
namespace app\custom\Models;

use app\framework\Component\Database\Model\Model;

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

Default Attribute Values

If you would like to define the default values for some of your model's attributes, you may define an $attributes property on your model:

<?php
namespace app\custom\Models;

use app\framework\Component\Database\Model\Model;

class User extends Model
{
    /**
     * The model's default values for attributes.
     *
     * @var array
     */
    protected $attributes = [
        'isLoggedIn' => false,
    ];
}

Retrieving Models

Once you have created a model and its associated database table, you are ready to start retrieving data from your database. Think of each model as a powerful query builder allowing you to query the database table associated with the model. For example:

<?php

$users = User::all();

foreach ($users as $user) {
    echo $user->name;
}

Adding Additional Constraints

The Model all method will return all of the results in the model's table. Since each Model serves as a query builder, you may also add constraints to queries, and then use the get method to retrieve the results:

<?php
$users = User::where('created_at', '>', '2018-00-00')
    ->orderBy('name', 'DESC')
    ->take(10)
    ->get();

NOTE: Since all Models are query builders, you should review all of the methods available on the query builder. You may use any of these methods in your queries.

Retrieving Single Models / Aggregates

In addition to retrieving all of the records for a given table, you may also retrieve single records using find or first. Instead of returning a collection of models, these methods return a single model instance:

// Retrieve a model by its primary key...
$user = User::find(1);

// Retrieve the first model matching the query constraints...
$user = User::where('active', 1)->first();

You may also call the find method with an array of primary keys, which will return a ArrayObject of the matching records:

$users = User::find([1, 2, 3]);

Retrieving Aggregates

You may also use the count, sum, max, and other aggregate methods provided by the query builder. These methods return the appropriate scalar value instead of a full model instance:

$count = User::where('active', 1)->count();

$max = User::where('active', 1)->max('price');

Inserting & Updating Models

Inserts

To create a new record in the database, create a new model instance, set attributes on the model, then call the save method:

$user = new User;

$user->username = "Jon Doe";

$user->save();

When we call the save method, a record will be inserted into the database. The created_at and updated_at timestamps will automatically be set when the save method is called, so there is no need to set them manually.

Updates

The save method may also be used to update models that already exist in the database. To update a model, you should retrieve it, set any attributes you wish to update, and then call the save method. Again, the updated_at timestamp will automatically be updated, so there is no need to manually set its value:

$user = User::find(1);

$user->username = "Jon Doe";

$user->save();

Deleting Models

To delete a model, call the delete method on a model instance:

$user = User::find(1);

$user->delete();

Deleting An Existing Model By Key

In the example above, we are retrieving the model from the database before calling the delete method. However, if you know the primary key of the model, you may delete the model without retrieving it by calling the destroy method. In addition to a single primary key as its argument an array of primary keys is also possible:

User::destroy(1);

User::destroy([2,3]);