Browsing Resources

To enable the browsing of resources you must have added browse to the resource.enabled array. You may then specify the following configurations for browsing, which includes ordering, filtering, and searching

Routing

The route will be named {your-bakery-prefix}.{resource}.browse

Custom Query Modifier

You may wish to specify additional modification to the query in order to return relevant results, for example to support tenancy, or returning a user's own resources.

You can do this by specifying query_modifier as a fully qualified class name, which implements the ModifiesBakerySearch interface.

Security

As per the cascaded security specification, supporting allows guests, security gates, and security policies.

Transforming Results

collection specifies a HTTP Collection Resource to be returned with the contents of your search, if not specified then the collection itself will be returned

per_page specifies how many items per page to be returned

Search

search.enabled is a boolean specifying whether we allow fluffy searching

search.columns is an array of fields which will be fluffy searched

search.custom_handlers is an array of custom search handlers to be used, these classes must implement the ModifiesBakerySearch interface

Filtering

Filtering looks for specific matches, for example posts by category ID, you can specify columns on which you wish to filter, and custom filters for application specific filtering, such as "in stock"

Field filters as specified as column (or alias) value pairs in the request, for example ?banned=1 whereas filters are specified in a filters array, for example ?filters[]=in-stock

Custom filers must implement the HandlesBakeryFilter interface

Caching

You may wish to cache results returned by the browse functionality. If this is the case you can specify the following, the TTL is specified in seconds.

Expiring the cache is handled by events and listeners in your application, read more in the Caching documentation.

'cache' => [
    'enabled' => true,
    'ttl' => 600
]

Ordering

You may specify that you wish for our resource collections to be ordered, if you wish for this to only be based on specific fields, specify order_fields as an array with the list of acceptable fields.

Custom Query Modifier

You may wish to specify additional modification to the query in order to return relevant results, for example to support tenancy, or returning a user's own resources.

You can do this by specifying query_modifier as a fully qualified class name, which implements the ModifiesBakerySearch interface.

Example Declaration

'browse' => [

        /* If we want to modify the query, for example to support tenancy, define it here */
        'query_modifier' => \App\Repository\QueryModifier::class,

        /* Do we allow guests to browse this endpoint */
        'allow_guests' => false,

        /* Use a gate to determine whether or not someone can browse this model */
        'gate' => 'admin',

        /* What collection should we use for results */
        'collection' => MyRecourceCollection::class,

        /* Search configurations */
        'search' => [

          /* On which columns can we do a fluffy search */
          'columns' => ['name','email'],

          /* If we have any custom search handlers, define them here, in execution order */
          'customHandlers' => [
            UserSearchHandler::class
          ],
          
          /* Caching */
          'cache' => [
            'enabled' => true,
            'ttl' => 600
          ]
          
        ],

        /* Filtering is for exact matching */
        'filter' => [
          'columns' => [
            'status', 
            'email_verified_at'
          ],
          'custom' => [
            'has-orders' => HasOrdersFilter::class
          ]
        ],

        /* Which fields do we allow ordering by */
        'order_fields' => [
          'created_at',
        ]