Support polymorphic to-many relationships

[lindyhopchris]

Given a posts resource has a has-many relationship called media, that may contain images, audios and videos . The JSON:API resource object may look like this.

{
  "type": "posts",
  "id": "5",
  "relationships": {
    "media": {
      "data": [
        { "type": "videos", "id": "7" },
        { "type": "audios", "id": "9" },
        { "type": "images", "id": "38" },
        { "type": "videos", "id": "11" },
        { "type": "images", "id": "234" },
      ]
    }
  }
}

The package doesn't actually support this at the moment. The reason being is that there is no Eloquent relation for this. In this scenario, the Post model would look like this:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    
    public function audios()
    {
        return $this->hasMany(Audio::class, 'media');
    }
    
    public function images()
    {
        return $this->hasMany(Image::class, 'media');
    }

    public function videos()
    {
        return $this->hasMany(Video::class, 'media');
    }
}

The relations might not just be hasMany. For example, if Image models could be attached to multiple Post models, the image relation could be a belongsToMany. Likewise, if Image models could be attached to multiple different types of models, it could be a morphedByMany relation.

Merging these all into a single JSON:API relation is not currently supported.

[lindyhopchris]

When we do add support for this, we should have a chapter in the Digging Deeper section of the docs explaining the different approaches that can be used in this scenario.

For example, given the above example posts resource... As the three different relationships have been merged into one, there is now no way for a client to request a posts resource and only include images. I.e. the client can only include media and get all three types, even if it only wants the images. Therefore, representing them as 3 separate relationships gives the client more options when including resources.

However there are advantages to a single relation. For example, a client could request /api/v1/posts/5/media and get all the media for a post in a single request. In this case, the posts resource could have 3 separate relations and then a links-only media relation.

Having a dedicated chapter on this topic is probably the best way of explaining the different options available to developers.

[lindyhopchris]

Related to this, people also want to implement routes that return mixed models from index routes:
cloudcreativity/laravel-json-api#492

My current thinking is we probably need a psuedo-schema that represents what's common about the polymorphic models... i.e. so you know what include paths etc can be included. Then querying that psuedo-schema would effectively query all the model sub-types and combine into one result.

If we did that, then it would be possible to add index routes for the pseudo-schema.

[lindyhopchris]

The above PR adds support for polymorphic to-many relations. As the implementation did not require a psuedo-schema, I've decided not to support polymorphic index routes. The main problem with an index route is it's highly like to return large numbers of resources - which means pagination would typically be required, but this isn't possible when executing multiple queries of the database.

It's taken a considerable amount of time to write the polymorphic relations. As I have no need for polymorphic index routes in any of the APIs I maintain, if someone wants that feature they will need to write it an submit a PR for it.

[lindyhopchris]

Documentation for the feature:
https://github.com/laravel-json-api/docs/blob/develop/1.0/digging-deeper/polymorphic-to-many.md