Sitemap Bundle Laravel Package

Getting Started

Version 0.2 is primarily a compatibility release: the package now builds against Symfony 5 components. That changes the install baseline more than the public API, so start there.

1. Check your Laravel/Symfony baseline before requiring it. Symfony 5 requires PHP >= 7.2.5. Laravel 6 can run Symfony 5 components; Laravel 7+ requires them. Laravel 5.8 and below pin older Symfony 4.x components and will usually fail resolution.
2. Install and inspect the constraint graph:

   composer require vendor/package:^0.2
   composer show vendor/package
   composer why symfony/console
   

   Confirm the package pulls symfony/*:^5.0 and that your app does not pin ^4.x anywhere.
3. Look first at the package’s composer.json, service provider, and config file. The provider is the map of what is bindable; the config file is the map of what is tunable. Publish it:

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

4. First use case: resolve the package’s primary service from the container and exercise one read/write path in php artisan tinker:

   app(Vendor\Package\Contracts\Client::class)->ping();
   

   If that works, run the package’s own tests or artisan command before wiring it into application code.

Because this release is a Symfony 5 migration, treat the upgrade as a dependency-graph change first and a feature change second.

Implementation Patterns

Constructor injection over facades. Bind the package contract in a service provider and inject it into controllers, jobs, and commands. This keeps you insulated if 0.3 changes concrete classes.

$this->app->bind(
    Vendor\Package\Contracts\Client::class,
    Vendor\Package\Client::class
);

Use Symfony contracts at boundaries. With Symfony 5 support, type-hinting contracts such as Psr\EventDispatcher\EventDispatcherInterface or Symfony\Contracts\Translation\TranslatorInterface is safer than type-hinting Laravel/Symfony concretes. Laravel’s dispatcher and translator satisfy the newer contracts.

Queue and command integration. If the package dispatches events or shells out, exercise those paths in a queued job and an artisan command. Symfony 5’s Process component expects an array of arguments:

$process = new Process(['php', 'artisan', 'package:sync']);

Testing pattern. Use Laravel’s fakes around the package boundary, and use the package’s own helpers if provided:

Event::fake([Vendor\Package\Events\Synced::class]);

$this->artisan('package:sync')->assertExitCode(0);

Event::assertDispatched(Vendor\Package\Events\Synced::class);

Run the suite with symfony/phpunit-bridge enabled so Symfony 5 deprecations surface as warnings rather than silent drift.

Configuration and caching. Keep package options in config/package.php, reference them through config(), and always run php artisan config:cache as part of deployment. On upgrade, clear stale caches:

php artisan config:clear && php artisan cache:clear

Upgrade workflow. On an existing app: bump the constraint, run composer update vendor/package --with-dependencies, run the full test suite, then grep for any package classes that extend Symfony base classes. Those are the most likely breakpoints.

Gotchas and Tips

• PHP minimum is now real. Symfony 5 requires PHP 7.2.5. If CI still runs 7.2.0 or 7.1, the failure appears at install time, not test time.
• Laravel 5.x is effectively excluded. Laravel 5.8 and earlier pin Symfony 4.x components. Composer will report a conflict rather than install a broken package. Use composer why-not vendor/package 0.2 to see the exact blocker.
• Symfony 5 removals can break subclasses. Watch for code extending or importing:
  • Symfony\Component\EventDispatcher\Event → use Symfony\Contracts\EventDispatcher\Event
  • Symfony\Component\HttpKernel\Event\FilterResponseEvent and related Filter*Event classes → use RequestEvent, ResponseEvent, etc.
  • Symfony\Component\Debug\* → Symfony\Component\ErrorHandler\*
  • Symfony\Component\Translation\TranslatorInterface → Symfony\Contracts\Translation\TranslatorInterface
• Command::execute() must return an integer. If the package or your subclass returns null, Symfony 5 will complain. Return Command::SUCCESS or Command::FAILURE.
• Process no longer accepts a string command. Any package code or app code passing 'ls -la' must become ['ls', '-la'].
• Config cache hides stale config keys. After upgrading, a cached config file can mask new or renamed package keys. Always clear before debugging “missing option” errors.
• Deprecation noise is useful. Set SYMFONY_DEPRECATIONS_HELPER=weak locally to keep the suite green while still seeing the list; tighten it in CI once clean.
• Extension points to prefer: bind custom implementations against the package’s contracts, publish and override config, and use container tags rather than editing vendor code. If the package exposes a manager/driver pattern, register a custom driver through the provider rather than subclassing internals.
• Debugging checklist: composer show symfony/*, php artisan about, composer why-not, then a targeted php artisan tinker call against the package service. Most 0.2 failures will be dependency resolution or a removed Symfony 5 class, not package logic.