Eloquent Export Laravel Package

Getting Started

This is a pre-1.0 package (v0.1.2), so treat the API as unstable and pin the exact version ("vendor/package": "0.1.2") rather than floating on ^0.1 until you have a test suite covering your usage.

1. Install and publish config:

composer require vendor/package:0.1.2
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"

2. Look first at the tests, not the README. On a 0.1.x release with a changelog this terse ("Improves handling of mutators and foreign data links"), the test suite is the only reliable specification of how mutators are resolved and how foreign links are matched. tests/ will show you which Eloquent hooks (setAttribute, getAttribute, Attribute casts, $casts) the package actually participates in.

3. First use case: take one existing model that already has a classic getFooAttribute() / setFooAttribute() mutator pair and belongs to a record sourced from a second connection or external system. Point the package at that single model before rolling it out. This is the exact intersection the 0.1.2 release touched, so it doubles as a smoke test for the version bump.

4. Run php artisan about / check the published config for the driver, connection, and key-mapping options, then confirm a round-trip: write through the mutator, read back, and verify the foreign link resolves to the expected model instance.

Implementation Patterns

Mutator-first modelling. Define your transformations on the model as you normally would — Laravel-native mutators and Attribute-style casts — and let the package handle persistence/mapping. Keeping transformation logic in the model (rather than in the package's config or a mapper class) means the code stays readable to developers who don't know the package, and it keeps you portable if you drop the package later.

protected function externalRef(): Attribute
{
    return Attribute::make(
        get: fn ($value) => $this->resolveRef($value),
        set: fn ($value) => is_array($value) ? $value['id'] : $value,
    );
}

Pair every mutator with a test. Because 0.1.2 changed mutator handling, any mutator you rely on should have an assertion on both the set and get path, plus a getDirty() / isDirty() assertion after setting. This is where regressions from this kind of release surface first.

Foreign links as an explicit mapping layer. Rather than scattering external IDs through your schema, keep a single mapping surface (config array or a dedicated pivot/link model) and resolve through the package. That gives you one place to debug when a link fails to resolve, instead of hunting through joins.

Eager-load foreign links. If link resolution hits a remote connection, it behaves like an N+1 waiting to happen. Resolve in bulk where the API allows it, and wrap any per-model resolution in a DB::listen() or query-count assertion in tests so a regression is caught in CI rather than in production latency dashboards.

Integration with factories and seeders. Build factories that produce records with foreign links already attached, so RefreshDatabase tests exercise the link path on every run rather than only in the one test that remembers to set it up.

Wrap the package behind a small internal seam. An ExternalDataMapper or similar class of your own that delegates to the package gives you a single file to change when 0.2.0 lands, and a place to shim behaviour you can't configure.

Gotchas and Tips

• Semver risk is real. 0.1.x makes no compatibility promises. Lock the version in composer.json, commit composer.lock, and read the diff of src/ — not just the release notes — before bumping. "Improves handling of mutators" can silently change the order in which setters run relative to casts.
• Mutator vs. cast ordering. When a column is both cast ($casts) and mutated (setXAttribute), the interaction order matters and is easy to get wrong. Assert the stored raw value with getRawOriginal() after a save, not just the hydrated attribute.
• Dirty tracking after mutation. Setting through a mutator that returns a transformed value can leave isDirty() reporting true for a value that hasn't logically changed. If you branch on isDirty() (audit logs, event listeners, sync jobs), guard against spurious writes.
• Nulls and missing foreign data. A foreign link that resolves to nothing is the most common production failure. Decide explicitly per-link whether that means null, an exception, or a skipped sync — and encode that decision in config, not in a try/catch three layers up.
• Mass assignment. Mutators that reshape arrays on set can defeat $fillable expectations. Prefer $guarded scoping or a DTO/fill() with explicit keys when accepting external payloads.
• Config caching. php artisan config:cache will freeze the published config. If the package reads connection details at runtime in a way that isn't cache-safe, you'll only find out after a deploy — test a cached-config boot in CI.
• Debugging: enable the package's log channel (or add a temporary Log::debug() in your own mapper seam), and log the resolved link payload alongside the raw external ID. Nearly every "link not resolving" bug is a type mismatch — "123" vs 123, or a trailing space from an import.
• Extension points: subclassing the package's base model/mapper and overriding a protected resolution method is usually more stable across patch releases than relying on its public configuration surface. Prefer that when you need behaviour the config doesn't expose, and re-check the override after each bump.
• Report upstream. Given the terseness of the changelog, file issues with a failing test case attached; on a project this young that's the fastest path to a fix in 0.1.3.