czim / laravel-listify
Turns any model into a list. Rebuild of the popular Lookitsatravis Listify package.
Installs: 66 199
Dependents: 5
Suggesters: 0
Security: 0
Stars: 5
Watchers: 2
Forks: 2
Open Issues: 1
Requires
- php: >=7.1.3
Requires (Dev)
- orchestra/testbench: ^3.0|^4.0
- phpunit/phpunit: ~7.0|~8.0
README
This is a rebuild (from scratch) of Lookitsatravis' Listify for personal reasons. It uses the same interface as Listify, so switching from that to this package should not break anything.
Version Compatibility
Changelog
Why?
Listify is great, but has a few shortcomings:
- A very minor one is the code standard, which could IMHO do with some serious cleanup.
- More annoying are the heavy reliance on
private
methods and properties, making it impossible to use Listify with flexible inheritance approaches. - Functionally, Listify is not suited for variable scopes. The belongs-to scope is too restrictive (no nullable foreign key columns), and any string-based scope is set inflexibly.
For my purposes, I require a callable scope that handles swapping scopes well and treats a
null
-scope as taking an item out of a list.
Install
Via Composer
$ composer require czim/laravel-listify
Usage
For general functionality the original Listify interface is largely the same. For reference, see the original documentation.
Some exceptions apply:
- You may now use a
callable
scope, which may return any string to be used in a (raw)where
clause. The original limitations to Listify string scopes apply. However,null
is now an acceptable scope that will keep or remove the record from any list (itsposition
will remainNULL
). - You may now use nullable and null foreign keys for BelongsTo scopes. A record without the relevant foreign key will not be added to a list.
Although it is not required, you may make models that use the trait implement the ListifyInterface
for your own purposes.
Differences with the original Listify
There is no attach
artisan command supplied; you are expected to handle your position
column migrations yourself.
The exceptions that do get thrown have been simplified. InvalidArgumentException
, UnexpectedValueException
and BadMethodCallException
are thrown instead of custom exceptions.
Exceptions are no longer thrown for 'null scope' or 'null foreign key', since these are now expected and allowed. Models with an effective 'null scope' will now silently be excluded from lists.
Note that this package has been tested with the original listify PHPUnit tests and passes them where behavior has not intentionally changed.
Finally, this trait may be used with inheritance (because its base scope is protected
rather than private
). You can make a 'BaseListifyModel' and extend that to avoid code (or setup) duplication.
Dealing with global scopes
When using global scopes on a listified model, this may break expected functionality, especially when the global scope affects how the records are ordered. To deal with this, listify will check for a method to clean up the scope as required. To use this, simply add an implementation of the following method to your listified model class:
/** * @param \Illuminate\Database\Eloquent\Builder $query * @return \Illuminate\Database\Eloquent\Builder */ public function cleanListifyScopedQuery($query) { // Return the query builder after applying the necessary cleanup // operations on it. In this example, a global scope ordering the // records by their position column is disabled by using unordered() return $query->unordered(); }
This method will be called any time that listify performs checks and operations on the model for which it needs access (and its own ordering).
To Do
- The way string (and QueryBuilder) scopes work is slightly strange. Adding new records that fall outside of the scope will be added with a position value. Those records are reported as being in a list, and odd things can happen when manipulating them.
Contributing
Please see CONTRIBUTING for details.
Credits
Obviously, the main credits for anything to do with Listify go to:
License
The MIT License (MIT). Please see License File for more information.