Download the PHP package mblarsen/laravel-repository without Composer

laravel-repository :cow:

Beefed up query-builder and repository to reduce boilerplate and keep your controllers lean

Features:

• Get started with zero config. See basic examples
• The usual suspects: all, find, create, update, destroy.
• Plus allResources, findResource, and so on to wrap in resources.
• list() function useful for <select> and autocompletes.
• Front-end and user driven. The request is the context for what gets included:
  • filter query on model and relations
  • include relations (all blocked by default)
  • deal with paging transparently
  • order models by their props or their relations props (with no custom SQL)
• 100% test coverage

The goal of this package:

1. Avoid boilerplate for paged, filtered, and sorted resources
2. Let the client decided what to fetch in a safe way
3. Separate controller logic from model logic
4. Let you be in control of the query for special cases

Practically the repository class is a mix between a query builder and a repository with emphasis on the retrieving stuff.

This package includes one interfaces and three classes for you to build on:

• Repository class, to use as is or extend for your model needs.
• ResourceContext interface, provides data to the repository.
• RequestResourceContext, draws data from the incoming Request object.

• ArrayResourceContext, you provide the data. Good for testing.

  

Installation

You can install the package via composer:

The repository relies on a ResourceContext to provide it with the necessary values to be able to sort, filter, paginate and so on. This is handled automatically, but it means that you should let Laravel's depency injection provide a repository for you. This is espesically powerfull if you extende the base repository class.

The default context that is used is the RequestResourceContext which is automatically injected into the repository. This is espesically useful when you are building public or private APIs to serve a front-end. However, another implementation is provided that lets you provide the control to a higher degree. This is the ArrayResourceContext. This implementation is useful for testing or for when you build a traditional Laravel application using Blade views.

The following examples a biased toward use of the RequestResourceContext.

Basic examples

The base repository knows nothing of your models, so unless you sub-class the repository, you must specify what model you are querying.

When used in controllers it is recommended letting Laravel do the work for you:

... or in case of a custom repository:

The result is now automatically sorted, filtered, and paginated according to the request.

Example requests that you'll be able to provide now:

That is:

• /posts, request posts
• sort_by=created_at, sort by created_at
• sort_by=desc, sort in descending order (default: asc)
• page=2, paginated result, request page 2 (default: null meaing not paginated)
• filters[title]=laravel search for title in the posts name

You can also filter by relationships. E.g. filters[address.zip]=1227.

Since relations are disallowed by default nothing requests to include are ignored. But once we set that up your will be able to request relations as well:

• with[]=ads&with[]=comments, will include the relations ads and comments.

Repository features

You can define the behaviour of the repository using a chained API. Be sure to check the full API below.

Control what relations to include

Query: with or with[]

The repository will include any relations specified in with based on what is allowed. That ensures that the client cannot request data that you have not allowed.

Some times you want to include certain relations by default. In addition to doing that on the model directly the Laravel way you also have the option to set which on the repository. This allows you to control the list of relation per action in the controller.

Aside: if you are building a public api (for your SPA or 3rd party) it is recommended that you wrap the result a JsonResource. This will give you control of what properties are exposed and will allow you to transform the data further. See resources section.

Filtering

Query: filter[key]=value

This package provides a search like functionality through its filters. Under the hood it uses LIKE, ie. %value%.

If you want exact matches, ie. =, instead you can add an exclamation point to then end of the key name.

The key doesn't have to be properties on the main model. It can be relation properties as well. Here are some examples:

You can combine properties in a search:

And lastly you can choose to search for the same value in multiple properties:

A different way to filter is to provider a query builder to all() and find(). See examples in the API.

Transforming RequestResourceContext

You cannot modify the request context directly, but you have the option to convert it to an ArrayResourceContext.

Custom repositories

Many of your models will likely not need as custom (sub-classed) repository. But often your core models have more logic associated with them. In that case it is advised do extend the base repository.

All the properties except the model can be omitted. Well, you can omitted the model too but that is kind of pointless.

Disclaimer: the example's purpose is to demo the flexibility not and isn't very real world.

You can achieve the same with the base repository, but of course then you would have to repeat the setup every time:

Versus:

Resources

If you are building a public api (for your SPA or 3rd party) it is recommended that you wrap the result a JsonResource. This will give you control of what properties are exposed and will allow you to transform the data further.

Doing is really easy.

Then you just use any of the API methods prepending Resource or Resources as shown here:

If you implement a collection resource you can set that as the second arguments to the setResource method call:

Note: list() doesn't support resources. It didn't make any sense to me. You are welcome to change my mind.

Customizing RequestResourceContext

The default values that the RequestResourceContext looks for in incoming request are:

• filters
• page
• per_page
• sort_by
• sort_order
• with

If you don't like these or for some reason cannot use them. You have the option to provide your own keys using mapKeys() on the context. mapKeys() lets you map one or more keys to your preferred scheme.

By far the easiest way to do this is add this bit of code in your AppServiceProvider.

So as where this would be the old way:

your client now should use this scheme:

Testing

When it comes to testing the ArrayResourceContext comes in handy. It lets you pass in context values directly.

API

• all($query = null)
• list(string|callabel $column, $query = null)
• find($id, $query = null)
• create(array $data)
• update(Model $model, array $data)
• destroy(Model $model)
• setContext(ResourceContext|array $resource_context)
• setModel(string $model)
• setAllowedWith(array $allowed)
• setDefaultWith(array $with)
• shouldAuthorize(bool $value = true)

When extending the base repository you may want to check out these additional functions:

• modelQuery($query = null)
• register()

all($query = null)

allQuery($query = null)

allResources($query = null)

Return all models given the current resource context.

Use with Query suffix to return as a query builder.

Use with Resources suffix to return as a resource collection.

list(string|callabel $column = null, $query = null)

listQuery(string|callabel $column = null, $query = null)

Produces a result suitable for selects, lists, and autocomplete. All entries that has a 'value' and a 'label' key.

If $column is omitted the default sort by is used. In many cases they'll be the same anyway.

Use with Query suffix to return as a query builder.

Note: if a callable is used the mapping is performed in memory, while a string is done in the database layer. Also note that when using the listQuery variant the callable is not reflected.

find($id, $query = null)

findQuery($id, $query = null)

findResource($id, $query = null)

Gets a single model. You can further narrow down the result by providing a start query. See example in all()

Use with Query suffix to return as a query builder.

Use with Resource suffix to return as a resource.

create(array $data)

createResource(array $data)

Typical crUd. Use with Resource suffix to return as a resource.

update(Model $model, array $data)

Typical crUd.

Use with Resource suffix to return as a resource.

destroy(Model $model)

Typical cruD.

setContext(ResourceContext|array $resource_context)

This method lets you set or change the context after the repository is created.

setModel(string $model)

See example code.

setAllowedWith(array $allowed)

See example code.

setDefaultSort(string $by, string $order = 'asc')

setDefaultWith(array $with)

See example code.

modelQuery($query = null)

See example code.

register()

Called when the repository is created. This is useful setting up this default_list_column function for a sub-classed repository.

shouldAuthorize(bool $value = true)

When set to true authorization is performed before any query is performed.

Example:

interface ResourceContext

See ResourceContext implementation.

Changelog

Please see CHANGELOG for more information what has changed recently.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Prior work

• Spatie QueryBuildir
• bosnadev/repository

Credits

• Michael Bøcker-Larsen
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.

Contributing

Please see CONTRIBUTING for details.

Please see DEVELOPING for help getting started.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Michael Bøcker-Larsen 💻 📖 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!