Generic Model Laravel Package

Getting Started

v2.0.1 is a housekeeping release — the changelog is a single merge commit ("Version/1.0.0 merge") plus a first-time contributor credit, with no documented API changes, deprecations, or breaking changes between v2.0.0 and v2.0.1. Treat it as a safe patch bump, but because the notes carry no upgrade guidance, verify the diff before bumping a production app.

Minimal path to first use:

1. composer require artisanbr/generic-model and check composer.json in the package for the actual PHP/Laravel constraints — v2.x is the current major line, so assume a modern Laravel skeleton (PHP 8+) and confirm before installing into an older app.
2. Look first at the package's src/ directory: the base class (typically GenericModel) and any trait it composes are the whole API surface. The README is thin relative to the code, so read the base class rather than trusting the docs.
3. Publish any config if the package ships one: php artisan vendor:publish --provider="ArtisanBr\GenericModel\GenericModelServiceProvider". If no provider is registered, skip this — the package may be pure class inheritance with no container bindings.
4. First use case: replace extends Model with extends GenericModel on one non-critical model and confirm nothing breaks.

use ArtisanBr\GenericModel\GenericModel;

class Post extends GenericModel
{
    protected $fillable = ['title', 'body', 'status'];
}

Run your existing test suite against that single model before converting others.

Implementation Patterns

Adopt one model at a time. Convert a leaf model (no children depending on its behaviour) first, exercise its full CRUD path, then migrate the rest. The failure modes of a generic base class show up in mass assignment and query building, so a canary model catches most of them.

Keep domain logic in the subclass. The value of a generic model is standardised create/read/update/delete and search/pagination behaviour. Resist putting business rules in the base layer; override per-model instead so a future major version doesn't ripple through your domain.

Wrap it behind a repository or service if you use the query helpers widely. A generic base class is convenient but couples every model to the package's method signatures. If the package's fluent search/listing helpers are used in controllers, funnel them through a repository so the v3 upgrade is a single-file change.

Use it as a consistent API resource layer. The strongest day-to-day pattern is: thin controller → repository/service → generic model. The model handles persistence and standard filtering; the service handles authorisation and domain invariants.

Fillable/guarded discipline. When a base class provides a generic create/update path, verify how it treats $request->all(). Prefer explicit DTOs or validated arrays over raw request payloads passed into any generic create method.

Testing. Add a small contract test per converted model asserting create/update/delete and one filtered listing. That gives you a regression net for future patch releases, which this package's changelog won't provide.

Gotchas and Tips

• The changelog is not a changelog. v2.0.1 documents a branch merge only. Before upgrading, run composer update artisanbr/generic-model --with-dependencies on a branch and diff vendor/artisanbr/generic-model/src. Watch for signature changes on overridden methods in your subclasses.
• Inheritance-based packages break silently on return-type changes. If your subclass overrides a base method and the base adds a return type in a patch release, PHP fatals only when that path executes. Cover the converted models with tests.
• Method name collisions. Generic base classes often define find, all, create, update, delete wrappers. If your subclass overrides Eloquent's versions, confirm the base isn't calling parent:: in a way that skips your override — or vice versa.
• Mass assignment surprises. Generic create/update helpers frequently call fill() or forceFill(). Confirm whether $guarded is respected; forceFill bypasses it entirely.
• Eager loading is not automatic. Any generic listing method that builds a query will respect $with but rarely infer relations from filters. Add $with on the model or pass it through the query layer.
• N+1 in generic listings. Generic pagination helpers that append computed attributes are a common N+1 source. Enable Model::preventLazyLoading() in local/testing to surface them early.
• Version confusion. The PR title references Version/1.0.0 merged into a v2.x line. If you're on v1.x and reading v2 docs (or vice versa), the API differs. Pin the major version in composer.json ("artisanbr/generic-model": "^2.0") so a surprise major doesn't land via a loose constraint.
• Extension points to prefer: subclass overrides and config, not edits to vendor files. If the package exposes no config, use a project-level abstract class (App\Models\BaseModel extends GenericModel) as your own stable seam — every app model extends that, so a package swap or upgrade touches one file.
• Evaluate whether you still need it. Generic-model packages are most valuable in CRUD-heavy admin backends. In a domain-driven app, the abstraction can cost more than it saves. v2.0.1 is a good moment to ask whether the models that barely use the base class should go back to plain Eloquent.