Need help architecting or implementing a REST API? Book a call!

Guide

Prologue

Learn about changes and new features in Orion for Laravel 2.0.

Release Notes

OpenAPI Specifications Generation

Now you can generate OpenAPI specifications automatically for all Orion-powered endpoints, simply by running the following command:

php artisan orion:specs

You can learn more about this feature in the Specifications section of this guide.

2.0 release enables even greater search capabilities by introducing the support for json fields.

// (POST) https://myapp.com/api/posts/search
{
    "filters" : [
        {"field" : "options->visible", "operator" : ">=", "value" : true},
    ],
    "search" : {
        "value" : "Example post"
    },
    "sort" : [
        {"field" : "options->key", "direction" : "asc"},
    ]
}

To whitelist a field inside a json field, use arrow notation:

<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;

// options field here is a json/jsonb field of the Post model
// visible and key fields are fields inside that json/jsonb field 
class PostsController extends Controller
{
    public function filterableBy() : array
    {
        return ['options->visible'];
    }

    public function searchableBy() : array
    {
        return [ 'options->key'];
    }

    public function sortableBy() : array
    {
         return ['options->key'];
    }
}

Previously, it was possible to search on relation fields one-level deep only, e.g.:

public function searchableBy() : array
{
    return ['user.name']; // name field of the user relation
}

This release makes it possible to perform search on deeply nested relations:

public function searchableBy() : array
{
    return ['user.name', 'user.location.address.postalcode']; // postalcode field of the deeply nested user.location.address relation
}

Hook Methods Signature

A parent entity is now passed into the hook methods of relationship controllers, e.g.:

protected function afterSave(Request $request, Model $parentEntity, Model $entity)

Default Auth Guard Resolution

The default auth guard is now resolved from the orion.php config's auth.guard key.

You can still override the resolveUser method on a controller, if you need a granular control over the auth guard or user resolution.

ilike and not ilike Operators Support

// (POST) https://myapp.com/api/posts/search
{
    "filters" : [
        {"field" : "title", "operator" : "ilike", "value" : "example post"},
    ]
}

Upgrade Guide

This guide covers the process of upgrading Laravel Orion from v1.x to v2.x.

PHP 7.3 Required

The new minimum PHP version is now 7.3.0.

Updating Dependencies

Update the following dependencies in your composer.json file:

  • php to >=7.3
  • tailflow/laravel-orion to ^2.0

Publishing Config

The release introduces orion.php config file, allowing you to customize the default auth driver and information about api for specifications generation.

To publish the config, run the following command:

php artisan vendor:publish --tag=orion-config

Whitelisting Methods Signature

The following methods have been made public:

  • exposedScopes
  • filterableBy
  • searchableBy
  • sortableBy
  • includes
  • alwaysIncludes

Please update your controllers accordingly, should you have any of these methods overridden.

Hook Methods Signature

Starting with 2.0 release, a parent entity is passed into the hook methods. Please update your relationship controllers accordingly, should you have any hook methods overridden.

Here is an example:

Before 2.0

protected function afterSave(Request $request, Model $entity)

After 2.0

protected function afterSave(Request $request, Model $parentEntity, Model $entity)

Copyright © 2019-2024 Aleksei Zarubin