Base Bundle Laravel Package

Getting Started

Confirm what you actually have before installing. The -bundle suffix and the useperform vendor strongly suggest a Symfony bundle, not a Laravel package. Open the repo's composer.json and check:

• "type": "symfony-bundle" (vs library)
• require on symfony/framework-bundle / symfony/dependency-injection
• PHP constraint

If it's a Symfony bundle, this is not a composer require-and-go dependency for a Laravel app — it's a small integration project. Decide that up front.

Minimal steps (Symfony path):

1. composer require perform/base-bundle — pin an exact version (see Gotchas).
2. Register in config/bundles.php if Flex doesn't auto-register it.
3. Look for DependencyInjection/Configuration.php to see what's configurable, then create config/packages/perform_base.yaml.
4. Run bin/console debug:container perform_ and bin/console lint:container to confirm wiring.

Read in this order: README → DependencyInjection/ → Resources/config/services.xml. That triangle tells you what gets registered, what's configurable, and what base classes you're meant to extend.

First use case: wire up one console command or one read-only route that touches the bundle's core services. Prove the container wiring end-to-end before building anything on top — with a 1-star package, wiring is the highest-risk step.

Implementation Patterns

Treat it as a foundation, not a library. A "base bundle" earns its keep by giving you abstract classes and pre-wired services you extend. Inventory the public API (services.xml, interfaces, abstract classes) and write a thin internal adapter so your app code depends on your interfaces, not the bundle's. This is the single most valuable habit with a low-signal dependency.

Config-first. Express behavior through the bundle's YAML rather than subclassing its config classes. Extension config is the most stable surface; internal classes are not.

Decorate, don't fork. Use Symfony service decoration (decorates: / !decorated) to override base services. If the bundle exposes tagged services or compiler passes, register yours via tags — that's the intended composability path.

Laravel bridge, if you must. Isolate everything in one service provider plus one config file:

• mergeConfigFrom() for the bundle's defaults
• bind resolved services as singletons via a wrapped Symfony container
• translate the bundle's events into Laravel events
• do not leak Symfony types into controllers/models

Keep the bridge in a single namespace so removal is a one-line composer change.

Upgrade workflow. Pin "perform/base-bundle": "x.y.*" in composer.json, commit the lockfile, and do version bumps on a dedicated branch with your own smoke test — there's no upstream test signal to rely on.

Gotchas and Tips

• Ecosystem mismatch is the big one. No Laravel auto-discovery, no facades, no vendor:publish. If the team is Laravel-only, budget the bridge or reject the dependency — don't hand-wave this.
• Bus factor. 1 star, 0 dependents, single maintainer. Assume zero upstream support and no security patch cadence. The adapter layer from above is what makes replacing it cheap.
• Config quirks. Symfony bundles commonly load defaults only when a config key is present. Check Configuration::getConfigTreeBuilder() for ->defaultValue() vs ->cannotBeEmpty(). Silent no-ops (service present but inert) are the classic failure mode.
• Debugging commands. debug:container perform_, debug:config perform_base, and lint:container will catch ~90% of wiring problems. On the Laravel side, artisan about tells you nothing — dump the container directly.
• Cache. Clear the Symfony cache after any config change; a stale compiled container will mask your overrides and send you chasing ghosts.
• Autoload hygiene. Keep your classes out of the bundle's namespace (Perform\BaseBundle\...). If you extend into their namespace, a future patch release can collide with your files.
• Never patch vendor. Decoration, tagged services, or a proper fork under your own vendor prefix. With a package this thin on maintenance, a hacked vendor dir is a permanent tax.