Version Bundle Laravel Package

Getting Started

Start by confirming runtime compatibility before installing or upgrading:

• PHP >= 8.4 is now required.
• Symfony 7.4 and 8.x are supported.
• Laravel projects must be on a version that supports PHP 8.4 and the package’s Symfony constraints. Run composer why-not php 8.4 and inspect composer.json constraints if the install fails.

Minimal upgrade/install steps:

composer require <vendor>/<package>:^4.0
php artisan vendor:publish --tag=<package-config> # only if the package provides config
php artisan about

Look first at:

1. The package’s service provider registration and any published config.
2. The public interfaces and contracts for services and commands.
3. The upgrade guide/documentation for the final class change.
4. Your own codebase for extends usage against package service or command classes.

First use case: resolve services through Laravel’s container rather than instantiating or extending package classes directly.

use Vendor\Package\Contracts\SomeService;

public function __construct(private SomeService $service) {}

Because v4 marks service and command classes as final, the intended integration style is dependency injection and interface binding, not subclassing.

Implementation Patterns

Prefer composition over inheritance

The main v4 migration pattern is replacing inheritance with composition or decoration.

Before:

class CustomService extends PackageService
{
    public function handle(): void
    {
        parent::handle();
        // custom logic
    }
}

After:

final class CustomService implements SomeService
{
    public function __construct(
        private SomeService $inner,
    ) {}

    public function handle(): void
    {
        $this->inner->handle();
        // custom logic
    }
}

Bind the decorator in a service provider:

use Vendor\Package\Contracts\SomeService;
use Vendor\Package\SomeService as BaseService;
use App\Services\CustomService;

public function register(): void
{
    $this->app->bind(SomeService::class, BaseService::class);

    $this->app->extend(SomeService::class, function (SomeService $service, $app) {
        return new CustomService($service);
    });
}

Commands

If you previously extended a package command to change behavior, use one of these instead:

• Create your own Artisan command that calls the package service.
• Wrap the package command through a service/action class.
• Use events or hooks exposed by the package, if available.
• Register an alias or wrapper command rather than subclassing.

Avoid relying on protected methods or internal command properties; final classes make those extension points unavailable by design.

Laravel integration tips

• Bind package contracts to implementations in a dedicated service provider.
• Use constructor injection in controllers, jobs, listeners, and commands.
• For tests, bind fakes or test doubles to the package’s interfaces.
• If the package uses Symfony components directly, keep Symfony version constraints aligned with Laravel’s own dependencies.
• Prefer $this->app->extend() for decoration, but only when the resolved service is type-compatible with the contract.
• Keep custom behavior in application-level adapters so future package major versions are easier to absorb.

Upgrade workflow

1. Create a branch and update composer.json to ^4.0.
2. Run composer update <vendor>/<package> --with-dependencies.
3. Search for extends references to package services and commands.
4. Replace subclassing with decoration, interfaces, or wrapper commands.
5. Run the full test suite, especially tests that mock or partially mock package classes.
6. Check for PHP 8.4 deprecations and Symfony 8 deprecations in logs.

Gotchas and Tips

Final classes break inheritance and some mocks

The BC break is not just stylistic: any code that extends package service or command classes will fatal-error after upgrade. PHPUnit mocks of final classes also fail unless you mock an interface instead.

Use interfaces for test doubles:

$mock = Mockery::mock(SomeService::class);
$this->app->instance(SomeService::class, $mock);

If the package does not expose an interface for a service you need to replace, wrap it in your own application-level contract.

PHP 8.4 is a hard requirement

The package will not install on PHP 8.3 or earlier. This can block Laravel upgrades or CI pipelines. Check:

• Local CLI version: php -v
• Composer platform config: composer config platform.php
• CI matrix and deployment images
• Docker base images
• Laravel Forge/Envoyer/Vapor runtimes

Symfony 7.4/8 compatibility can conflict with Laravel constraints

Laravel itself may constrain Symfony components to a different major version. If Composer reports a conflict, do not force the package in with --ignore-platform-reqs unless you have verified the runtime. Instead:

composer why-not symfony/console 8.0
composer why-not <vendor>/<package> 4.0

Resolve the Laravel/Symfony/PHP version triangle first.

Extension points have moved

Because services and commands are final, the supported extension points are now likely:

• Interfaces/contracts
• Container bindings
• Decorators
• Events/listeners
• Package configuration
• Wrapper commands

Check the updated documentation for the recommended replacement before refactoring.

Debugging upgrade failures

Useful commands:

composer diagnose
composer outdated --direct
php artisan about
php artisan package:discover --ansi

If a command fails after upgrade, check whether your application registered a subclass of a now-final package command. The error will usually mention “cannot extend final class.”

Configuration quirks

If the package publishes config, republish or diff it after upgrading. Major versions often add or rename keys. Prefer environment variables and config caching checks:

php artisan config:clear
php artisan config:cache

Testing checklist

• No extends against package service/command classes.
• No PHPUnit mocks of final package classes.
• Container bindings resolve interfaces correctly.
• Artisan command signatures and output remain stable.
• Full suite passes on PHP 8.4.
• Production image and CI use PHP 8.4.