Model Relationships

Relationships - 图1

Relationships between Models

There are four types of relationships: one-on-one, one-to-many, many-to-one and many-to-many. The relationship may be unidirectional or bidirectional, and each can be simple (a one to one model) or more complex (a combination of models). The model manager manages foreign key constraints for these relationships, the definition of these helps referential integrity as well as easy and fast access of related records to a model. Through the implementation of relations, it is easy to access data in related models from each record in a uniform way.

Unidirectional relationships

Unidirectional relations are those that are generated in relation to one another but not vice versa.

Bidirectional relations

The bidirectional relations build relationships in both models and each model defines the inverse relationship of the other.

Defining relationships

In Phalcon, relationships must be defined in the initialize() method of a model. The methods belongsTo(), hasOne(), hasMany() and hasManyToMany() define the relationship between one or more fields from the current model to fields in another model. Each of these methods requires 3 parameters: local fields, referenced model, referenced fields.

MethodDescription
hasManyDefines a 1-n relationship
hasOneDefines a 1-1 relationship
belongsToDefines a n-1 relationship
hasManyToManyDefines a n-n relationship

The following schema shows 3 tables whose relations will serve us as an example regarding relationships:

  1. CREATE TABLE robots (
  2.     id int(10) unsigned NOT NULL AUTO_INCREMENT,
  3.     name varchar(70) NOT NULL,
  4.     type varchar(32) NOT NULL,
  5.     year int(11) NOT NULL,
  6.     PRIMARY KEY (id)
  7. );
  9. CREATE TABLE robots_parts (
  10.     id int(10) unsigned NOT NULL AUTO_INCREMENT,
  11.     robots_id int(10) NOT NULL,
  12.     parts_id int(10) NOT NULL,
  13.     created_at DATE NOT NULL,
  14.     PRIMARY KEY (id),
  15.     KEY robots_id (robots_id),
  16.     KEY parts_id (parts_id)
  17. );
  19. CREATE TABLE parts (
  20.     id int(10) unsigned NOT NULL AUTO_INCREMENT,
  21.     name varchar(70) NOT NULL,
  22.     PRIMARY KEY (id)
  23. );
  • The model Robots has many RobotsParts.
  • The model Parts has many RobotsParts.
  • The model RobotsParts belongs to both Robots and Parts models as a many-to-one relation.
  • The model Robots has a relation many-to-many to Parts through RobotsParts.Check the EER diagram to understand better the relations:

Relationships - 图2

The models with their relations could be implemented as follows:

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class Robots extends Model
  8. {
  9.     public $id;
  11.     public $name;
  13.     public function initialize()
  14.     {
  15.         $this->hasMany(
  16.             'id',
  17.             RobotsParts::class,
  18.             'robots_id'
  19.         );
  20.     }
  21. }
  1. <?php
  3. use Phalcon\Mvc\Model;
  4. use Store\Toys\RobotsParts;
  6. class Parts extends Model
  7. {
  8.     public $id;
  10.     public $name;
  12.     public function initialize()
  13.     {
  14.         $this->hasMany(
  15.             'id',
  16.             RobotsParts::class,
  17.             'parts_id'
  18.         );
  19.     }
  20. }
  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class RobotsParts extends Model
  8. {
  9.     public $id;
  11.     public $robots_id;
  13.     public $parts_id;
  15.     public function initialize()
  16.     {
  17.         $this->belongsTo(
  18.             'robots_id',
  19.             Robots::class,
  20.             'id'
  21.         );
  23.         $this->belongsTo(
  24.             'parts_id',
  25.             \Parts::class,
  26.             'id'
  27.         );
  28.     }
  29. }

The first parameter indicates the field of the local model used in the relationship; the second indicates the name of the referenced model and the third the field name in the referenced model. You could also use arrays to define multiple fields in the relationship.

Many to many relationships require 3 models and define the attributes involved in the relationship:

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class Robots extends Model
  8. {
  9.     public $id;
  11.     public $name;
  13.     public function initialize()
  14.     {
  15.         $this->hasManyToMany(
  16.             'id',
  17.             RobotsParts::class,
  18.             'robots_id', 'parts_id',
  19.             \Parts::class,
  20.             'id'
  21.         );
  22.     }
  23. }

Relationships with parameters

Depending on the needs of our application we might want to store data in one table, that describe different behaviors. For instance you might want to only have a table called parts which has a field type describing the type of the part.

Using relationships, we can get only those parts that relate to our Robot that are of certain type. Defining that constraint in our relationship allows us to let the model do all the work.

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class Robots extends Model
  8. {
  9.     public $id;
  11.     public $name;
  13.     public $type;
  15.     public function initialize()
  16.     {
  17.         $this->hasMany(
  18.             'id',
  19.             Parts::class,
  20.             'robotId',
  21.             [
  22.                 'reusable' => true, // cache related data
  23.                 'alias'    => 'mechanicalParts',
  24.                 'params'   => [
  25.                     'conditions' => 'robotTypeId = :type:',
  26.                     'bind'       => [
  27.                        'type' => 4,
  28.                     ]
  29.                 ]
  30.             ]
  31.         );
  32.     }
  33. }

Multiple field relationships

There are times where relationships need to be defined on a combination of fields and not only one. Consider the following example:

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class Robots extends Model
  8. {
  9.     public $id;
  11.     public $name;
  13.     public $type;
  14. }

and

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class Parts extends Model
  8. {
  9.     public $id;
  11.     public $robotId;
  13.     public $robotType;
  15.     public $name;
  16. }

In the above we have a Robots model which has three properties. A unique id, a name and a type which defines what this robot is (mechnical, etc.); In the Parts model we also have a name for the part but also fields that tie the robot and its type with a specific part.

Using the relationships options discussed earlier, binding one field between the two models will not return the results we need. For that we can use an array in our relationship:

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. class Robots extends Model
  8. {
  9.     public $id;
  11.     public $name;
  13.     public $type;
  15.     public function initialize()
  16.     {
  17.         $this->hasOne(
  18.             ['id', 'type'],
  19.             Parts::class,
  20.             ['robotId', 'robotType'],
  21.             [
  22.                 'reusable' => true, // cache related data
  23.                 'alias'    => 'parts',
  24.             ]
  25.         );
  26.     }
  27. }

NOTE The field mappings in the relationship are one for one i.e. the first field of the source model array matches the first field of the target array etc. The field count must be identical in both source and target models.

Taking advantage of relationships

When explicitly defining the relationships between models, it is easy to find related records for a particular record.

  1. <?php
  3. use Store\Toys\Robots;
  5. $robot = Robots::findFirst(2);
  7. foreach ($robot->robotsParts as $robotPart) {
  8.     echo $robotPart->parts->name, "\n";
  9. }

Phalcon uses the magic methods set/get/__call to store or retrieve related data using relationships.

By accessing an attribute with the same name as the relationship will retrieve all its related record(s).

  1. <?php
  3. use Store\Toys\Robots;
  5. $robot = Robots::findFirst();
  7. // All the related records in RobotsParts
  8. $robotsParts = $robot->robotsParts;

Also, you can use a magic getter:

  1. <?php
  3. use Store\Toys\Robots;
  5. $robot = Robots::findFirst();
  7. // All the related records in RobotsParts
  8. $robotsParts = $robot->getRobotsParts();
  10. // Passing parameters
  11. $robotsParts = $robot->getRobotsParts(
  12.     [
  13.         'limit' => 5,
  14.     ]
  15. );

If the called method has a get prefix Phalcon\Mvc\Model will return a findFirst()/find() result. The following example compares retrieving related results with using magic methods and without:

  1. <?php
  3. use Store\Toys\Robots;
  5. $robot = Robots::findFirst(2);
  7. // Robots model has a 1-n (hasMany)
  8. // relationship to RobotsParts then
  9. $robotsParts = $robot->robotsParts;
  11. // Only parts that match conditions
  12. $robotsParts = $robot->getRobotsParts(
  13.     [
  14.         'created_at = :date:',
  15.         'bind' => [
  16.             'date' => '2015-03-15',
  17.         ],
  18.     ]
  19. );
  21. $robotPart = RobotsParts::findFirst(1);
  23. // RobotsParts model has a n-1 (belongsTo)
  24. // relationship to RobotsParts then
  25. $robot = $robotPart->robots;

Getting related records manually:

  1. <?php
  3. use Store\Toys\Robots;
  5. $robot = Robots::findFirst(2);
  7. // Robots model has a 1-n (hasMany)
  8. // relationship to RobotsParts, then
  9. $robotsParts = RobotsParts::find(
  10.     [
  11.         'robots_id = :id:',
  12.         'bind' => [
  13.             'id' => $robot->id,
  14.         ],
  15.     ]
  16. );
  18. // Only parts that match conditions
  19. $robotsParts = RobotsParts::find(
  20.     [
  21.         'robots_id = :id: AND created_at = :date:',
  22.         'bind' => [
  23.             'id'   => $robot->id,
  24.             'date' => '2015-03-15',
  25.         ],
  26.     ]
  27. );
  29. $robotPart = RobotsParts::findFirst(1);
  31. // RobotsParts model has a n-1 (belongsTo)
  32. // relationship to RobotsParts then
  33. $robot = Robots::findFirst(
  34.     [
  35.         'id = :id:',
  36.         'bind' => [
  37.             'id' => $robotPart->robots_id,
  38.         ],
  39.     ]
  40. );

The prefix get is used to find()/findFirst() related records. Depending on the type of relation it will usefind() or findFirst():

TypeDescriptionImplicit Method
Belongs-ToReturns a model instance of the related record directlyfindFirst
Has-OneReturns a model instance of the related record directlyfindFirst
Has-ManyReturns a collection of model instances of the referenced modelfind
Has-Many-to-ManyReturns a collection of model instances of the referenced model, it implicitly does ‘inner joins’ with the involved models(complex query)

You can also use the count prefix to return an integer denoting the count of the related records:

  1. <?php
  3. use Store\Toys\Robots;
  5. $robot = Robots::findFirst(2);
  7. echo sprintf(
  8.     "The robot has %d parts\n",
  9.     $robot->countRobotsParts()
  10. );

Aliasing Relationships

To explain better how aliases work, let’s check the following example:

The robots_similar table has the function to define what robots are similar to others:

  1. mysql> desc robots_similar;
  2. +-------------------+------------------+------+-----+---------+----------------+
  3. | Field             | Type             | Null | Key | Default | Extra          |
  4. +-------------------+------------------+------+-----+---------+----------------+
  5. | id                | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
  6. | robots_id         | int(10) unsigned | NO   | MUL | NULL    |                |
  7. | similar_robots_id | int(10) unsigned | NO   |     | NULL    |                |
  8. +-------------------+------------------+------+-----+---------+----------------+
  9. 3 rows in set (0.00 sec)

Both robots_id and similar_robots_id have a relation to the model Robots:

Relationships - 图3

A model that maps this table and its relationships is the following:

  1. <?php
  3. class RobotsSimilar extends \Phalcon\Mvc\Model
  4. {
  5.     public function initialize()
  6.     {
  7.         $this->belongsTo(
  8.             'robots_id',
  9.             \Store\Toys\Robots::class,
  10.             'id'
  11.         );
  13.         $this->belongsTo(
  14.             'similar_robots_id',
  15.             \Store\Toys\Robots::class,
  16.             'id'
  17.         );
  18.     }
  19. }

Since both relations point to the same model (Robots), obtain the records related to the relationship could not be clear:

  1. <?php
  3. $robotsSimilar = RobotsSimilar::findFirst();
  5. // Returns the related record based on the column (robots_id)
  6. // Also as is a belongsTo it's only returning one record
  7. // but the name 'getRobots' seems to imply that return more than one
  8. $robot = $robotsSimilar->getRobots();
  10. // but, how to get the related record based on the column (similar_robots_id)
  11. // if both relationships have the same name?

The aliases allow us to rename both relationships to solve these problems:

  1. <?php
  3. use Phalcon\Mvc\Model;
  5. class RobotsSimilar extends Model
  6. {
  7.     public function initialize()
  8.     {
  9.         $this->belongsTo(
  10.             'robots_id',
  11.             \Store\Toys\Robots::class,
  12.             'id',
  13.             [
  14.                 'alias' => 'Robot',
  15.             ]
  16.         );
  18.         $this->belongsTo(
  19.             'similar_robots_id',
  20.             \Store\Toys\Robots::class,
  21.             'id',
  22.             [
  23.                 'alias' => 'SimilarRobot',
  24.             ]
  25.         );
  26.     }
  27. }

With the aliasing we can get the related records easily. You can also use the getRelated() method to access the relationship using the alias name:

  1. <?php
  3. $robotsSimilar = RobotsSimilar::findFirst();
  5. // Returns the related record based on the column (robots_id)
  6. $robot = $robotsSimilar->getRobot();
  7. $robot = $robotsSimilar->robot;
  8. $robot = $robotsSimilar->getRelated('Robot');
  10. // Returns the related record based on the column (similar_robots_id)
  11. $similarRobot = $robotsSimilar->getSimilarRobot();
  12. $similarRobot = $robotsSimilar->similarRobot;
  13. $similarRobot = $robotsSimilar->getRelated('SimilarRobot');

Magic Getters vs. Explicit methods

Most IDEs and editors with auto-completion capabilities can not infer the correct types when using magic getters (both methods and properties). To overcome that, you can use a class docblock that specifies what magic actions are available, helping the IDE to produce a better auto-completion:

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  7. /**
  8.  * Model class for the robots table.
  9.  * @property Simple|RobotsParts[] $robotsParts
  10.  * @method   Simple|RobotsParts[] getRobotsParts($parameters = null)
  11.  * @method   integer              countRobotsParts()
  12.  */
  13. class Robots extends Model
  14. {
  15.     public $id;
  17.     public $name;
  19.     public function initialize()
  20.     {
  21.         $this->hasMany(
  22.             'id',
  23.             RobotsParts::class,
  24.             'robots_id'
  25.         );
  26.     }
  27. }

Conditionals

You can also create relationships based on conditionals. When querying based on the relationship the condition will be automatically appended to the query:

  1. <?php
  3. use Phalcon\Mvc\Model;
  5. // Companies have invoices issued to them (paid/unpaid)
  6. // Invoices model
  7. class Invoices extends Model
  8. {
  10. }
  12. // Companies model
  13. class Companies extends Model
  14. {
  15.     public function initialize()
  16.     {
  17.         // All invoices relationship
  18.         $this->hasMany(
  19.             'id',
  20.             Invoices::class,
  21.             'inv_id',
  22.             [
  23.                 'alias' => 'Invoices',
  24.             ]
  25.         );
  27.         // Paid invoices relationship
  28.         $this->hasMany(
  29.             'id',
  30.             Invoices::class,
  31.             'inv_id',
  32.             [
  33.                 'alias'  => 'InvoicesPaid',
  34.                 'params' => [
  35.                     'conditions' => "inv_status = 'paid'",
  36.                 ],
  37.             ]
  38.         );
  40.         // Unpaid invoices relationship + bound parameters
  41.         $this->hasMany(
  42.             'id',
  43.             Invoices::class,
  44.             'inv_id',
  45.             [
  46.                 'alias'  => 'InvoicesUnpaid',
  47.                 'params' => [
  48.                     'conditions' => "inv_status <> :status:",
  49.                     'bind'       => [
  50.                         'status' => 'unpaid',
  51.                     ],
  52.                 ],
  53.             ]
  54.         );
  55.     }
  56. }

Additionally, you can use the second parameter of getRelated() when accessing your relationship from your model object to further filter or order your relationship:

  1. <?php
  3. // Unpaid Invoices
  4. $company = Companies::findFirst(
  5.     [
  6.         'conditions' => 'id = :id:',
  7.         'bind'       => [
  8.             'id' => 1,
  9.         ],
  10.     ]
  11. );
  13. $unpaidInvoices = $company->InvoicesUnpaid;
  14. $unpaidInvoices = $company->getInvoicesUnpaid();
  15. $unpaidInvoices = $company->getRelated('InvoicesUnpaid');
  16. $unpaidInvoices = $company->getRelated(
  17.     'Invoices', 
  18.     [
  19.         'conditions' => "inv_status = 'paid'",
  20.     ]
  21. );
  23. // Also ordered
  24. $unpaidInvoices = $company->getRelated(
  25.     'Invoices', 
  26.     [
  27.         'conditions' => "inv_status = 'paid'",
  28.         'order'      => 'inv_created_date ASC',
  29.     ]
  30. );

Virtual Foreign Keys

By default, relationships do not act like database foreign keys, that is, if you try to insert/update a value without having a valid value in the referenced model, Phalcon will not produce a validation message. You can modify this behavior by adding a fourth parameter when defining a relationship.

The RobotsPart model can be changed to demonstrate this feature:

  1. <?php
  3. use Phalcon\Mvc\Model;
  5. class RobotsParts extends Model
  6. {
  7.     public $id;
  9.     public $robots_id;
  11.     public $parts_id;
  13.     public function initialize()
  14.     {
  15.         $this->belongsTo(
  16.             'robots_id',
  17.             \Store\Toys\Robots::class,
  18.             'id',
  19.             [
  20.                 'foreignKey' => true,
  21.             ]
  22.         );
  24.         $this->belongsTo(
  25.             'parts_id',
  26.             \Parts::class,
  27.             'id',
  28.             [
  29.                 'foreignKey' => [
  30.                     'message' => 'The part_id does not exist on the Parts model',
  31.                 ],
  32.             ]
  33.         );
  34.     }
  35. }

If you alter a belongsTo() relationship to act as foreign key, it will validate that the values inserted/updated on those fields have a valid value on the referenced model. Similarly, if a hasMany()/hasOne() is altered it will validate that the records cannot be deleted if that record is used on a referenced model.

  1. <?php
  3. use Phalcon\Mvc\Model;
  5. class Parts extends Model
  6. {
  7.     public function initialize()
  8.     {
  9.         $this->hasMany(
  10.             'id',
  11.             \RobotsParts::class,
  12.             'parts_id',
  13.             [
  14.                 'foreignKey' => [
  15.                     'message' => 'The part cannot be deleted because other robots are using it',
  16.                 ],
  17.             ]
  18.         );
  19.     }
  20. }

A virtual foreign key can be set up to allow null values as follows:

  1. <?php
  3. use Phalcon\Mvc\Model;
  5. class RobotsParts extends Model
  6. {
  7.     public $id;
  9.     public $robots_id;
  11.     public $parts_id;
  13.     public function initialize()
  14.     {
  15.         $this->belongsTo(
  16.             'parts_id',
  17.             \Parts::class,
  18.             'id',
  19.             [
  20.                 'foreignKey' => [
  21.                     'allowNulls' => true,
  22.                     'message'    => 'The part_id does not exist on the Parts model',
  23.                 ],
  24.             ]
  25.         );
  26.     }
  27. }

Cascade/Restrict actions

Relationships that act as virtual foreign keys by default restrict the creation/update/deletion of records to maintain the integrity of data:

  1. <?php
  3. namespace Store\Toys;
  5. use Phalcon\Mvc\Model;
  6. use Phalcon\Mvc\Model\Relation;
  8. class Robots extends Model
  9. {
  10.     public $id;
  12.     public $name;
  14.     public function initialize()
  15.     {
  16.         $this->hasMany(
  17.             'id',
  18.             Parts::class,
  19.             'robots_id',
  20.             [
  21.                 'foreignKey' => [
  22.                     'action' => Relation::ACTION_CASCADE,
  23.                 ],
  24.             ]
  25.         );
  26.     }
  27. }

The above code set up to delete all the referenced records (parts) if the master record (robot) is deleted.

Magic properties can be used to store a record and its related properties:

  1. <?php
  3. // Create an artist
  4. $artist = new Artists();
  6. $artist->name    = 'Shinichi Osawa';
  7. $artist->country = 'Japan';
  9. // Create an album
  10. $album = new Albums();
  12. $album->name   = 'The One';
  13. $album->artist = $artist; // Assign the artist
  14. $album->year   = 2008;
  16. // Save both records
  17. $album->save();

Saving a record and its related records in a has-many relation:

  1. <?php
  3. // Get an existing artist
  4. $artist = Artists::findFirst(
  5.     'name = "Shinichi Osawa"'
  6. );
  8. // Create an album
  9. $album = new Albums();
  11. $album->name   = 'The One';
  12. $album->artist = $artist;
  14. $songs = [];
  16. // Create a first song
  17. $songs[0]           = new Songs();
  18. $songs[0]->name     = 'Star Guitar';
  19. $songs[0]->duration = '5:54';
  21. // Create a second song
  22. $songs[1]           = new Songs();
  23. $songs[1]->name     = 'Last Days';
  24. $songs[1]->duration = '4:29';
  26. // Assign the songs array
  27. $album->songs = $songs;
  29. // Save the album + its songs
  30. $album->save();

Saving the album and the artist at the same time implicitly makes use of a transaction so if anything goes wrong with saving the related records, the parent will not be saved either. Messages are passed back to the user for information regarding any errors.

Note: Adding related entities by overloading the following methods is not possible:

  • Phalcon\Mvc\Model::beforeSave()
  • Phalcon\Mvc\Model::beforeCreate()
  • Phalcon\Mvc\Model::beforeUpdate()You need to overload Phalcon\Mvc\Model::save() for this to work from within a model.

Operations over Resultsets

If a resultset is composed of complete objects, model operations can be performed on those objects. For example:

  1. <?php
  3. /** @var RobotType $type */
  4. $type = $robots->getRelated('type');
  6. $type->name = 'Some other type';
  8. $result = $type->save();
  11. // Get the related robot type but only the `name` column
  12. $type = $robots->getRelated(
  13.     'type',
  14.     [
  15.         'columns' => 'name',
  16.     ]
  17. );
  19. $type->name = 'Some other type';
  21. // This will fail because `$type` is not a complete object
  22. $result = $type->save();

Instead of doing this:

  1. <?php
  3. $parts = $robots->getParts();
  5. foreach ($parts as $part) {
  6.     $part->stock      = 100;
  7.     $part->updated_at = time();
  9.     if ($part->update() === false) {
  10.         $messages = $part->getMessages();
  12.         foreach ($messages as $message) {
  13.             echo $message;
  14.         }
  16.         break;
  17.     }
  18. }

you can do this:

  1. <?php
  3. $robots->getParts()->update(
  4.     [
  5.         'stock'      => 100,
  6.         'updated_at' => time(),
  7.     ]
  8. );

update also accepts an anonymous function to filter what records must be updated:

  1. <?php
  3. $data = [
  4.     'stock'      => 100,
  5.     'updated_at' => time(),
  6. ];
  8. // Update all the parts except those whose type is basic
  9. $robots->getParts()->update(
  10.     $data,
  11.     function ($part) {
  12.         return ($part->type !== Part::TYPE_BASIC);
  13.     }
  14. );

Instead of doing this:

  1. <?php
  3. $parts = $robots->getParts();
  5. foreach ($parts as $part) {
  6.     if ($part->delete() === false) {
  7.         $messages = $part->getMessages();
  9.         foreach ($messages as $message) {
  10.             echo $message;
  11.         }
  13.         break;
  14.     }
  15. }

you can do this:

  1. <?php
  3. $robots->getParts()->delete();

delete() also accepts an anonymous function to filter what records must be deleted:

  1. <?php
  3. // Delete only whose stock is greater or equal than zero
  4. $robots->getParts()->delete(
  5.     function ($part) {
  6.         return ($part->stock >= 0);
  7.     }
  8. );