Smart Laravel Package

Getting Started

• Install with composer require dietercoopman/smart and commit the lockfile change. Because v2.0 is a major bump, read the diff at https://github.com/dietercoopman/smart/compare/v1.9...v2.0 before running composer update — a 1.9 → 2.0 jump almost always carries a PHP/Laravel minimum-version raise and at least one renamed method or signature change.
• Publish any shipped config (php artisan vendor:publish --tag=smart-config) and diff it against the package's default file rather than overwriting your existing copy.
• Look first at the package README's usage block and the src/ directory: the public surface is typically a trait plus a query-builder scope or facade call, so you can read the whole API in a few minutes.
• First use case: make one existing listing page searchable. Add the trait to the model, replace your hand-rolled where('name','like',...) chain with the package call in the controller, and paginate the result. Compare output side-by-side with the old query before deleting the old code.

Implementation Patterns

• Controller-level search endpoint. Keep the search term in a $request->string('q') and feed it into the scope, then chain normal Eloquent on top (->with('team')->paginate(25)). The package should compose with the builder, not replace it — if it returns a collection, wrap it yourself.
• Model trait over inheritance. Apply the trait only to models you actually search. Blanket-applying it to every model makes it hard to reason about which columns are exposed.
• Explicit column allow-lists. Where the API accepts a column list, always pass one. Falling back to "search everything" means a later migration adding a internal_notes column silently exposes it to users.
• Wrap it in your own scope. Create a local scopeSearchable(Builder $q, ?string $term) on the model or a small action class that handles empty terms, trimming, and the package call. This gives you one place to swap the implementation (e.g. to Scout) later and keeps package-specific syntax out of controllers.
• Relevance + pagination ordering. If the package exposes a relevance/score ordering, apply it before paginate(), and add a deterministic tiebreaker (->orderBy('id')) — otherwise page 2 can repeat or skip rows.
• Livewire / Inertia integration. Debounce the input, keep the term in the query string (->withQueryString()), and make sure the search runs against a query object, not a hydrated collection, so pagination stays cheap.
• Testing. Assert on the query shape (assertDatabaseCount, specific IDs in the result set) rather than snapshotting order. Include cases for empty term, single word, multiple words, and a term containing % or _.

Gotchas and Tips

• Pin the major version during rollout. Use "dietercoopman/smart": "^2.0" and run the upgrade on a branch. Check composer why-not dietercoopman/smart 2.0 to see what's holding you back if resolution fails.
• Expect an upgrade guide, not just a changelog. The release notes here are only a compare link, so diff the README.md between the v1.9 and v2.0 tags — that is usually where renamed methods, dropped config keys, and new required arguments are documented.
• LIKE '%term%' does not use indexes. For tables past a few hundred thousand rows, measure before shipping. The usual escape hatch is a MySQL FULLTEXT index or Laravel Scout/Meilisearch — keep the package behind your own scope so that swap is a one-file change.
• Escape wildcards in user input. A user typing % or _ will match far more than intended unless the package escapes it or you do. Pass raw input through a sanitiser and treat anything interpolated into a column or ORDER BY as an injection vector.
• Watch collation and case sensitivity. MySQL's default collation is case-insensitive, PostgreSQL is not. If search behaviour differs between your local SQLite and production Postgres, this is why — don't chase it as a package bug.
• Trim and normalise before calling. Leading/trailing whitespace, multiple internal spaces, and empty strings are the most common cause of "search returns nothing." Handle blank($term) by returning the unfiltered query.
• Debug with the builder, not the results. ->toSql() plus ->getBindings() immediately after the scope call tells you whether the package appended a where, a join, or nothing at all. Do this before assuming the trait isn't applied.
• Check composer show dietercoopman/smart after upgrade. Confirm the installed version and its declared PHP/Laravel constraints, then run your test suite — a major bump that "just installs" can still change default behaviour silently.
• Extension points to prefer: config file and published views are stable across majors; protected methods and internal classes are not. If you need behaviour the package doesn't expose, add a decorator or a local scope rather than extending its internals or subclassing its query class.