Turbine Laravel Package

Getting Started

Install with Composer and follow the package README for publishing config/assets or running migrations, if required:

composer require power-components/turbine

Look first at the README, the published config/turbine.php if present, and the diff for PR #4 (“Review filters”). Since v0.9.0 is still pre-1.0, pin the version in composer.json while evaluating it.

A practical first use case: add a filter to an existing review/moderation listing or query-backed screen, then verify the generated SQL, pagination counts, and empty-state behavior. Start with one filter and one test before wiring it into a larger admin workflow.

Implementation Patterns

• Treat filters as composable query constraints. Keep filter definitions close to the screen/component that owns them, and test each filter independently plus common combinations.
• Validate and allowlist filter keys before applying them. Do not pass raw request column names into the query layer.
• Pair review/filter screens with authorization checks. A filter should not expose records the current user cannot already view.
• Add database indexes for columns commonly used by filters, especially status, reviewer, date, and foreign-key fields.
• For relation-based filters, prefer whereHas() or explicit joins with distinct() to avoid duplicate rows and incorrect pagination totals.
• Use Laravel’s query log or dd()/dump() on the builder while developing filters; confirm that empty, null, and “all” values behave as intended.
• If the package exposes custom filter classes or callbacks, keep custom logic in those extension points rather than modifying vendor code.

Gotchas and Tips

• v0.9.0’s release notes are very sparse: the only documented change is PR #4, “Review filters.” Review the PR diff before upgrading, especially if you already depend on filter behavior from v0.8.2.
• No breaking changes are called out, but this is still a pre-1.0 package. Pin exact versions and run your filter/listing tests after each update.
• Watch for filter semantics around empty strings, null, 0, and “no filter selected.” These often cause unexpected query constraints or missing rows.
• Filtering on related records can introduce duplicate results or inflated counts. Check count(), pagination, and distinct() behavior explicitly.
• If filters are applied from request input, validate them at the boundary and fail closed on unknown keys.
• Debug from the query layer first: inspect the final SQL and bindings before assuming the UI component is wrong.
• Check the package’s configuration and extension points after publishing. Avoid editing vendor files; prefer published config, custom filter classes, or documented callbacks.