More About Models

The API's concept of a model maps directly to a table and is concerned with your application's data. It is still a Phalcon Model as has all the attributes and features they contain. Things like validation, relationships and CRUD events should be referenced on the Phalcon site.

Show/Hide Fields on endpoints

Use the model to show or hide fields (even when sideloading). The basic approach the API takes is to build a list of all available fields in the model and remove anything explicitly blocked.

A hook is provided where you may specify a list of fields to block statically or dynamically. Here is an example of hiding a specific field

    /**
     * hide user_id in favor of parent id
     *
     * {@inheritDoc}
     *
     * @see \PhalconRest\API\BaseModel::loadBlockColumns()
     */
    public function loadBlockColumns()
    {
        //helpful since the parent auto loads a Parent Model's block columns as well
        parent::loadBlockColumns();

        // add this column to the existing list
        $this->setBlockColumns([
            'user_id'
        ]);
    }

Parent Tables

A unique feature of the API is to automatically merge in columns from a parent table for display on an endpoint. This has the advantage of reducing boilerplate code that is commonly needed to support these types of relationships. Imaging a User table that acts as a parent to an Employee table. You may want to hide the User table from API consumers and instead present the Employee table with all related columns merged into the Employee end point.

Consider the following table structure:

--------------                ------------
| users       |               | employees|
--------------                ------------
|id           |-||----------< |user_id   |
|first_name   |               |title     |  
|last_name    |               |salary    |
--------------                ------------

You can show the Employees endpoint with all fields from BOTH tables:

{
    "employees": 
[
    {
        "id": "768",
        "first_name": "Big",
        "last_name": "Boss",
        "salary": "100",
        "title": "Director"
    }
],
"meta": 
    {}
}

With the following code snippit in your model:

    //app/models/Employees.php
    /**
     * this model's parent model
     */
    public static $parentModel = 'Users';

    /**
     * define custom model relationship
     */
    public function initialize()
    {
        parent::initialize();
        $this->hasOne("user_id", "PhalconRest\Models\Users", "id", array(
            'alias' => 'Users'
        ));
    }

    //hide user_id in favor of parent id
    public function loadBlockColumns()
    {
        $this->setBlockColumns([
            'user_id'
        ]);
    }

Parent tables should automatically deal with CRUD operations on the parent and child tables. Now you can hide the parent end point and only deal with the child!.

Control API Behavior through Phalcon Model relationships

Phalcon's ORM provides a number of ways to relate models to each other. The API will provides built in behavior to express these relationships on the API with little or no coding. For example, if a model has a hasMany or belongsTo relationship defined, then the corresponding endpoint will auto side load related records is requested via the WITH query param.

A hasOne relationship will automatically merge the related table's fields into the end point record. This is much like the Parent feature described above but without the automatic data writing provided by the Parent feature. This behavior is also helpful when an endpoint needs to represent multiple tables as a single record w/o resorting to SQL trickery like views.