Laravel Purity Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require abbasudo/laravel-purity
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Abbasudo\Purity\PurityServiceProvider"
   

2. First Use Case: Add filter() to any Eloquent query:

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

   Now, clients can filter via URL params like:

   GET /posts?filters[title][$contains]=Laravel
   

3. Key Files to Review:

   • config/purity.php (for global settings like allowed fields)
   • app/Models/Post.php (to define custom filters if needed)
   • Official Docs (for filter types and syntax)

Implementation Patterns

Core Workflows

1. Basic Filtering:

   // Controller
   public function index()
   {
       return Post::filter()->get();
   }
   

   URL: /posts?filters[title][$contains]=search-term

2. Restricting Fields: Define allowed fields in the model or config:

   // Model
   protected $filterable = ['title', 'published_at', 'author.name'];
   
   // OR in config/purity.php
   'allowed_fields' => ['title', 'published_at'],
   

3. Custom Filters: Extend the package’s filter logic:

   use Abbasudo\Purity\Filters\Filter;
   
   class CustomFilter extends Filter
   {
       public function apply($query, $value)
       {
           return $query->where('custom_column', $value);
       }
   }
   

   Register in config/purity.php:

   'filters' => [
       'custom' => \App\Filters\CustomFilter::class,
   ],
   

4. Sorting:

   Post::filter()->sort()->get();
   

   URL: /posts?sort=-created_at

5. Livewire Integration:

   use Abbasudo\Purity\Livewire\HasFilters;
   
   class PostTable extends Component
   {
       use HasFilters;
   
       public function getQuery()
       {
           return Post::query();
       }
   }
   

Integration Tips

• APIs: Use filter() in API resources to standardize query params.
• Admin Panels: Combine with Laravel Scout for search-as-you-type.
• Testing: Mock Request to test filters:

  $request = Request::create('/posts', 'GET', ['filters' => ['title' => ['$contains' => 'test']]]);
  $this->app->instance('request', $request);
  

Gotchas and Tips

Pitfalls

1. Field Name Mismatches:

   • If filters[author.name] fails, ensure the relation is defined in the model and the field is allowed.
   • Debug with dd(Request::all()) to verify incoming params.

2. Database-Specific Quirks:

   • MySQL/MariaDB: Use backticks for reserved keywords (e.g., filters[order][$gt]=1).
   • PostgreSQL: Case-sensitive LIKE queries may need ILIKE (configure in config/purity.php).

3. Silent Mode:

   • By default, invalid filters throw 422 errors. Disable in config:

     'silent' => true,
     

4. Nested Relations:

   • Ensure relations are eager-loaded or use with():

     Post::with('author')->filter()->get();
     

5. Performance:

   • Avoid complex filters on large datasets without limit()/offset().
   • Use select() to limit columns:

     Post::select('id', 'title')->filter()->get();
     

Debugging Tips

• Log Filters: Add to app/Providers/AppServiceProvider.php:

  Purity::macro('debug', function () {
      \Log::debug('Filters:', Request::query('filters'));
      return $this;
  });
  

  Usage:

  Post::filter()->debug()->get();
  

• Query Inspection: Use Laravel Debugbar or toSql():

  $query = Post::filter()->toSql();
  \Log::info($query);
  

Extension Points

1. Custom Resolver: Override the default filter resolver:

   Purity::setResolver(function ($query, $filters) {
       // Custom logic
       return $query->where('custom_logic', $filters);
   });
   

2. Dynamic Field Whitelisting: Use a closure in config/purity.php:

   'allowed_fields' => function () {
       return auth()->user()->can('admin') ? ['*'] : ['title', 'published_at'];
   },
   

3. Filter Groups: Combine filters with logical operators:

   // URL: /posts?filters[0][title][$contains]=term&filters[1][status][$eq]=published
   Post::filter()->get();
   

   Use $and/$or for grouped logic:

   // URL: /posts?filters[$and][0][title][$contains]=term&filters[$and][1][status][$eq]=published
   

4. Sorting Nulls: Configure null handling in config/purity.php:

   'sort_nulls' => 'last', // or 'first'