Configuration

The configuration file

Publish config/rest.php to change a default:

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

The file has seven blocks, in this order: authorizations, gates, morph, search, transactions, limits and precognition.

The package merges its defaults into your file at every level. A nested key that your file leaves out, such as gates.names.authorized_to_restore or limits.sizes.filters, keeps its default value. You can keep only the keys you change.

Authorizations

'authorizations' => [
    'strict' => env('REST_AUTHORIZATIONS_STRICT', false),

    'cache' => [
        'enabled' => env('REST_AUTHORIZATIONS_CACHE_ENABLED', true),
        'store' => env('REST_AUTHORIZATIONS_CACHE_STORE'),
    ],
],

A resource keeps no decision until it declares one in authorizationCache(), so the cache does nothing in an application that declares none. See Decision cache.

To turn strict mode on in your tests, add the variable to phpunit.xml:

<env name="REST_AUTHORIZATIONS_STRICT" value="true"/>

Gates

'gates' => [
    'key' => 'gates',

    'names' => [
        'authorized_to_view' => 'authorized_to_view',
        'authorized_to_create' => 'authorized_to_create',
        'authorized_to_update' => 'authorized_to_update',
        'authorized_to_delete' => 'authorized_to_delete',
        'authorized_to_restore' => 'authorized_to_restore',
        'authorized_to_force_delete' => 'authorized_to_force_delete',
    ],
],

Add a key to gates.names to rename a gate that a resource declares in gates(), by its default name: 'authorized_to_download' => 'can_download'. Each answer holds allowed and message. See Gates.

Morph

'morph' => [
    'type_key' => '@type',
],

See Relations.

Search

'search' => [
    'select_columns' => true,

    'more_key' => '@more',
],

When a policy, an accessor or the map() of a custom response reads a column that the search did not load, the search throws Lomkit\Rest\Exceptions\MissingColumnException. Add the column to the resource's alwaysSelect() or to the field's requires(), or set select_columns to false. See Fields.

Transactions

'transactions' => [
    'attempts' => env('REST_TRANSACTION_ATTEMPTS', 1),
],

Each write runs in a transaction: a mutation, a destroy, a restore, a forceDestroy, and each chunk or whole run of an action. Each attempt runs the whole write again, with its checks, its hooks, its events and the handle() method of the action. A transaction inside a transaction of your application is not run again. See Mutate.

Limits

The limits block bounds the size of a request and of what it makes the package do. A request over a limit gets a 422 on the list or the value that goes over it. A limit of 0 refuses every entry, or the first level of a depth. See Limits for the messages and the rules of each key.

'limits' => [
    'sizes' => [
        'filters' => 100,
        'sorts' => 20,
        'selects' => 100,
        'scopes' => 10,
        'aggregates' => 20,
        'includes' => 20,
        'instructions' => 10,
        'fields' => 100,
        'values' => 100,
        'mutate' => 100,
        'relation_entries' => 100,
        'resources' => 1000,
        'jobs' => 100,
        'rows' => 10000,
        'groups' => 100,
    ],

    'depths' => [
        'filters' => 1,
        'includes' => 3,
        'mutations' => 3,
    ],

    'totals' => [
        'filters' => 500,
        'entries' => 1000,
        'relations' => 20,
        'patterns' => 10,
    ],

    'lengths' => [
        'patterns' => 255,
        'values' => 1000,
    ],
],

Each value is an integer of 0 or more. sizes.jobs, sizes.rows, sizes.groups, totals.relations, totals.patterns and lengths.values must be at least 1.

Sizes

The most entries of each list, at every level of a request, then three bounds on the work of one request: the jobs of a queued action, the rows of a response, and the groups of a metric.

Depths

How many levels nest.

Totals

Totals across the lists of one request.

Lengths

These limits are not the page sizes of a resource, which its limits() method returns. See Limits.

Precognition

'precognition' => [
    'enabled' => false,
],

The middleware is added when the routes are registered: clear the route cache after you change this option. See Precognition.

Typed values

Each request reads the values once, and checks their type. A value of the wrong type throws Lomkit\Rest\Exceptions\InvalidConfigException, an InvalidArgumentException, that names the key.

The strings let env() values work as they are. null and an empty string are refused: a variable set without a value, such as REST_AUTHORIZATIONS_STRICT=, throws.

precognition.enabled is read when the routes are registered, limits when a request first reads its limits, and the other values together, the first time a request needs one of them.