Shared Bundle Laravel Package

Getting Started

Reset expectations first. ranky/shared-bundle is a Symfony bundle, not a Laravel package. There is no Illuminate\Support\ServiceProvider, no extra.laravel.providers in composer.json, and php artisan package:discover will not wire it up. Treat it as a plain Composer library that happens to ship Symfony DI metadata; you get classes, and you opt into container wiring yourself. That reframing is the difference between a 15-minute integration and a day of confusion.

Minimal steps.

1. composer require ranky/shared-bundle:^2.1 — pin the minor, not ^2.0, until you have read a real diff.
2. composer show ranky/shared-bundle — read the declared php and illuminate/* / symfony/* constraints. If it requires symfony/framework-bundle or doctrine/*, decide now whether you accept those transitive packages in a Laravel app.
3. ls vendor/ranky/shared-bundle/src and cat vendor/ranky/shared-bundle/composer.json — find the PSR-4 root and the autoload.files/classmap entries, if any.
4. php artisan tinker and instantiate one class. If it constructs without arguments, it's a utility library and you are done.

Where to look first, in order.

• composer.json — constraints and autoload (the only authoritative facts you have).
• src/Resources/config/services.yaml (or .xml) — this is the inventory of what the bundle intends to provide.
• src/DependencyInjection/*Extension.php — how parameters are resolved and what defaults exist.
• src/*Bundle.php — usually trivial, but confirms it's a Symfony bundle and shows any compiler passes.
• CHANGELOG.md — likely absent or empty given the v2.1.2 release notes are just a compare link; note that and move on.

First use case. Consume a value object, DTO, or helper directly — new Ranky\Shared\...\Foo() inside a job or action — with zero container involvement. Only escalate to a service provider if the classes you need have constructor dependencies that the Symfony container was supplying. Most "shared bundles" are 80% plain PHP and 20% DI glue; find out which 20% you actually need before writing wiring code.

Implementation Patterns

Pattern 1 — plain library (default). Import classes, use them, inject into your own classes via Laravel's container or constructor. No provider, no config file. This is the correct choice for DTOs, enums, small utilities, and anything with a no-arg or trivially-satisfiable constructor. It also keeps the dependency at arm's length: swapping the package out later is a use statement change.

Pattern 2 — adapter service provider. If the bundle's services need a Symfony container, write one small provider in your app that binds them explicitly:

class SharedBundleServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(FooClient::class, fn ($app) => new FooClient(
            baseUrl: config('shared-bundle.base_url'),
            http: $app->make(HttpClient::class),
        ));
    }
}

Keep this provider in app/Providers/Vendor/ and keep it boring. It is the one file you will touch on every bump, so it should contain no business logic.

Pattern 3 — anti-corruption layer (recommended). Do not reference ranky\shared\* outside one namespace in your codebase. Define a App\Support\Shared\* interface, implement it with a thin wrapper around the package, and bind the interface. This costs an hour and buys you: a single place to fix a patch regression, a single place to swap the package, and a seam to fake in tests. Given a 3-star, single-maintainer dependency with an empty changelog, this is not over-engineering — it's the minimum viable insurance.

Pattern 4 — config bridge. Symfony bundles use extension load() with %parameter% and %env(VAR)% placeholders; Laravel has neither. Copy the bundle's YAML defaults into a real config/shared-bundle.php in your app, read env() there once, and pass plain scalars into constructors. Resist the urge to write a YAML loader to keep the Symfony config "in sync" — you will spend more time on the loader than on the config.

Pattern 5 — bump discipline. One PR per consuming app containing only the composer.lock change plus the output of composer why ranky/shared-bundle. Never batch it with feature work. Since the upstream changelog is a compare URL, your PR description is the changelog: paste git log v2.1.1..v2.1.2 --oneline from a clone of the repo, or explicitly state you could not obtain it. That record is the only thing that will make the next patch release debuggable.

Pattern 6 — contract tests. Write three or four Pest/PHPUnit tests against your wrapper asserting the behavior you depend on (not the package's full surface). These are the tests that will catch a silent patch regression, because upstream almost certainly won't.

Pattern 7 — fan-out order. Roll to your lowest-traffic app first, hold a few days, then proceed in dependency order. If multiple apps consume it, keep a version matrix (app × package version) reviewed monthly; unbounded skew is how "we all use the shared bundle" quietly becomes "we all behave differently."

Gotchas and Tips

Auto-discovery is a no-op. There is no Laravel provider to discover. If you add a provider manually to bootstrap/providers.php, confirm it's actually registered with php artisan about --only=providers rather than assuming.

Symfony container features do not exist here. Compiler passes, tagged services, !tagged_iterator, autowiring by type against a Symfony container, kernel.event_subscriber — none of it runs. If the bundle's services.yaml is dense, you are manually reimplementing a slice of Symfony DI. Price that before committing.

%env()% and %parameter% will not resolve. They surface as literal strings, often failing deep in a constructor with a confusing "invalid URL" or "missing connection" error rather than at boot. If you see a placeholder string in a stack trace, this is why.

Doctrine is the likely hidden cost. Shared Symfony bundles frequently depend on doctrine/orm for entity mappings or migrations. Check composer show --tree ranky/shared-bundle before installing. If it ships migrations, their timestamps will interleave with your app's and can reorder deploys — inspect Resources/migrations (or equivalent) and decide whether to disable auto-loading of them.

Namespace and class collisions. A generic shared namespace is exactly the kind that collides with app classes or with a second vendor package. After install, run composer dump-autoload -o and watch for "ambiguous class resolution" warnings; they are easy to miss in CI.

Empty changelog is a signal, not a nuisance. v2.1.2's notes are a compare link with no enumerated commits. Treat every bump as "pin-and-audit": require the diff, even for patches. A patch that widens a sub-dependency constraint can pull a new major into all consumers simultaneously.

Debugging checklist when something breaks after a bump.

1. composer why ranky/shared-bundle and composer show --tree — did a transitive version move?
2. git diff vendor/ranky/shared-bundle (commit vendor/, or diff the two tagged tarballs) — what actually changed?
3. composer dump-autoload -o — classmap staleness masquerades as logic bugs.
4. Instantiate the class in tinker with the exact arguments your provider passes — isolates wiring from package behavior.

Extension points, ranked by preference. (1) Wrap, don't extend. (2) If you must patch, maintain a documented fork right — with a single maintainer and no security advisories, waiting upstream may not be an option. (3) Do not subclass internals; with no published API/internal boundary, "internal" is indistinguishable from "public" and will move under you.

Scope the contents before trusting it. If the bundle's classes touch auth, payments, or PII, a single-maintainer dependency with no SLA is the wrong trade. If it's domain constants and DTOs, it's benign. The package's size and content — not its version number — determine your actual risk.