Referential Bundle Laravel Package

Getting Started

First, reconcile the framing: mpp/referential-bundle is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no config/referential.php, no Artisan commands wired into your app. Day-to-day "leverage" from a Laravel codebase is therefore pattern extraction and reimplementation, not composer require. Treat any attempt to load it directly as a research spike, not an integration.

Concrete first steps:

1. Confirm the shape before you touch composer.

   composer show mpp/referential-bundle --all
   

   Look for "type": "symfony-bundle", the Symfony constraint (^5.4 / ^6.x), and whether Doctrine is a hard dependency. This tells you the cost of the port in one command.

2. Clone and read — don't install into your app. A throwaway Symfony skeleton (or just git clone + cat) is enough. Nothing here is designed to coexist with Eloquent.

3. Read in this order:

   • src/DependencyInjection/Configuration.php — reveals the config root key and every tunable.
   • src/Entity/ — the actual data model; this is the thing worth borrowing.
   • src/Repository/ — read patterns, and check for findAll without pagination or caching.
   • src/Resources/config/ — service wiring, and whether anything is tagged or globally registered.
   • src/Fixtures, src/Command, migrations — how seed data is owned and refreshed.
   • tests/ — usually the only runnable specification of intended behavior.

4. First use case to design against: a read-mostly source of reference data feeding form dropdowns and validation rules. In Laravel that becomes a Referential Eloquent model plus a small ReferentialRepository, seeded from the bundle's fixtures, cached with Cache::rememberForever, and consumed via a ReferentialChoices service injected into FormRequests and Blade/Filament forms.

final class ReferentialChoices
{
    public function __construct(private ReferentialRepository $referentials) {}

    public function for(string $code): array
    {
        return Cache::rememberForever("referential.{$code}", fn () =>
            $this->referentials->options(code: $code)
        );
    }
}

Prefer stable codes over primary keys — the bundle's design almost certainly assumes this, and so should yours, because it lets you re-seed without rewriting foreign references.

Implementation Patterns

• Anti-corruption layer, not a dependency. Wrap whatever you take from the bundle behind App\Referential\*. Your domain code should never import Mpp\ReferentialBundle\.... This is the single most important pattern because there is no upstream to protect you from breaking changes.

• Read-through cache on the hot path. Reference data is low-write, high-read. A per-request lookup without caching is a common failure in small bundles. Cache the whole list keyed by code and bust it on write:

  Referential::saved(fn ($r) => Cache::forget("referential.{$r->code}"));
  

• Two-tier model: Referential (the list) → ReferentialItem (the values). This mirrors the "configure once, inject consistently" description and maps cleanly onto Eloquent. A category taxonomy and a country list become rows in the same table, not bespoke countries and categories tables.

• Seed via migration or seeder, not fixtures-in-code. The bundle's fixtures are Symfony fixtures; port them into database/seeders/ReferentialSeeder.php and run them idempotently (updateOrCreate keyed on code). This makes the list refreshable as a deploy step rather than a manual edit.

• Validation via Rule::in. Once you own the list, 'country' => ['required', Rule::in($choices->for('countries'))] — no separate validation package needed. Same list powers the form.

• Audit as a first-class concern, not an afterthought. The bundle almost certainly lacks change history. If the data touches money, eligibility, or compliance, add a referential_changes table (who / what / when / why) at the point you reimplement — it is cheap now and expensive later.

• Fork the upstream, don't shadow it. Pin the fork to a commit SHA in composer.json (or vendor the files) and record the SHA in a REFERENTIAL-UPSTREAM.md. This lets you git diff against upstream if it ever moves.

• Integration tip for Filament. Filament resource over the Referential / ReferentialItem tables gives non-engineers the "edit the list without a deploy" capability the bundle is trying to enable — this is where the pattern actually pays off day-to-day.

Gotchas and Tips

• The framework mismatch is the first gotcha. Do not attempt to install the Symfony bundle inside a Laravel app "just to see." It brings symfony/framework-bundle, symfony/dependency-injection, and DoctrineBundle into a stack that expects neither. The porting cost is measured in days, not minutes.

• Zero stars, zero dependents is the real config. There is no changelog, no security-response process, no issue history to mine for failure modes. Support = reading the source. This is acceptable for a stable lookup table and unacceptable for anything on the money or auth path.

• No caching by default. The description says "cache-friendly," not "cached." Confirm in src/Repository whether lookups hit the DB on every call. If they do, wrap them yourself.

• N+1 in findAll-style APIs is common. Small bundles often ship findAll() without pagination because the reference lists were small. Watch for it in the port.

• French/French-fintech assumptions are baked in. Reference data, locale defaults, and validation rules from a French broker are unlikely to be generic. Audit src/Entity for country/currency/risk codes that assume EU context before building UX on top.

• No audit trail. Assume absent until proven otherwise. Search for updatedBy, version, ChangedAt, or an event listener. If nothing, plan to add it during the port.

• Locale in the bundle's seed data is not the same as i18n. Labels for values (e.g. French country names) may need your own translation table layered on top.

• The DI extension can register global services or event subscribers. Audit DependencyInjection/MppReferentialExtension.php during the spike — an internal extraction sometimes wires behavior outside its own namespace, which is invisible in a Laravel port but explains oddities if you ever do run the Symfony side.

• Verify the release situation. If there are no tags and only main, you cannot pin a version meaningfully — clone the repo into your own vendor or fork and pin the commit SHA. Never track main for a dependency that touches anything business-critical.

• Extension points are limited by design. This is a "bundle registers services" package, not a "plugin" package. Do not expect strategy interfaces for swapping storage or injecting custom validators. If you need extension points, that is your signal to reimplement rather than adopt.

• Decision rule for the team: adopt-as-dependency only on Symfony with an owner and a pinned fork; on Laravel, harvest the entity model and seed data, reimplement behind App\Referential, and treat the upstream as a design reference with no maintenance contract.