Laravel Listify Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require czim/laravel-listify
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Czim\Listify\ListifyServiceProvider"
   

2. Basic Usage Register a listable model (e.g., Post):

   use Czim\Listify\Traits\Listable;
   
   class Post extends Model
   {
       use Listable;
   }
   

3. First Use Case Fetch a list of posts with default sorting:

   $posts = Post::listify()->get();
   

   Or with custom sorting:

   $posts = Post::listify(['sort' => 'created_at:desc'])->get();
   

4. Configuration Check config/listify.php for default settings (e.g., default_sort, allowed_sort_fields).

Implementation Patterns

Core Workflows

1. Dynamic Sorting Use listify() with a sort parameter to override defaults:

   // In a controller
   $sort = request('sort', 'title:asc');
   $items = Model::listify(['sort' => $sort])->get();
   

2. Filtering Chain where clauses before listify():

   $activePosts = Post::where('published', true)
       ->listify(['sort' => 'views:desc'])
       ->get();
   

3. Pagination Combine with Laravel’s pagination:

   $posts = Post::listify()->paginate(10);
   

4. API Integration Return sorted/filtered lists in API responses:

   return response()->json(Post::listify()->get());
   

Integration Tips

1. Middleware for Sorting Create middleware to handle sort query params globally:

   public function handle($request, Closure $next)
   {
       if ($request->has('sort')) {
           $model = app($request->route('model'));
           $model::listify(['sort' => $request->sort]);
       }
       return $next($request);
   }
   

2. Custom Sort Fields Override allowed fields in config/listify.php:

   'allowed_sort_fields' => [
       'posts' => ['title', 'created_at', 'views'],
   ],
   

3. Eager Loading Use with() before listify() to optimize queries:

   $posts = Post::with('author')->listify()->get();
   

4. Testing Mock listify() in unit tests:

   $model = new Post();
   $this->assertEquals(
       ['title:asc'],
       $model->listify(['sort' => 'title:asc'])->getQuery()->orders
   );
   

Gotchas and Tips

Pitfalls

1. Case Sensitivity Sort fields in config/listify.php must match the model’s fillable/attributes exactly (e.g., created_at vs createdAt).

2. Reserved Keywords Avoid using sort as a custom column name—it conflicts with the package’s parameter.

3. Mass Assignment Ensure sort fields are fillable or use $fillable in the model:

   protected $fillable = ['title', 'views'];
   

4. Query Overrides Chaining listify() after orderBy() will reset the sort order. Use listify() first:

   // Correct
   Post::listify(['sort' => 'title'])->get();
   
   // Incorrect (overrides)
   Post::orderBy('id')->listify()->get();
   

Debugging

1. Inspect Queries Use Laravel’s query logging:

   \DB::enableQueryLog();
   $posts = Post::listify()->get();
   dd(\DB::getQueryLog());
   

2. Validate Config Check config/listify.php for typos in allowed_sort_fields or default_sort.

3. Sort Direction Ensure asc/desc is lowercase and separated by a colon (field:asc).

Extension Points

1. Custom Sort Logic Override the sortableFields() method in your model:

   public function sortableFields()
   {
       return ['custom_field', 'parent->name'];
   }
   

2. Dynamic Config Use listify() with a closure for runtime config:

   $posts = Post::listify(function ($query) {
       $query->where('status', 'published');
       return ['sort' => 'updated_at:desc'];
   })->get();
   

3. Event Hooks Listen for listify.before or listify.after events (if the package supports them):

   \Event::listen('listify.before', function ($query, $options) {
       // Modify query or options
   });
   

4. Localization Translate sort labels (e.g., "Newest" for created_at:desc) in your language files.