makeabledk / laravel-eloquent-status
Installs: 47 936
Dependents: 1
Suggesters: 0
Security: 0
Stars: 153
Watchers: 5
Forks: 10
Open Issues: 0
Requires
- php: ^8.1
- illuminate/support: ^10.0|^11.0
- makeabledk/laravel-querykit: ^3.0|^4.0
Requires (Dev)
- laravel/laravel: ^10.3.3|^11.0.5
- phpunit/phpunit: ^10.5.17
This package is auto-updated.
Last update: 2024-10-31 00:21:17 UTC
README
Check out the blog post explaining the concepts of this package:
https://medium.com/@rasmuscnielsen/an-eloquent-way-of-handling-model-state-c9aa372e9cb8
Most models has some sort of status or state to it. Few examples could be
- Post: draft, private, published,
- Job: applied, accepted, declined, completed, cancelled
- Approval: pending, reviewing, approved
Traditionally you may find yourself having a scopeAccepted
and then additionally a ìsAccepted
helper method to test a model-instance against a specific status.
This package offers a very handy way of dealing with statuses like these without cluttering you model.
When you've successfully setup this package you'll be able to achieve syntax like
Approval::status('approved')->get(); // Collection
$model->checkStatus('approved'); // bool
Makeable is web- and mobile app agency located in Aarhus, Denmark.
Installation
You can install this package via composer:
composer require makeabledk/laravel-eloquent-status
Example usage
Given our Approval example from earlier we may have the following database fields:
- id
- ... (some foreign keys)
- tutor_approved_at
- teacher_approved_at
- assessor_approved_at
- created_at
- updated_at
Let's start out by creating a status class that holds our status definitions
Getting started
1. Create a status class
We will define all our valid statuses as public functions in a dedicated status class.
<?php class ApprovalStatus extends \Makeable\EloquentStatus\Status { public function pending($query) { return $query ->whereNull('tutor_approved_at') ->whereNull('teacher_approved_at') ->whereNull('assessor_approved_at'); } public function reviewing($query) { return $query ->whereNotNull('tutor_approved_at') ->whereNull('assessor_approved_at'); } public function approved($query) { return $query ->whereNotNull('tutor_approved_at') ->whereNotNull('teacher_approved_at') ->whereNotNull('assessor_approved_at'); } }
Notice how the statuses are defined just like regular scope
functions. While this example is super simple, you have the full power of the Eloquent Query Builder at your disposal!
🔥 Tip: We recommend that your statuses has unambiguous definitions, meaning that a model can only pass one definition at a time. This will come in handy in the next few steps.
2. Apply trait on the model
<?php use \Makeable\EloquentStatus\HasStatus; class Approval extends Eloquent { use HasStatus; }
Querying the database
Now we can query our database for approvals using the defined statuses:
Approval::status(new ApprovalStatus('pending'))->get();
Again, notice how this is very close to just calling a scope like we're used to: Approval::pending()
.
However there are som benefits to this new approach.
- We've defined and encapsulated all our statuses in one place de-cluttering our model
- We can only query against valid statuses
Approval::status(new ApprovalStatus('something-else'))->get(); // throws exception
For instance this makes it convenient and safe to accept a raw status from a GET filter in your controller and return the result with no further validation or if-switches.
🔥 Checking model status
The real magic of the package!
We can actually use the same status definitions to check if a model instance adheres to a given status.
$approval->checkStatus(new ApprovalStatus('reviewing')); // true or false
This sorcery is powered by our other package makeabledk/laravel-query-kit.
Note: Make sure to see the Limitations section of this readme.
Guessing model status
What if you wanted to know which status a model is from its attributes? Well you're in luck.
<?php use \Makeable\EloquentStatus\HasStatus; class Approval extends Eloquent { use HasStatus; public function getStatusAttribute() { return ApprovalStatus::guess($this); } }
Now $approval->status
would attempt resolve the approval status from your definitions.
Note: The status is guessed by checking each definition one-by-one until one passes. This is why you may consider unambiguous definitions.
Also you should be careful not to load relations in your definitions and generally consider a caching-strategy for large query-sets.
Furthermore see the Limitations section of this readme.
Binding a default status to a model
Rather than passing an instance of a status class each time you perform a check, you may bind a default status class to your model:
use Makeable\EloquentStatus\StatusManager; StatusManager::bind(Approval::class, ApprovalStatus::class);
Now you may simply type name of the status
$approval->checkStatus('accepted');
Other status classes than the default can still be used when passed explicitly.
You may bind the status classes in the boot
function of your AppServiceProvider
or create a separate service provider if you wish.
Limitations
This package is an abstraction on top of makeabledk/laravel-query-kit.
QueryKit provides a mocked version of the native QueryBuilder, allowing to run a scope function against a model instance.
This approach ensures great performance with no DB-queries needed, but introduces certain limitations.
While QueryKit supports most QueryBuilder syntaxes such as closures and nested queries, it does not support SQL language such as joins and selects. These limitation only applies to checkStatus()
and guess()
functions.
Check out the Limitations section in the makeabledk/laravel-query-kit documentation for more information.
Available methods on HasStatus
- scopeStatus($status)
Approval::status(new ApprovalStatus('approved'))->get(); // Collection // Or when default status is defined Approval::status('approved')->get(); // Collection
- scopeStatusIn($statuses)
Approval::statusIn(['pending', 'reviewing'])->get(); // Collection
- checkStatus
$approval->checkStatus('approved'); // bool
- checkStatusIn
$approval->checkStatusIn(['pending', 'reviewing']); // bool
Testing
You can run the tests with:
composer test
Contributing
We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details.
Credits
License
Attribution-ShareAlike 4.0 International. Please see License File for more information.