Download the PHP package ingruz/yodo without Composer
On this page you can find all versions of the php package ingruz/yodo. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package yodo
Yodo
A set of utility to easily and rapidly create REST api with Laravel.
Requirements
Yodo requires php 7.0 or above and is designed to work with Laravel 5.5 or above.
Install
Via Composer
Getting started
Suppose you need to create CRUD (or, more precisely, BREAD) handlers for a Post
model, you should first create a PostController
class inside your app/Http/Controllers
folder.
Then you should tell your router to use that controller for handling the Post resource:
And that's it! You now should have a full working BREAD endpoint for the Post
resource, with enabled support for pagination, filtering, sorting and more!
Usage
Of course you can customize most of Yodo's behaviour!
In addition to Controllers there are two other main pieces of Yodo that are Repositories and Transformers. By default Yodo will search for a custom Repository
in app/Repositories
folder, and for a custom Transformer
in app/Transformers
(in future both paths will be customizable), searching with the name of the controller's resource (for example if the class name is PostController
it will search for PostRepository
and PostTransformer
respectively).
You can always specify them with a custom path or name overriding protected getRepositoryClass
or getTransformerClass
methods in your controller.
If you don't specify anything and Yodo can't find a suitable class, it will fall back to default Repository
and Trasformer
. In most cases you won't need to customize the Repositories but this will happen more ofter for the Transformers, since the default one will just return the model as an array.
Repository
To create a custom repository, just extend the default one:
Like the Controller, by default the Repository will search for it's model class in your root name space (so PostRepository
will look for App\Post
model). You can always specify by overriding the getModelClass
method or by passing direcly an instance to the Repository's constructor (also passing the classname as string is supported).
It's possible to customize in many way how a Repository works, expecially when handling the getAll
method that it's used by the index
method inside the resource Controller:
-
static $eagerAssociations (defaults to []): define a list of associations that will be automatically eager-loaded;
-
static $defaultParams (defaults to ['limit' => 50]): define an hash of parameters that will be passed to
getAll
method if not specified elsewhere; -
static $defaultScopes (defaults to []): define a list of local scope to apply to the query generated by the
getAll
method; -
static $filterParams (defaults to []): define a list of columns on which will be performed a full-text search when the filter parameter (
q
) is specified; -
static $queryParamsHandlers (defaults to []): define an hash of possible query params that could be mapped to database column or handled by a closure, more detailed information in the following chapters;
-
static $orderParamsHandlers (defaults to []): same as
$queryParamsHandler
but for ordering; - static $rules: define a serie of rules to validate the model during create and update phases using Laravel built-in Validator, more detailed information in the following chapters.
Handle query's params
Query parameters defined here will be automatically handled by the repository, you can define them as an hash in $queryParamsHandlers
or by returning an array overriding the method getQueryParams
:
So the values of the hash could be:
- a simple string: maps the query parameter to a column on the model's database table;
- a simple string, but with a dot (.): maps the query parameter to a column of a related model's database table;
- a string, starting with
::
, representing an Eloquent Scope e.g.::active
- a closure, which are passed the current
$query
object and the array of query parameters, which could be used to handle more advanced situations. - a string representing a class that extends the base
Ingruz\Yodo\Base\AbstractQueryParamsResolver
Request validation
It is possible to specify an array of Laravel's validation rules that will be used by the repository to validate the requests before creating and updating actions.
You can define the rules as a plain array:
Or just define rules for a specific action:
Or define general rules that should always be checked and rules specific to an action:
Events
A great place where setting up model's events is the boot
method of the repository:
Public API
getModel
: returns an instance of the repository model, useful as a start to create custom methods;getAll($params)
: returns all the rows filtered, ordered and paginated by$params
;getById($id)
: returns a row by its$id
;getFirstBy($key, $value, $operand)
: get the first row that match a where clause;getManyBy($key, $value, $operand)
: get all the rows that match a where clause;create($data)
: create a new item with the provided$data
;update($item, $data)
: update an$item
(could be an actual instance or a string id) with the provided$data
;delete($item)
: delete an$item
from the database.
Transformer
Yodo uses the excellent Fractal library for handling the transformation of Models in json.
To create a custom Transformer just extends Fractal's TransformerAbstract
:
Exceptions
Yodo will automatically returns error responses following two exceptions:
ModelValidationException
: this exception will be raised if the payload of a create or update request doesn't satisfy the validation rules defined inside the repository. A response will be returned with the validation error messages with the HTTP code 422;ApiLimitNotValidException
: this exception will be raised if a list request contain a limit not valid (above the$limitCap
defined in the repository or with a limit set to 0 where not allowed). A response will be return with the HTTP code 400.
Customization
To customize some default aspects of Yodo you will need to use its service provider. If you are on Laravel 5.5 or above you don't have to do anything, Package Discovery will include it for you.
Otherwise just add it to your config/app.php file providers's array:
The you can publish the yodo.php config file with the command php artisan vendor:publish
.
Inside you can customize Repositories and Transformers namespace roots and which http error code Yodo will return in case of ModelValidationException
and ApiLimitNotValidException
.
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
Contributing
Please see CONDUCT for details.
Security
If you discover any security related issues, please email direcly the author instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
All versions of yodo with dependencies
illuminate/support Version ^8.0
league/fractal Version ^0.19.0
spatie/fractalistic Version ^2.9