Laravel Qcloud Captcha Laravel Package

Getting Started

This release (4.0.0) is a compatibility major, not a feature major. There is no new public API surface to learn — the entire delta is a raised platform floor:

• PHP ^8.3
• Laravel ^13.9
• Orchestra Testbench ^11.0 and PHPUnit ^12.5.8 (dev only)

Start by confirming you can even install it. Before touching application code, validate the constraint resolution in the host project:

composer require your-vendor/your-package:^4.0 --dry-run

If that resolves, your first real use case is simply the one you already had — the package's runtime behaviour is unchanged from 3.x. The meaningful "first use case" for this release is verifying your own test suite still runs against the new dev stack, because PHPUnit 12.5 and Testbench 11 change more for package consumers who extend the package's test harness than the runtime code does.

Where to look first:

1. composer.json in your app — check laravel/framework and php constraints.
2. composer.lock — confirm no other dependency pins Laravel below 13.9.
3. Your package's phpunit.xml — if you extend or copy its schema, it needs migrating.
4. CI config — align your matrix with 8.3, 8.4, 8.5.

Implementation Patterns

Constraint alignment in the host app. Because the floor is Laravel ^13.9, treat 13.9 as the real minimum, not 13.0. Teams commonly pin laravel/framework loosely (^13.0) and then discover Composer picks an older 13.x in a lockfile that was generated before this release. Bump the lockfile deliberately:

composer update "laravel/framework" --with-dependencies
composer require your-vendor/your-package:^4.0

Staged upgrade across a monorepo. If several first-party packages depend on this one, upgrade them in dependency order and run composer update --dry-run --no-interaction at each step — the same gate the maintainers used for validation. It surfaces constraint conflicts without mutating locks.

CI matrix. Mirror the maintainers' matrix rather than pinning a single version. PHP 8.3 is the floor and 8.5 is the newest supported runtime; testing only one of them hides deprecation notices that appear in 8.4/8.5:

strategy:
  matrix:
    php: ['8.3', '8.4', '8.5']

Test harness integration. If you write integration tests against the package, base them on Testbench 11. The Orchestra\Testbench\TestCase contract is the extension point — override getPackageProviders() and getEnvironmentSetUp() as before, but confirm your require-dev block matches orchestra/testbench: ^11.0 alongside phpunit/phpunit: ^12.5.8. Mismatched pairs are the most common source of "works locally, fails in CI" on this upgrade.

Gate your own releases the same way. The maintainers' validation sequence is a good template for any Laravel package release:

composer validate --strict
composer update --dry-run --no-interaction
composer check-style
composer test

Treat 4.x as a hard fork in your dependency graph. If you maintain a downstream package that supports both Laravel 12 and 13, you now need conditional constraints:

"require": {
    "your-vendor/your-package": "^3.0 || ^4.0"
}

…and CI jobs that actually exercise both branches, since ^3.0 will pull Laravel 12 and ^4.0 will refuse it.

Gotchas and Tips

^13.9 is a minor floor, not just a major. ^13.9 excludes 13.0–13.8. Composer will report a conflict that reads like a Laravel incompatibility but is really a minor-version pin. Read the constraint literally before debugging anything else.

Transitive Laravel pins. A dev dependency (nunomaduro/larastan, a Testbench-era helper, a debugging toolbar) can hold laravel/framework below 13.9 and block the whole upgrade. composer why-not laravel/framework 13.9 is the fastest diagnostic.

PHPUnit 12.5 drops doc-comment metadata. This bites anyone whose tests were copied from the package's older examples:

• @test → use the test_ prefix or the #[Test] attribute.
• @dataProvider → #[DataProvider('methodName')], and providers must be static.
• @depends, @group, @covers annotations are gone — use #[Depends], #[Group], #[CoversClass].

PHPUnit XML schema migration. The 12.5 schema replaces the old coverage block with <source> containing <include>/<exclude>, and moves cache settings under cacheDirectory. An un-migrated phpunit.xml typically produces a schema-validation warning rather than a hard failure, so it slips through CI until a future major makes it fatal. Migrate it now.

Testbench 11 no longer supports Laravel 12. A CI job that installs Testbench 11 against a Laravel 12 matrix entry will fail on resolution, not on assertions. Keep the matrix entries paired: Laravel 13 ↔ Testbench 11 ↔ PHPUnit 12.

PHP 8.4/8.5 deprecations surface as noise before they surface as failures. Run the upper bound of the matrix with E_ALL and fail on deprecations (<phpunit failOnDeprecation="true">) so implicit-nullable and similar notices are caught while they're still cheap.

Downgrading is the escape hatch. If the upgrade blocks a release, pin ^3.0 explicitly rather than * or dev-main. Pinning prevents a future composer update from silently jumping the major.

No runtime migration path is provided because none is needed. There are no renamed config keys, no removed service providers, no deprecations in the public API described in this release. If your 3.x integration works and you satisfy the platform floors, 4.0 is a version-constraint change only. Budget upgrade effort against your test suite and CI, not against application code.

Extension points are unchanged. Service provider registration, config publishing, and facade bindings carry over verbatim. The one place to re-verify is anything you subclass from the package's test utilities — that's where the Testbench 11 / PHPUnit 12.5 jump has real surface area.