README

Verbose Repository Data Access Layer for Laravel 5.

Yet Another Repository package?

If you search within Github you can find at least a dozen implementations of the repository pattern for Laravel 4 and 5. For Laravel 5, specifically, the best ones are prettus/l5-repository and Bosnadev/Repositories.

The difference between these packages and this one is a more flexible interface, enabling more complex queries through the Repository. And a lot of tests.

Installation

Add

"mayconbordin/reloquent": "dev-master"

to your composer.json. Then run composer install or composer update.

Add the Service Provider to the providers array in config/app.php:

'providers' => array(
    ...
    'Mayconbordin\Reloquent\Providers\ReloquentServiceProvider',
)

And then publish the configurations

php artisan vendor:publish

API & Usage

In the following sections examples will be given for all the interface methods available in the repository.

Assume we have a Post class model with columns: id, title, content, category_id and author_id.

findAllBy

// to find all posts that belong to a single category
$repository->findAllByCategoryId(1);

// fetch also the post tags and category
$repository->findAllByCategoryIdWith(1, ['tags', 'category']);

// we can also order the results by id in ascending order
$repository->findAllByCategoryIdOrderById(1);

// or descending
$repository->findAllByCategoryIdOrderByDescId(1);

// we could then limit the number of results returned to 15
$repository->findAllByCategoryIdOrderByIdLimit(1, 15);

// or even paginate the results, with 15 records per page
$repository->findAllByCategoryIdOrderByIdPaginated(1, 15);

// we can also get posts within a list of categories
$repository->findAllByInCategoryId([1, 2, 3, 4]);

// or filter the posts by category and author
$repository->findAllByCategoryIdAndAuthorId(1, 2);

// or by category or author
$repository->findAllByCategoryIdOrAuthorId(1, 2);

findBy

// find a single post by author id
$repository->findByAuthorId(1);

// or with author id AND category id
$repository->findByCategoryIdAndAuthorId(1, 2);

// or with author id OR category id
$repository->findByCategoryIdOrAuthorId(1, 2);

// fetch also the post tags and category objects
$repository->findByAuthorIdWith(1, ['tags', 'category']);

create, update and delete

$attributes = [
  'title'       => 'Post Title',
  'content'     => 'Post content...',
  'category_id' => 1,
  'author_id'   => 1
];

// create a new post
$post = $repository->create($attributes);

// update the title of the post
$updatedPost = $repository->update(['title' => 'Update Post Title'], $post->id);

// and delete it
$repository->delete($updatedPost->id);

Creating and deleting models with their relations

By default the repository doesn't care about the relations a model might have, which means that you can't give an instance of a related model as an attribute value to the create method. You also can't have the related objects removed before the object in question, and if the database is not configured to remove the children objects (DELETE CASCADE) the operation will fail.

To make the repository aware of the relations, add the attribute relations to the repository implementations, like this:

class PostRepository extends BaseRepository
{
    protected $relations = ['category', 'author'];
    
    ...
}

Now you can create a new post like this:

$attributes = [
  'title'    => 'Post Title',
  'content'  => 'Post content...',
  'category' => Category::find(1),
  'author'   => Author::find(1)
];

// create a new post
$post = $repository->create($attributes);

If a post could also have tags, you could create a post with tags like this:

$attributes = [
  'title'    => 'Post Title',
  'content'  => 'Post content...',
  'category' => Category::find(1),
  'author'   => Author::find(1),
  'tags'     => [1, 2, 3, 4]
];

BelongsTo relations are saved using the associate method, while BelongsToMany use the attach method. And when a post is deleted, the repository will iterate over the defined relations and remove them. For relations that are instances of HasOneOrMany the method delete is used, and for BelongsToMany the detach method.

exists, find and findByField

// check if a post exists, returns a boolean
$repository->exists(1);

// find a post by id
$repository->find(1);

// bring also its relations
$repository->find(1, ['author', 'tags']);

// find a post by author
$repository->findByField('author_id', 1);

// find a post whose title starts with 'A'
$repository->findByField('title', 'A%', 'LIKE');

// and you can also bring the post's relations
$repository->findByField('title', 'A%', 'LIKE', ['author', 'tags']);

findWhere

The findWhere method is not as pretty as the other methods. The first argument is an associative array of where statements. An statement is an array that contains the value of the field, and optionally the operator and the statement.

$repository->findWhere([
    'title' => ['test'],        // WHERE title = 'test'
    'category_id' => ['!=', 2], // AND category_id != 2
    'author_id' => ['or', 1]    // OR author_id = 1
    'content' => ['or', 'like', '%test%']    // OR content LIKE %test%
]);

all, findAllByField and findAllWhere

// get all posts
$repository->all();

// get all posts ordered by title
$repository->all('title:asc');

// get all posts ordered by id and title
$repository->all(['id:asc', 'title:asc']);

// get all posts by author 
$repository->findAllByField('author_id', 1);

// get all posts not by author 
$repository->findAllByField('author_id', 1, '!=');

// get all posts by author ordered by title
$repository->findAllByField('author_id', 1, '=', 'title:asc');

// get 15 posts by author ordered by title
$repository->findAllByField('author_id', 1, '=', 'title:asc', ['author'], 15);

// same as the above query
$repository->findAllWhere(['author_id' => 1], 'title:desc', ['author'], 15);

paginate, findAllByFieldPaginated and findAllWherePaginated

// get all posts
$repository->paginate();

// get 15 posts per page ordered by title
$repository->paginate(15, 'title:asc');

// get 15 posts per page posts ordered by id and title
$repository->paginate(15, ['id:asc', 'title:asc']);

// get 15 posts per page posts ordered by id and title with author
$repository->paginate(15, ['id:asc', 'title:asc'], ['author']);

// get posts by author 
$repository->findAllByFieldPaginated('author_id', 1);

// get posts not by author 
$repository->findAllByFieldPaginated('author_id', 1, '!=');

// get posts by author ordered by title
$repository->findAllByFieldPaginated('author_id', 1, '=', 'title:asc');

// get 15 posts per page by author ordered by title
$repository->findAllByFieldPaginated('author_id', 1, '=', 'title:asc', 15, ['author']);

// same as the above query
$repository->findAllWherePaginated(['author_id' => 1], 15, 'title:desc', ['author']);