Getting Started

Confirm what you actually installed. The package is small; read it before trusting any blog post or its own README. The whole surface is roughly a base model class plus one or two traits/builders:
```
composer require saritasa/eloquent-custom
ls vendor/saritasa/eloquent-custom/src
cat vendor/saritasa/eloquent-custom/composer.json   # check required Laravel/Eloquent range
```
Map every exported class to a real Eloquent hook (Model, Builder, Collection, a trait's boot* method). That list is the package's feature set.
Find the namespace and the entry class. Typically Saritasa\...\CustomModel (a base model) and/or a HasCustom* trait. Grep for namespace and class:
```
grep -R "namespace\|^class\|^trait" vendor/saritasa/eloquent-custom/src
```
First use case — apply it to one model, not all of them. Either extend the provided base class:
```
use Saritasa\EloquentCustom\CustomModel; // verify exact FQCN

class Invoice extends CustomModel {}
```
Or, if you already have an App base model, compose the trait instead (see below) and leave App\Models\Model untouched until you know the package behaves under your Laravel version.

Smoke-test before migrating anything. In php artisan tinker:

(new App\Models\Invoice)->getClass();      // confirm it's the package class
App\Models\Invoice::query()->first();       // confirm the custom builder works
App\Models\Invoice::create([...]);          // confirm fillable/casts behavior

If the base class overrides newEloquentBuilder, newCollection, or casts, exercise those paths explicitly — those are the spots an old package usually breaks on a modern Laravel.

Decide early whether you need it at all. Zero stars, no dependents, archived since 2022. The realistic value is a few convenience methods or a small base-model layer. If the diff against plain Illuminate\Database\Eloquent\Model is under ~100 lines, the correct "getting started" step is to vendor those lines into app/Models/ rather than take a runtime dependency you cannot patch.

Implementation Patterns

Wrap the base model, don't inherit it everywhere. Put the package class one level up in your own hierarchy so you can drop it later:

namespace App\Models\Concerns;

use Saritasa\EloquentCustom\CustomModel as PackageModel;

abstract class AppBaseModel extends PackageModel
{
    // your project-wide behavior lives here, not in the vendor class
}

Then every model extends AppBaseModel. Swapping the package out becomes a one-line change instead of a find-and-replace across the app.

If you already have a base model, use the trait (preferred). Composition is more forgiving than the class hierarchy:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Saritasa\EloquentCustom\HasCustomBuilder; // example name — verify

abstract class AppModel extends Model
{
    use HasCustomBuilder;
}

Custom builder for query ergonomics. If the package ships a CustomBuilder, the day-to-day payoff is chainable scopes on every model:

// Package-style scope applied consistently across models
Invoice::query()
    ->orWhereLike('reference', $term)   // example scope — confirm against src
    ->orderBy('created_at')
    ->get();

Where it adds a builder subclass, keep your own scopes in a project trait rather than editing vendor code, and register them via #[Scope] or the classic scopeX convention so they compose with the package's builder.

Integration into existing apps — do it model by model. Migrate the highest-traffic model first, run the test suite, then fan out. Because the package touches the model base class, a single broken override (e.g. a save() that calls parent::save() differently) can surface as weird mass-assignment or timestamp bugs that only appear under load. One model at a time keeps the blast radius small.

Feature tests guard the extension points. Anything the package overrides on Model/Builder is a place a Laravel upgrade can break you. Write thin tests around each one:

it('still persists through the custom base model', function () {
    $invoice = Invoice::create(['reference' => 'X-1']);
    expect($invoice->fresh()->reference)->toBe('X-1');
});

Factories and seeders are unaffected — they use Model::factory() which resolves through the concrete class. But if the package customizes toArray/toJson, snapshot test your API responses so you notice the payload shape shifting.

Vendor it as a last resort. Since the repo is archived and you're on zero dependents, the sustainable pattern is: copy the handful of classes into app/Support/Eloquent/, keep the MIT header, and own the code. You get the convenience methods without an unmaintained dependency in composer.lock.

Gotchas and Tips

Archived + 2022 last release = no security patches, no Laravel 11/12 guarantees. Check composer.json's illuminate/* constraint. If it tops out at ^8|^9, do not force-install it with --ignore-platform-reqs; vendor the code instead.
Base-class overrides are the danger zone. A package like this typically overrides newEloquentBuilder, newCollection, casts, or timestamp handling. Those are exactly the methods that changed across Laravel 9→10→11. Diff the vendor class against Illuminate\Database\Eloquent\Model to see what it replaces:
```
diff <(php -r 'echo (new ReflectionClass(Illuminate\Database\Eloquent\Model::class))->getFileName();') \
     vendor/saritasa/eloquent-custom/src/CustomModel.php
```
boot* trait methods are magic and easy to miss. If the package defines bootHasCustomFields() or similar, it runs automatically on every model using the trait. Debugging "why is this model behaving oddly" starts with:
```
dump(get_class_methods(App\Models\Invoice::class));   // inherited methods
dump(class_uses_recursive(App\Models\Invoice::class)); // all traits in the chain
```
Conflict with existing global scopes / observers. If your app already adds a booted() hook or global scope in a base model, layering the package base class on top can double-apply or silently drop one. Test toSql() after the switch for any model with existing scopes.
Config quirks: expect none, verify anyway. If php artisan vendor:publish --provider="Saritasa\..." offers a config file, publish it and read the defaults — but with a package this small there may be no service provider at all. Check composer.json's extra.laravel.providers.
Debugging extension points. If a package builder method disappears at runtime, it usually means your model isn't returning the custom builder. Confirm with:
```
dump(Invoice::query()::class); // should be the package builder, not Illuminate\...\Builder
```
If it shows the stock builder, your model isn't using the trait, or newEloquentBuilder is being overridden further up your own hierarchy.
Pin the version and pin the lockfile. With zero dependents there's no community pressure to fix anything. "saritasa/eloquent-custom": "1.0.*" in composer.json with the exact hash in composer.lock is the only safe posture — and re-audit it on every Laravel major.
Cleanest extension point is your subclass, not theirs. All your project logic should live in App\Models\Concerns\* traits and AppBaseModel. Treat the vendor class as a frozen dependency you never edit and never rely on for anything you couldn't reimplement in an afternoon — which, for a package this size, is the realistic bar.

Eloquent Custom Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips