Download the PHP package tunecino/yii2-nested-rest without Composer

yii2-nested-rest

Adds nested resources routing support along with related actions and relationship handlers to the Yii RESTful API framework.

How It Works

This extension doesn't replace any of the built-in REST components. It is about a collection of helper actions and a custom UrlRule class designed to be used along with the default one:

To explain how it works, lets better go through an example:

If within the previous configurations we expect team and player to share a one-to-many relationship while player and skill shares a many-to-many relation within a junction table and having an extra column called level in that junction table then this extension may help achieving the following HTTP requests:

Installation

The preferred way to install this extension is through composer.

Either run

or add

to the require section of your composer.json file.

Configuration

By default, all the properties used by the custom UrlRule class in this extension will be used to generate multiple instances of the built-in yii\rest\UrlRule so basically both classes are sharing similar configurations.

Those are all the possible configurations that may be set to the UrlManager in the app config file:

As you may notice; by default; $patterns is pointing to 6 new actions different from the basic CRUD actions attached to the ActiveController class. Those are the helper actions included in this extension and you will need to manually declare them whenever needed inside your controllers or inside a BaseController from which all others should extend. Also note that by default we are expecting an OptionsAction attached to the related controller. That should be the case for any controller extending ActiveController or its child controllers. Otherwise, you should also implement \yii\rest\OptionsAction.

The following is an example of a full implementation within the controller::actions() function:

What you need to know

1. This doesn't support composite keys. In fact one of my main concerns when building this extension was to figure out a clean alternative to not have to build resources for composite keys related models like the ones mapping a junction table. check the example provided in section 8. for more details.

2. When defining relation names in the config file they should match the method names implemented inside your model (see Declaring Relations section in the Yii guide for more details). This extension will do the check and will throw an InvalidConfigException if they don't match but for performance reasons (check this) and because it make no sense to keep doing the same verification with each request when you already did correctly set a list of relations, this extension won't do that DB schema parsing anymore when the application is in production mode. in other words verification is made only whenYII_DEBUG is true.

3. By default, when you specify a relation 'abc' in the $relation property, its related name expected to be used in the URL endpoint should be 'abcs' (pluralized) while its controller is expected to be AbcController. This can be changed by configuring the $relation property to explicitly specify how to map the relation name used in endpoint URLs to its related controller ID. For example, if we had a relation defined inside the Team model class within a getJuniorCoaches() method we can do the following:

4. When it comes to linking many-to-many relations with extra columns in a junction table it is highly recommended to use via() instead of viaTable() so the intermediate class can be used by this extension to validate related attributes instead of using link() and saving data without performing the appropriate validations. Refer to the Relations via a Junction Table section in the Yii guide for more details.

5. When you do:

and the 'name' attribute is supposed to be loaded and saved along with the new created model while 'level' should be added in a related junction table. Then you should know this:

• If relation between both models is defined within via() , Yii::$app->request->bodyParams will be populated to to both models using the [load()](http://www.yiiframework.com/doc-2.0/yii-base-model.html#load()-detail) method:

• If relation is defined within viaTable() instead the script will try to do some guessing.

So when unexpected results happens or when attribute names are similar in model class and junction related class, it would be recommended to set the viaWrapper property. See the 'nested-create' action in the configuration section for more details.

6. When unlinking data, if the relation type between both models is _many_tomany related row in the junction table will be removed. Otherwise the concerned foreign key attribute will be set to NULL in its related column in database.

7. When a successful linking or unlinking request happens, a 204 response should be expected while a 304 response should tell that no change has been made like when asking to link two already linked models. When you try to link 2 models sharing a many_to_many relationship and both models are already linked no extra row will be added to related junction table: If the bodyRequest is empty you'll get a 304 response otherwise the bodyRequest content will be used to update the extra attributes found in the junction table and you'll get a 204 headers response.

8. When performing any HTTP request; lets say as example GET /players/9/skills/2; The custom UrlRule will redirect it by default to the route skill/nested-view (or other depending on your patterns) with those 4 extra attributes added to Yii::$app->request->queryParams:

Those may be useful when building your own actions or doing extra things like for example if we add the following inside app/models/skill :

a request like GET /players/9/skills or GET /players/9/skills/2 will also output the related data between both models that is stored in the related junction table: