Alipay Bundle Laravel Package

Getting Started

This release is a dependency bump: the package now builds against Symfony 3.x components instead of Symfony 2.x. That single line has more day-to-day impact than a typical feature release, because it changes which Laravel versions can install the package at all.

Start here:

1. Check your Laravel version against the Symfony constraint before anything else.

   composer why-not vendor/package 2.0
   composer show vendor/package --all | grep -i symfony
   

   Laravel 5.1/5.2 pin symfony/* at 2.7.*; Laravel 5.4+ ship Symfony 3.2 components. If you are on 5.1/5.2, 2.0 will not resolve and you should stay on 1.x. If you are on 5.4+, you should already be able to install it.

2. Install and confirm the resolved graph.

   composer require vendor/package:^2.0
   composer show vendor/package | grep -E 'symfony|php'
   

3. Re-publish config only if the package ships one. Compare rather than overwrite:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config
   git diff config/
   

4. Clear compiled artefacts. Symfony 3 removed a large number of deprecated classes and helpers, so stale cached service definitions can reference classes that no longer exist:

   php artisan config:clear && php artisan cache:clear && composer dump-autoload
   

5. First use case: exercise the package's primary entry point once through php artisan tinker (or a throwaway route) before wiring it into a feature. Resolve it out of the container — app(\Vendor\Package\Contract::class) — rather than new-ing it, so you fail fast on a container misconfiguration rather than deep inside your own code.

Where to look first in the repo: composer.json (the real compatibility contract), the service provider (what is bound and how), and the UPGRADE.md/CHANGELOG.md (what Symfony APIs the package itself touched).

Implementation Patterns

Resolve through the container, never construct directly. A Symfony 3 bump usually means the package's constructor signatures changed (helpers replaced by services, options arrays replaced by typed objects). Bind to the package's interface in your own provider and let the package's binding supply the concrete class:

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->bind(
        \App\Contracts\Thing::class,
        fn ($app) => $app->make(\Vendor\Package\PackageClass::class)
    );
}

This is the single highest-value pattern here: when 2.0.1 lands with another Symfony tweak, you change one line.

Wrap the package in a thin application service. Day-to-day code should call your ThingService, not the vendor class. That gives you a seam for the next major bump and keeps Symfony types out of your controllers and jobs.

Keep Symfony types out of your public method signatures. If the package hands you a Symfony 3 object, convert it to a plain value object or array at the boundary. Symfony 3 → 4 → 5 migrations repeatedly broke Symfony\Component\Console\Helper\* and similar; code that treats those as internal never notices.

Configuration over constructor arguments. Anything the package exposes via config/package.php should be set there, not passed as a constructor arg — config keys survive minor releases, constructor params do not.

Queue and console usage: if the package is used inside jobs or Artisan commands, resolve it inside handle() via app(), not in the constructor. Serialised jobs holding a resolved Symfony-backed object will fail to unserialise after an upgrade.

Testing pattern: mock the package's interface, not the vendor class. Symfony 3 classes are frequently final or have non-public constructors, and PHPUnit cannot mock them.

$this->mock(\App\Contracts\Thing::class, function ($mock) {
    $mock->shouldReceive('run')->once()->andReturn(true);
});

Upgrade workflow used by most teams:

1. Branch, bump the constraint, run the full test suite unchanged.
2. If it is green, the Symfony bump is transparent and you can ship.
3. If it is red, diff the failures against the package changelog — 90% of the time it is a removed helper class or a changed options array.
4. Re-run composer update --prefer-lowest on CI to catch a too-loose constraint.

Gotchas and Tips

The Laravel/Symfony version lock is the real breaking change. "Update to Symfony 3" is a hard incompatibility wall with Laravel 5.1/5.2 and anything else pinned to symfony/* 2.7. Composer will refuse to install rather than warn; composer why-not is the fastest diagnostic.

Symfony 3 dropped every class deprecated in 2.8. If the package used DialogHelper, TableHelper, ProgressHelper, LegacyFormHelper, or the old Symfony\Component\HttpFoundation\Session* shims, those are gone. Symptom: Class not found at runtime, not at install time — Composer does not type-check your code.

Symfony 3.0 is not an LTS. 2.8 and 3.4 are LTS; 3.0–3.3 are short-lived. If the constraint is a loose ^3.0, you may resolve onto an EOL minor with unfixed CVEs. Pin tighter or at least constrain to ^3.4.

PHP floor moved. Symfony 3 requires PHP ≥ 5.5.9, and 3.3+ requires 7.1. Check php -v on every environment, including CI and any queue workers you have not restarted.

Config cache staleness. After upgrading, bootstrap/cache/config.php can hold resolved class strings that no longer exist. php artisan config:clear (and config:cache again in production) is not optional.

Facade caching under long-running workers. With Octane or Swoole, a facade resolved in one request retains the old container binding. If you swapped the package binding in register(), restart the workers — php artisan octane:reload.

Symfony's Debug and ErrorHandler singletons (if the package touches them) register globals that are not request-safe. In tests, this shows up as error handlers accumulating across test cases; reset in tearDown() or skip the class entirely.

Debugging a resolution failure: php artisan tinker then app()->make(\Vendor\Package\PackageClass::class) gives you the real exception with the dependency chain, whereas a feature-level failure usually reports a misleading downstream error.

Extension points to prefer: the package's Contract/interface, its config array, and Laravel's container bind/extend. Avoid subclassing vendor classes — Symfony 3 removed many protected members that subclasses relied on, and minor bumps will break you silently.

Verdict: treat 2.0 as a compatibility release, not a feature release. The upgrade is safe and near-invisible on Laravel 5.4+, and impossible below it. Budget time for the config clear, a full test run, and an interface binding if you have not added one yet.