Download the PHP package mleczek/laravel-rest without Composer

Laravel REST Package

Laravel package with a set of tools helpful for building REST API.

• Installation
• Configuration
• Usage
  • Query params
  • With
  • Offset
  • Limit
  • Fields
  • Sort
  • Filter
  • Responses
  • Item
  • Collection
  • Accepted
  • No Content
  • Created
  • Updated
  • Patched
  • Deleted
• Tips and tricks
  • Default Context
• Contributing
• License

Installation

To install this package you will need:

• Laravel 5.3+
• PHP 5.6.4+

Require this package with composer:

In config/app.php add the RestServiceProvider:

Configuration

Publish the package configuration and ContextServiceProvider:

This command will create 2 files for you:

• config/rest.php
• app/Providers/ContextServiceProvider.php

Register new local copy of the ContextServiceProvider in the config/app.php file:

Usage

Query params

Supplied by the client. They control the format of the response most often by narrowing result.

With

Include related data in response:

In the background the library will attach related models using Eloquent defined relations, which is quite similar to calling $quer->with(['messages', 'permissions']).

By default all relations are disabled, which means that you have to explicitly define which relations can be used in API call. You can set up this in the previously published ContextServiceProvider:

If you'd like to do some policy checks then you can define context class. In this class you can create methods which name is equal to the relation name. Whenever you try to access this relation the new instance of this class will be created and the result of the method will determine if the relation can be used or not.

Of course you have to register that context in the ContextServiceProvider:

Now if someone without root access call the with=messages then nothing will happen. If you'd like you can throw 401 or 403 response code from the context class.

In UserWithContext class and other context classes you can inject your dependencies in the constructor, because class is resolved using service container.

Offset

Skip n first items:

You can use this as well for the related data:

Limit

Limit results to n items:

You can use this as well for the related data:

Fields

Get only specified fields:

You can use this as well for the related data:

If you specify fields only for the primary model then all fields will be retrieved for the related one:

Above example will return first_name, last_name and all columns for the messages model (eq. id, author_id, recipient_id, content). This helps in finding a sub-optimal query - if you don't want any field from the related model then just simply remove redundant values from the with query param.

Sort

Return results in specified order:

You can use this as well for the related data:

By default no sort methods are available, which means that you have to explicitly define sort that can be used for specific model. You can set up this in the previously published ContextServiceProvider:

Then you have to create context class. Sort name will be converted to method name using camelCase style (eq. last_name_desc will call lastNameDesc method). As a first argument you will receive the Illuminate\Database\Query\Builder.

Now you can sort messages using latest method in any context:

In MessageSortContext class and other context classes you can inject your dependencies in the constructor, because class is resolved using service container.

Filter

Put constraint on request:

Unlike sort param the filter query param can also accept arguments:

You can use this as well for the related data:

By default no filter methods are available, which means that you have to explicitly define filters that can be used for specific model. You can set up this in the previously published ContextServiceProvider:

Then you have to create context class. Filter name will be converted to method name using camelCase style (eq. last_name_in will call lastNameIn method). As a first argument you will receive the Illuminate\Database\Query\Builder.

Now you can filter users using scoreAbove method in any context:

In UserFilterContext class and other context classes you can inject your dependencies in the constructor, because class is resolved using service container.

Responses

Library extends the Response class using some helpful macros.

Item

Response single model item with response code 200 OK:

This macro will use the fields and with query param.

This is not recommended to use with, select and addSelect on the $query parameter passed to the method. After all if you would like to do this the behavior it is as follows:

• if someone pass the same relation name in with query param the one you created will be overridden
• if someone pass the fields query parameter then only fields specified in this parameter will be returned

Often you will need to do some operations using retrieved model, in this case use rest() helper funtion:

The above example has one major defect, the second argument passed to the authorize can contain only fields specified in the fields query param. The better solution is to retrieve the whole model, call authorize method and then apply the query param transformations:

Summarizing, the response()->item() macro can accept the Illuminate\Database\Eloquent\Model or Illuminate\Database\Eloquent\Builder object.

Collection

Response collection of models with response code 206 Partial Content:

This macro will use the fields, sort, filter, offset, limit and with query param. Again, using orderBy, select, addSelect, limit/take, offset/skip methods on the $query argument is not recommended, but fell free to add some constraints using where method.

If you will need to make some operations before returning response you can use rest() helper function:

Accepted

Empty response with status code 202 Accepted.

No Content

Empty response with status code 204 No Content.

Created

Response created model with status code 201 Created. If $location is specified then appropriate Location header will be added to the response.

Updated

Response updated model (if provided) with status code 200 OK.

Patched

Response part of updated model (if provided) with status code 200 OK.

Deleted

Empty response with status code 204 No Content.

Tips and tricks

Default Context

By default library implements 2 context classes:

These context can be used with any class and allow sorting and filtering using fillable attributes. Example usage for the default User model:

It's recommended to use only for the dev purposes. In future releases implementation will change in order to prevent accidental security vulnerabilities (like the above one with password column). Any ideas are welcome.

Contributing

Thank you for considering contributing! If you would like to fix a bug or propose a new feature, you can submit a Pull Request.

License

The library is licensed under the MIT license.