Region Bundle Laravel Package

Getting Started

1. Pull the new version and re-resolve dependencies.

   composer require <vendor>/<package>:^1.2 --with-all-dependencies
   

   v1.2.2 changes the dependency graph (it now pulls in doctrine/doctrine-bundle), so a plain composer update <vendor>/<package> may leave you with a stale lock entry or a partial install. Always use -W on this bump.

2. Confirm what actually landed.

   composer show <vendor>/<package>
   composer why doctrine/doctrine-bundle
   composer why doctrine/dbal
   

   You want exactly one owner for doctrine/doctrine-bundle. If two packages claim it, you have a version-constraint tug-of-war waiting to happen.

3. Check whether the package's service provider is auto-discovered.

   php artisan about
   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Look in bootstrap/providers.php (Laravel 11+) or config/app.php. If the package registers Doctrine wiring, it should appear here before you write any code against it.

4. First use case. Run the package's own smoke path before integrating: publish its config, run php artisan migrate --pretend (or the package's equivalent), and hit one read + one write through the API it exposes. Doing this in isolation tells you whether the new Doctrine dependency resolves cleanly on your PHP/Laravel version, separately from any of your own code.

5. Where to look first when something's off: config/<package>.php, the package's composer.json (require + extra.laravel), and storage/logs/laravel.log filtered on the package namespace.

Implementation Patterns

Wrap the package behind a thin application-level interface. Given v1.2.2 is purely a dependency change, the public surface is assumed stable — but the transitive surface is not. Bind the package's client/manager into the container and depend on your own contract everywhere else:

// app/Providers/AppServiceProvider.php
$this->app->singleton(ReportRepository::class, fn ($app) =>
    new PackageReportRepository($app->make(Vendor\Package\Client::class))
);

This is the cheapest insurance you can buy against the next dependency bump.

Resolve inside jobs, not constructors. Doctrine-backed connections are stateful (EntityManager, transaction nesting, connection reuse). Don't hold them as constructor properties on queued jobs or long-lived singletons — resolve per handle() so a recycled worker doesn't inherit a closed connection.

public function handle(ReportRepository $reports): void
{
    $reports->rebuild($this->id);
}

Keep transactions at the boundary you own. If the package manages its own unit of work, do not nest DB::transaction() around its calls and assume atomicity. Pick one owner per operation and document it.

Isolate the config surface. Publish once, commit config/<package>.php, and drive environment differences through env() in that file only. Never read env() from application code that touches the package — it breaks under config:cache.

Test against a real dependency resolution. In CI, add a job that runs composer update --prefer-lowest against this package. Dependency-only releases like 1.2.2 are exactly the kind that pass composer install locally (lock file untouched) and fail on a fresh resolve.

Gate the rollout. Feature-flag anything that goes through the new dependency path so you can disable it without a redeploy if Doctrine wiring misbehaves in production.

Gotchas and Tips

• doctrine/doctrine-bundle is a Symfony bundle. In a Laravel app it contributes no service provider and no auto-discovery. Treat it as an inert transitive library: it will sit in vendor/, expand your audit surface, and do nothing for you directly. Don't try to "enable" it.

• This is the most likely source of breakage. The dependency brings its own constraints on doctrine/dbal, doctrine/orm, symfony/*, and psr/*. If your app already uses doctrine/dbal directly, a dbal minor-version shift can change behaviour in Schema and QueryBuilder. Diff composer.lock after the bump — not just the package entry, but the whole doctrine/* and symfony/* block.

• Watch for a Laravel/Symfony container clash. Some Symfony components register container-compiler passes via composer.json extra. Laravel ignores them, which is fine — but if you also run a Symfony app in the same monorepo, ensure the two lock files are independent.

• composer why-not is your friend. When resolution fails after this bump:

  composer why-not doctrine/doctrine-bundle ^2.0
  composer diagnose
  

  The error text usually names the package that pinned dbal — that's your real culprit, not the release itself.

• Pin the transitive version, not just the package. In composer.json:

  "conflict": { "doctrine/dbal": "<3.6" }
  

  Cheap, explicit, and it fails at resolve time rather than in production.

• config:cache and route:cache after every dependency bump. Stale caches mask config changes and produce confusing "my setting isn't applied" symptoms that look like package bugs.

• Debugging order when something regresses post-upgrade: (1) composer show doctrine/dbal — did the version move? (2) php artisan config:clear && php artisan optimize:clear. (3) Re-run against the previous lock (composer install from a stashed lock) to confirm the release is the cause. (4) Only then read the package source.

• Extension point to prefer: if the package exposes a manager/builder you can extend or a container binding you can rebind, use that rather than subclassing. Subclassing couples you to internals that a dependency bump can silently change.

• Upgrade hygiene. Because v1.2.2 is dependency-only, it's a low-risk patch — but it isn't a no-op. Bump it in its own commit with the lock diff attached, so a git bisect later has one clean candidate instead of a bundled mystery.