Download the PHP package makeabledk/laravel-eloquent-status without Composer

Laravel Eloquent Status

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

``

``

Makeable is web- and mobile app agency located in Aarhus, Denmark.

Installation

You can install this package via composer:

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.

``

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

Querying the database

Now we can query our database for approvals using the defined statuses:

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

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.

``

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.

``

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:

``

Now you may simply type name of the status

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)

- scopeStatusIn($statuses)

- checkStatus

- checkStatusIn

Testing

You can run the tests with:

Contributing

We are happy to receive pull requests for additional functionality. Please see CONTRIBUTING for details.

Credits

• Rasmus Christoffer Nielsen
• All Contributors

License

Attribution-ShareAlike 4.0 International. Please see License File for more information.