optimus/architect

2.0.4 2023-12-28 14:51 UTC

Requires

• laravel/framework: ~6.0|~7.0|~8.0|~9.0|~10.0

Requires (Dev)

• mockery/mockery: 1.3.*
• orchestra/testbench: 4.*
• php-coveralls/php-coveralls: 2.2.*
• phpunit/phpunit: ~8.0

MIT

README

Introduction

Architect is used for dynamically creating new structures for API resource relationships. Sounds confusing and pretentious?

Imagine you have a resource Book with a related resource Author.

Book 1-----n Author

Normal embedded mode

This is how related resources are loaded by default using embedded mode.

{
   "books":[
      {
         "id":1,
         "author_id":1,
         "title":"How to save the world from evil",
         "pages":100,
         "author":{
            "id":1,
            "name":"Optimus Prime"
         }
      },
      {
         "id":2,
         "author_id":2,
         "title":"How to take over the world",
         "pages":100,
         "author":{
            "id":2,
            "name":"Megatron"
         }
      }
   ]
}

With Architect now you can load related resources using ids mode and sideloading mode

Ids mode

Only load the IDs of the related resource. Using the primary key property of Eloquent models is in the roadmap.

{
   "books":[
      {
         "id":1,
         "author_id":1,
         "title":"How to save the world from evil",
         "pages":100,
         "author":1
      },
      {
         "id":2,
         "author_id":2,
         "title":"How to take over the world",
         "pages":100,
         "author":2
      }
   ]
}

Sideloading mode

Hoist the related resources into the global scope and leave behind the IDs using the ID mode resolver.

{
   "author":[
      {
         "id":1,
         "name":"Optimus Prime"
      },
      {
         "id":2,
         "name":"Megatron"
      }
   ],
   "books":[
      {
         "id":1,
         "author_id":1,
         "title":"How to save the world from evil",
         "pages":100,
         "author":1
      },
      {
         "id":2,
         "author_id":2,
         "title":"How to take over the world",
         "pages":100,
         "author":2
      }
   ]
}

Usage

Architect works with normal array's (collections and resources), Illuminate\Support\Collection and Illuminate\Database\Eloquent\Model.

<?php

$books = Book::with('Author')->get();

$architect = new \Optimus\Architect\Architect;
$parsed = $architect->parseData($books, [
    'author' => 'sideload' // can also be embed or ids (embed is default)
], 'books');

Optimus\LaravelController gives nice convenience methods to define the Architect relationships in query parameters.

Installation

composer require optimus/architect

Standards

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Testing

$ phpunit

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.