kigathi-chege/lyre

About Lyre

Lyre is a php package built for Laravel. Lyre works together with the rich Laravel ecosystem, and goes hand in hand with its philosophy of expressive, elegant syntax. It takes enjoyable and creative development a step further and makes you feel the harmony of it all as the elements come together. Lyre utilizes the following to create the rhythm of the future:

• Repositories, as hinted at in Laravel's container docs.
• Eloquent resources to automatically transform your responses.
• Abstracted resource controllers with all your basic CRUD, maximizing on a naturally RESTFUL API.
• Comes out of the box with spatie roles and permissions configured with Laravel policies.
• Another out of the box feature: spatie activity log configured with Eloquent observers.
• And finally, Artisan console commands to rule them all.

Lyre is accessible, powerful, and it is your next favorite tool.

Get started right away

composer require lyre/lyre

• Add LyreServiceProvider to your providers array under bootstrap > providers.php
• Add user BaseModelTrait to your User model, and to any other existing models.
• Run php artisan vendor:publish --provider="Lyre\Providers\LyreServiceProvider" to publish Lyre configuration.
• Clear configuration cache

Known Issue

• Lyre has problems publishing its stubs
• You can manually copy the stubs from this link before running the lyre:all command for the first time.
• STUBS

php artisan lyre:all Post

• Add your columns to your migration and migrate

• Add your model to your routes file

Route::apiResource('posts', PostController::class);

• Consume your API!

• Guess what? That's it.

Dependencies

• PHP 8.2
• Spatie Activity Log
• Spatie Laravel Permission

Digging Deeper

RESTFULNESS

• Lyre is naturally RESTFUL, meaning that after adding your apiResource or resource in your routes file, you will be able to create, update, and delete all records using these routes, borrowed from the above example:

   GET|HEAD        posts
   POST            posts
   GET|HEAD        posts/{post}
   PUT|PATCH       posts/{post}
   DELETE          posts/{post}
  

Hidden Gem

• Lyre comes with a bulkUpdate option that also follows the RESTFUL convention for batch operations, allowing you to efficiently update multiple records in a single request.
• All you need to do is comma separate the values in your PUT|PATCH request.
• For example:

Single Update

   posts/1

Bulk Update

   posts/1,2,3

Filters

Easily Handle Relationships

• To return a model with all its relationships, simply chain a with method that takes an array of relations when querying the repository like so:

$data = $this->postRepository->with(['author', 'comments'])->all();

• All you need to do is define the relationships in your model:

public function author()
{
       return $this->belongsTo(User::class, 'user_id');
}

public function comments()
{
       return $this->hasMany(Comment::class);
}

• Then override the loadResources method of the Posts resource in app>Http>Resources>Post

public static function loadResources(): array
{
       return [
              'author' => User::class,
              'comments' => Comment::class
       ];
}

• Now you will be able to get your model with these relationships using a simple query string

   posts/1?with=author,comments
  

Filters

Column Filters

• Easily return data filtered by a specific column

$data = $this->postRepository->columnFilters(['status' => 'active'])->all();

Range Filters

• Easily filter your data by range, for example, created_at!

$data = $this->postRepository->rangeFilters(['created' => [now()->subHours(24), now()])->all();

Relation Filters

• You can even return your data filtered by specific relationships!

$data = $this->postRepository->relationFilters('author' => 'id,1')->all();

Search Query

• Search through your repository!

$data = $this->postRepository->searchQuery(['search' => 'lyre'])->all();

Method Chaining

• What is more? You can chain all these methods to fine tune your query!

$data = $this->postRepository->with(['author', 'comments'])
       ->columnFilters(['status' => 'active'])
       ->rangeFilters(['created' => [now()->subHours(24), now()])
       ->relationFilters('author' => 'id,1')
       ->searchQuery(['search' => 'lyre'])
       ->all()

API Query Strings

Lyre provides the following query string filters to filter all your data the way you want!

• with - A comma separated list of all the relationships that you want to return in your response
• paginate - This boolean value determines whether pagination is set, default is true
• page - Changes the current page in a paginated request
• per_page - Changes the number of items returned in the request
• latest - Returns the latest value items
• order - Returns ordered items, e.g. ?order=id,desc

Known Issues

Installation

• All models must use BaseModelTrait, otherwise throws error: Call to a member function connection() on null
• Fails to publish stubs, creates empty folder. Stubs must be copied from STUBS

Collaboration

• Update version in composer.json
• Push changes to github, push tag to update Packagist

       git tag x.x.x
       git push origin x.x.x

License

Lyre is open-sourced software licensed under the MIT license.