Persistence Bundle Laravel Package

Getting Started

First, reset expectations: this is not a Laravel package. funddy/persistence-bundle is a Symfony bundle (composer type symfony-bundle) that wires the companion funddy/persistence component into a Symfony DI container. There is no service provider, no facade, no config/persistence.php, and no auto-discovery. If you are assessing it for a Laravel codebase, treat it as research material for the underlying component, not as a dependency you install.

Minimal steps:

1. Read composer.json first — check the require block for Symfony and PHP constraints. Given the package's age and adoption (3 stars, 0 dependents), expect Symfony 2.x/3.x-era constraints that will not resolve on PHP 8 + Symfony 6/7. Run composer why-not php 8.2 before anything else.
2. Open the bundle class and DependencyInjection/*Extension.php plus Resources/config/*.{yml,xml}. That is where the entire public surface lives — the extension defines the config tree and the service definitions you can actually inject.
3. Look at compiler passes (if any). That is where repository/service tagging happens; it tells you the intended registration pattern.
4. Cross-reference the sibling repo funddy/persistence for the real API (persistence manager, repository contracts, unit-of-work semantics). The bundle is thin; the component is the product.
5. First use case: register the bundle in AppKernel/bundles.php, define an aggregate repository as a service, inject the repository (not the container) into a command or controller, and persist an aggregate.

For Laravel specifically, the pragmatic "first use case" is: skip the bundle, and if the abstraction appeals, bind the component's persistence interface to your own implementation in AppServiceProvider.

Implementation Patterns

• Constructor injection, not container pulls. The bundle exposes services, so inject the concrete repository or persistence interface into controllers, console commands, and handlers. Avoid $container->get() — it defeats the point of the DI wiring the bundle provides.
• One repository per aggregate root. The Funddy persistence abstraction is domain-oriented rather than table-oriented. Keep repositories narrow (find by identity, add, remove) and let the persistence manager coordinate flush/identity-map behavior.
• Transactional boundary at the application layer. Wrap a handler/command in a single unit of work: mutate aggregates, then flush once. If the component offers a transactional decorator or explicit begin/commit, put it in a command bus middleware rather than sprinkling it through services.
• Domain events after commit. If the component exposes after-commit hooks, publish events there, not inside the mutation path. If it doesn't, collect events on the aggregate and dispatch them explicitly after the enclosing transaction succeeds.
• Interface-first ports. Define your own OrderRepository interface in the domain, and have the bundle-wired implementation satisfy it. This is what makes the package replaceable when you inevitably migrate off it.
• Laravel translation of the same pattern: bind the interface to an Eloquent- or query-builder-backed implementation in a service provider; back the "flush" with DB::transaction(); hook after-commit work onto DB::afterCommit() or a terminable middleware. The architectural shape survives the port; the bundle does not.
• Testing: write an in-memory implementation of the repository contract for fast unit tests, and reserve the real bundle-wired implementation for integration tests. This is the single highest-leverage thing you can do if you adopt the abstraction.

Gotchas and Tips

• Adoption risk is the headline gotcha. 3 stars, 0 dependents, score near zero. Assume no maintainer response, no security patches, and no compatibility work. Pin an exact version, vendor the source into packages/ or a fork, and budget for owning it.
• The bundle name is misleading. Almost all useful behavior lives in funddy/persistence. Installing the bundle without understanding the component gets you service definitions you can't reason about.
• Config alias must match the bundle name. Symfony extensions resolve config under a snake-cased alias derived from the bundle class. If your bundle registration name differs from the expected alias, your config is silently ignored rather than erroring.
• Compiler pass ordering matters. If repository services aren't tagged before the consuming pass runs, you get "service not found" at compile time, not runtime. Use debug:container --tag=<tag> and debug:container --show-private to confirm registration before debugging business logic.
• Debugging strategy: most failures here are container-compilation failures, not code failures. Work outward — bin/console lint:container, then debug:container, then the extension's config tree, then your code. A Definition-level dump() inside the pass is often faster than reading the YAML.
• Don't flush inside loops. Whether it's this component or Doctrine, repeated flush calls per iteration destroy throughput. Batch mutations and flush once per unit of work.
• Extension points, in order of safety: decorate the persistence service (Symfony decorates:), add a tagged repository, then subclass/override a service definition in your app config. Avoid modifying the bundle's own config files — you'll lose the changes on the next fork sync.
• Hard cutoff for Laravel teams: if the constraint solve fails on your PHP version (very likely), stop. Do not patch vendor constraints — the code itself may rely on removed Symfony APIs. Copy the ~200 lines of abstraction you actually need into your own app/Support/Persistence namespace and move on. You'll get 90% of the design value at 5% of the maintenance cost.