Runway provides two fieldtypes to let you manage Eloquent relationships within Statamic: Belongs To & Has Many.
You can not only use these fieldtypes to represent Eloquent relationships on your models but you can also use them to relate Eloquent models to entries/terms, it's almost like magic 🪄.
You can use the Belongs To fieldtype to relate to a single Eloquent model.
To configure the Belongs To fieldtype, you'll need to ensure you've created the belongsTo
relationship on your model:
// app/Models/Post.php public function author(){ return $this->belongsTo(Author::class);}
You'll next need to add the field to your resource's blueprint:
# resources/blueprints/post.yaml - handle: author_id field: max_items: 1 mode: default resource: author create: true display: 'Author' type: 'belongs_to'
Make sure resource
is set to the handle of the 'related resource' (in this case, the one for the Author
model). You should also ensure the handle of the field is set to the name of the Belongs To column in the database, like author_id
.
When using this fieldtype on Entries / Terms, you don't need to create an Eloquent relationship and you can name your field anything (it doesn't need to be in the format model_id
).
You can use the Has Many fieldtype to relate to multiple Eloquent models.
To configure the Has Many fieldtype, you'll need to ensure you've created a hasMany
/morphedByMany
relationship on your model:
// app/Models/Post.php public function categories(){ return $this->hasMany(Category::class);}
You'll next need to add the field to your resource's blueprint:
# resources/blueprints/post.yaml - handle: categories field: type: has_many resource: category mode: default display: Categories
Make sure resource
is set to the handle of the 'related resource' (in this case, the one for the Category
model). You should also ensure the handle of the field is the same as the name of the Eloquent relationship.
When using this fieldtype on Entries / Terms, you obviously don't need to create an Eloquent relationship so you can name your field anything.
If you'd like users to be able to re-orderable models in your Has Many field, you may set reorderable
to true
and specify the column you'd like to use to store the order.
If you're using a pivot table for the relationship, the order column must exist on the pivot table.
# resources/blueprints/post.yaml - handle: categories field: type: has_many resource: category mode: default display: Categories orderable: true // [tl! add] order_column: sort_order // [tl! add]
By default, Relationship Fieldtypes in Statamic have three modes: default
/select
/typeahead
.
However, the Has Many fieldtype offers an additional table
mode. This displays the related Eloquent models in a table (similar to listing tables used elsewhere in the Control Panel), allowing you to see more information about each model.
You may enable Table Mode by adjusting the mode
configuration option:
# resources/blueprints/post.yaml - handle: categories field: type: has_many resource: category mode: default // [tl! remove] mode: table // [tl! add] display: Categories
The title_format
configuration option allows you to specify a title format to be used when related models are displayed in the Control Panel.
You can even use Antlers when specifying a title_format
.
# resources/blueprints/post.yaml - handle: categories field: type: has_many resource: category mode: default display: Categories title_format: 'Category ID {{ id }}: {{ name }}' // [tl! add]
If you wish, you can configure additional relationships to be eager loaded with the field:
# resources/blueprints/post.yaml - handle: categories field: type: has_many resource: category mode: default display: Categories with: - 'parentCategory'