Osmose Laravel Package

Product Decisions This Supports

• Build vs. Buy: Buy – Osmose eliminates the need to manually implement filtering logic for Eloquent models, reducing boilerplate code and maintenance overhead. Ideal for teams prioritizing developer velocity and consistency.
• Feature Roadmap:
  • API/Backend: Standardize filtering across all Eloquent queries (e.g., admin dashboards, public APIs) with reusable filter classes.
  • Search/Discovery: Enable dynamic, user-driven filtering (e.g., e-commerce product listings, content platforms) via URL parameters.
  • Data Integrity: Enforce mandatory filters (e.g., bound() method for admin-only queries) to ensure compliance or security constraints.
  • Date Handling: Support for date ranges and custom date filtering (e.g., created_at ranges) for time-sensitive data.
• Use Cases:
  • Admin Panels: Filter records by relationships (e.g., role=god), direct columns (e.g., gender=male), or custom callbacks.
  • Public APIs: Expose filtering capabilities to clients without exposing raw SQL (e.g., /products?category=electronics&price_min=50).
  • Legacy System Integration: Modernize filtering in older Laravel applications without rewriting existing queries.
  • Multi-Tenant Apps: Apply tenant-specific filters via bound() rules (e.g., column:tenant_id,123).

When to Consider This Package

• Adopt Osmose if:

  • Your Laravel app heavily relies on Eloquent queries with repetitive filtering logic (e.g., >50% of queries include where clauses).
  • You need to support dynamic filtering via URL parameters (e.g., frontend-driven tables, APIs).
  • Your team lacks dedicated backend resources to build/maintain custom filtering solutions.
  • You require relationship filtering (e.g., filtering posts by author, products by category).
  • You need date-range filtering (e.g., "show records from last 30 days") without writing custom Carbon logic.
  • You want to enforce mandatory filters (e.g., bound() rules for admin-only data access).
  • Your project uses Laravel 9+ (PHP 8 support) and Eloquent models.

• Look Elsewhere if:

  • Your filtering needs are static (e.g., hardcoded queries in a single controller).
  • You require full-text search (consider Laravel Scout or Algolia).
  • Your app uses non-Eloquent data sources (e.g., raw SQL, NoSQL).
  • You need complex aggregations (e.g., GROUP BY, JOIN-heavy queries) beyond simple filtering.
  • Your team prefers raw query builders over abstraction layers.
  • You’re on Laravel <8.0 (Osmose drops PHP 7 support).

How to Pitch It (Stakeholders)

For Executives: *"Osmose is a plug-and-play solution to standardize and accelerate filtering across our Laravel backend. By adopting this package, we can:

• Reduce development time by 30–50% for filtering features (no more reinventing the wheel for where clauses).
• Improve API consistency with reusable filter classes, making our public endpoints more predictable for clients.
• Enhance admin tools with dynamic, relationship-based filtering (e.g., 'Show all villain characters').
• Cut technical debt by consolidating filtering logic into maintainable, testable components. Cost: Minimal (MIT-licensed, open-source). ROI: Faster feature delivery and fewer bugs in query logic."*

For Engineers: *"Osmose provides a clean, Laravel-native way to handle Eloquent filtering with three key benefits:

1. Scaffolding: Generate filter classes in seconds with php artisan osmose:make-filter.
2. Flexibility: Supports direct column filters (column:id), relationship filters (relationship:roles,name), and custom callbacks for edge cases.
3. Global Function: Use osmose(FilterClass::class) to auto-load models, reducing boilerplate in controllers. Example use case: Replace 20 lines of where clauses in a controller with a single filter class. Also supports date ranges and mandatory filters (bound()) for security/compliance. Trade-offs: Slight learning curve for the filter driver syntax, but docs and artisan commands make it intuitive."*