Relationships

Define relationship fields (opens new window) on your resource using the hasOne and hasMany methods.

$type->hasOne('user');
$type->hasMany('comments');

By default, the resource type that the relationship corresponds to will be the pluralized form of the relationship name. In the example above, the user relationship would correspond to the users resource type, while comments would correspond to comments. If you'd like to use a different resource type, call the type method:

$type->hasOne('author')
    ->type('people');

By default, the relationship will read and write to the relation on your model with the same name. If you'd like it to correspond to a different relation, use the property method:

$type->hasOne('author')
    ->property('user');

Resource Linkage

By default, to-one relationships will have resource linkage (opens new window), but to-many relationships will not. You can toggle this by calling the withLinkage or withoutLinkage methods.

$type->hasMany('users')
    ->withLinkage();

WARNING

Be careful when enabling linkage on to-many relationships as pagination is not supported.

Relationship Inclusion

To make a relationship available for inclusion (opens new window) via the include query parameter, call the includable method.

$type->hasOne('user')
    ->includable();

WARNING

Be careful when making to-many relationships includable as pagination is not supported.

Relationships included via the include query parameter are automatically eager-loaded (opens new window) by the adapter, and any type scopes are applied automatically. You can also apply additional scopes at the relationship level using the scope method:

use Tobyz\JsonApiServer\Context;

$type->hasOne('users')
    ->includable()
    ->scope(function ($query, Context $context) {
        $query->where('is_listed', true);
    });

To prevent a relationship from being eager-loaded, use the dontLoad method:

$type->hasOne('user')
    ->includable()
    ->dontLoad();

Polymorphic Relationships

Define a polymorphic relationship using the polymorphic method. Optionally you may provide an array of allowed resource types:

$type->hasOne('commentable')
    ->polymorphic();

$type->hasMany('taggable')
    ->polymorphic(['photos', 'videos']);

WARNING

Note that nested includes cannot be requested on polymorphic relationships.

Meta Information

You can add meta information to a relationship using the meta method:

$type->hasOne('user')
    ->meta('updatedAt', function ($model, $user, Context $context) {
        return $user->updated_at;
    });