Js Routing Bundle Laravel Package

Getting Started

Start by treating v5.0.0 as a breaking upgrade, not a drop-in patch. First inspect the package’s composer.json for PHP and Symfony constraints, then locate the new bundle class and the restructured source directories. The bundle class is now the primary configuration entry point, so read it before touching config files.

Minimal steps:

1. Require the new version in a branch:

   composer require vendor/package:^5.0
   

2. Check for namespace/path changes caused by the directory restructure:

   composer dump-autoload
   

3. Find the bundle class and confirm how configuration is loaded:
   • Look for *Bundle.php.
   • Inspect its getContainerExtension() / config tree usage.
   • Compare against any Laravel service provider or bridge class if present.
4. Re-run the package’s config update tooling if cook is part of your workflow, then review the diff carefully:

   # only if your project uses cook
   cook update
   

5. Run the application test suite, especially tests that mock package classes.

First use case: wire the package through its bundle class, publish or update its config, then make one real call through the package in a feature test. Do not start by rewriting all mocks; first verify the container boots and config is resolved.

Implementation Patterns

Use the bundle class as the source of truth for configuration. In a Symfony-oriented integration, register the bundle and let its extension load config. In a Laravel integration, keep the Laravel service provider thin and bind package services explicitly rather than duplicating config logic.

Recommended patterns:

• Constructor injection everywhere. v5.0.0 uses PHP 8 constructor promotion, so prefer constructor injection over setter injection or container lookups. This also makes tests easier once mocks are updated.
• Bind interfaces in the app container. If the package exposes services through the bundle class, mirror those bindings in your Laravel provider where needed:

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

• Publish config once, then diff. If cook updated the package config, compare it with your published config before committing. Keep app-specific values in your app config, not in vendor files.
• Use feature tests for config resolution. A unit test can miss bundle-class wiring failures. Add one test that boots the app/container and resolves the main package service.
• Update mocks deliberately. Constructor-promoted dependencies change mock setup. Prefer real collaborators or container-resolved services in integration tests; mock only external boundaries.
• Keep package.json changes isolated. If cook modified package.json, treat it as a separate commit and confirm it did not overwrite app-specific scripts.

A practical workflow:

1. Upgrade in a branch.
2. Fix autoload and namespace references from the directory restructure.
3. Boot the app and resolve the main package service.
4. Update config for the bundle-class-based setup.
5. Replace brittle mocks with container-based or fake-based tests.
6. Run the full suite and a smoke test of the primary package workflow.

Gotchas and Tips

• This is a breaking release. Symfony 6/7 support, directory restructuring, bundle-class configuration, and constructor promotion can all break existing integrations. Do not assume Laravel-only usage is unaffected.
• Directory restructure means namespace drift. Search for old namespaces, service IDs, config paths, and view/template paths. composer dump-autoload alone will not find string-based service references.
• Bundle class configuration may bypass Laravel config expectations. If your app previously read package settings from config/package.php, confirm the bundle class does not expect a different tree or parameter shape.
• Constructor promotion breaks some test doubles. Mocking classes with promoted constructor dependencies can fail if tests instantiate them directly. Update tests to use the container, factories, or explicit constructor arguments.
• cook updates need review. Automatically updated config and package.json files can overwrite local customizations. Diff before committing.
• Clear caches aggressively. After changing bundle classes or config trees, clear framework/container caches. In Laravel:

  php artisan optimize:clear
  

• Check Symfony version constraints with Composer. Use composer why-not vendor/package 5.0 if installation fails, and verify your app’s Symfony components are on 6 or 7 as required.
• Debug config through the container. Dump the resolved bundle extension/config or use your framework’s container debug command. Do not debug by editing vendor files.
• Extension points: use the bundle class for package-level config, Laravel service provider bindings for app-level overrides, service decoration for behavior changes, and config publishing for environment-specific values.