- How do I install Osmose in my Laravel project?
- Run `composer require agog/osmose` to install via Composer. No additional configuration is needed beyond the package itself. The `osmose:make-filter` Artisan command will scaffold filter classes automatically.
- What Laravel versions does Osmose support?
- Osmose is designed for Laravel 9+ and requires PHP 8+. Check the [changelog](https://github.com/franciskisiara/osmose) for version-specific updates, especially if migrating from v2.x to v3.0.0.
- Can I use Osmose for filtering API responses with Laravel's API Resources?
- Yes, Osmose integrates seamlessly with API Resources. Apply filters via `sieve()` in your controller, then pass the filtered query to `Resource::collection()` or `->paginate()`. Example: `return UserResource::collection($filter->sieve(User::query()))`.
- How do I define a filter for a relationship (e.g., filtering users by their roles)?
- Use the `RelationshipFilter` driver in your `residue()` method. Define the relationship name and the filter logic, like `['role.name' => new RelationshipFilter('role', 'name', 'like', '%admin%')]`. Ensure to eager-load relationships with `with()` to avoid N+1 queries.
- What’s the difference between `osmose()` and `sieve()` for applying filters?
- The `osmose()` helper is a shortcut for simple cases, like `osmose(User::query(), UserFilter::class)`. For complex logic, use `sieve()` directly on a filter instance, e.g., `$filter->sieve(User::query())`. `sieve()` offers more control, like customizing bound values dynamically.
- How do I handle optional filters (e.g., when a request parameter might be missing)?
- Osmose’s `bound()` method checks if a parameter exists before applying rules. For optional filters, use `bound('param') ? ['param' => new DirectFilter('column')] : []` in your `residue()` method. Test edge cases like empty or null values to avoid unexpected behavior.
- Are there performance concerns with Osmose, especially for large datasets?
- Relationship filters and complex callbacks can impact performance. Use `->toSql()` to inspect generated queries and optimize with eager loading (`with()`) or caching (`->remember()`). For critical queries, benchmark with tools like Laravel Debugbar or Xdebug.
- Can I extend Osmose to add custom filter drivers (e.g., for full-text search)?
- Yes, Osmose supports custom drivers via the `OsmoseFilterInterface`. Create a new class implementing the interface and register it in your filter’s `residue()` method. Review the existing drivers (`DirectFilter`, `CallbackFilter`, `RelationshipFilter`) for implementation patterns.
- How do I test Osmose filters in my Laravel application?
- Test `residue()` logic with unit tests for individual rules, and use Laravel’s query builder assertions (e.g., `expectsQuery()` in Pest) to verify generated SQL. Mock requests or use `Http::fake()` to simulate filtered queries in integration tests.
- What alternatives exist to Osmose for Eloquent filtering in Laravel?
- Alternatives include `spatie/laravel-query-builder` (for dynamic query building), `beberlei/attributes` (for attribute-based filtering), or `archtechx/telescope-filters` (for admin panels). Osmose stands out for its Artisan scaffolding and dedicated filter classes, reducing boilerplate.