Powermodel Laravel Package

Getting Started

1. Install and pin.

   composer require gsferro/powermodel
   

   Because adoption is low (5 stars, 0 dependents), pin an exact version in composer.json ("gsferro/powermodel": "1.0.x") rather than a caret range so a surprise release can't silently change base-model behavior across your app.

2. Read in this order before writing code. The package is small enough to audit in one sitting:

   • README.md — the intended API surface and any published config.
   • src/ — the service provider and the model/trait that carries the "power" behavior. This is the single most important step; with no ecosystem around it, the source is the documentation.
   • config/powermodel.php (if present) — feature flags and defaults.

3. Publish config if offered.

   php artisan vendor:publish --tag=powermodel-config
   

   Check the tag name against the provider's publishes() call; small packages often use non-obvious tags.

4. First use case. Don't retrofit every model. Pick one read-heavy CRUD resource (an admin index page) and either extend the package's base model or apply its trait to a single existing model. Then wire up the package's query helpers for filtering/sorting/searching on that resource and confirm generated SQL with ->toSql() before trusting it.

5. Verify Laravel compatibility. Confirm the illuminate/* constraints in the package's composer.json match your Laravel version; a package last released Jan 2025 may not have been tested against the newest minor.

Implementation Patterns

• Base-model extension. The most common pattern with "power model" packages: create app/Models/PowerModel.php that extends the package base, then have your domain models extend it. This centralizes helpers but couples every model to the package — keep a app/Models/BaseModel.php shim of your own that extends the package class, so a future swap is a one-file change.
• Trait-on-demand. Prefer applying the package trait to selected models rather than globally. It keeps the blast radius small and makes it obvious which models depend on the package.
• Query-helper composition. Typical day-to-day use is chaining filter/sort/search helpers onto Eloquent builders in controllers or repository classes:

  User::query()
      ->filter($request->only(['status', 'role']))
      ->sort($request->query('sort', '-created_at'))
      ->paginate();
  

  Keep the raw Request out of the model layer — pass validated arrays from a form request or a dedicated query object so the helpers stay testable.
• Repository / service boundary. Treat the helpers as a convenience layer only. Business queries belong in services or repositories; helpers are for the repetitive index-table plumbing. This also gives you a fallback path if the package is abandoned: rewrite the repository, not every controller.
• Caching pattern. If the package exposes caching helpers on models, wrap reads in your own cache keys ("users:index:{$filtersHash}"), not the package's implicit keys, so you control invalidation on writes.
• Testing. Write a small base test case that boots the package's provider and asserts one known helper produces the expected SQL against a SQLite in-memory database. That single test catches most regressions on Laravel upgrades.

Gotchas and Tips

• Maintenance risk is the headline gotcha. 0 dependents, 5 stars, and a single recent release means no community bug-fixing pressure. Budget for the possibility of vendoring or forking. Keep package usage behind your own base model/repository so removal is cheap.
• Trait conflicts. Power-model traits frequently override newEloquentBuilder, newQuery, scope* methods, or getAttribute. If you also use SoftDeletes, HasFactory, or custom casts, test for collisions — two traits defining the same method cause a fatal error, and one silently winning in a parent/child hierarchy is worse.
• Global scopes are the classic footgun. If the package registers global scopes (soft-delete-like behavior, tenant filters, etc.), they will leak into raw queries, pivot queries, and exists() checks. Check getGlobalScopes() in php artisan tinker and use withoutGlobalScope() where needed.
• Debugging helpers. When a chained helper produces unexpected SQL:

  DB::listen(fn ($q) => logger($q->sql, $q->bindings));
  

  or ->ddRawSql() / ->toSql() on the builder. Bindings are the usual source of "the filter isn't working" — helper names rarely match column names exactly.
• Config caching. After publishing config, php artisan config:cache can mask a missing key; clear it (config:clear) when behavior doesn't match config/powermodel.php.
• Extension points. If the base model is abstract, subclass it rather than editing vendor code. If helpers are protected, override them in your shim model. If the package has no extension points at all, that's a signal to limit adoption to non-critical models.
• Version pinning + lock file. The last release date (2025-01-13) with a low score means a composer.lock commit is non-negotiable. Also watch composer outdated gsferro/powermodel during Laravel upgrades and read the diff before bumping.
• Document the dependency. Add a short ADR or README note: "Models X, Y, Z depend on gsferro/powermodel for filter/sort helpers; removal plan is to inline into app/Models/BaseModel.php." Future you (or a new hire) will thank you.