Zmkr Cloudflare Turnstile Bundle Laravel Package

Getting Started

v2.0 is a platform-level release: the only breaking changes are minimum-version bumps (PHP ≥ 8.2, Symfony components ≥ 5.4). There are no reported API breaks, so the upgrade is mostly a dependency-resolution exercise rather than a code rewrite.

Before you composer update:

1. Check your runtime and CI images: php -v must report 8.2 or newer. If you use Dockerized or shared-hosting PHP, bump the image/FPM pool first — Composer will fail with an opaque solver error otherwise.
2. Check what is holding Symfony components back:

   composer why-not symfony/console "^5.4|^6.0|^7.0|^8.0"
   composer show | grep symfony/
   

   A single package pinned to an old symfony/* line will block the whole upgrade even if your own composer.json looks fine.
3. Bump the constraint to ^2.0 and update with --with-dependencies so Symfony components move together:

   composer require "vendor/package:^2.0" --with-dependencies
   

Where to look first: the service provider (what it binds, merges, and publishes), then the published config file, then the README's usage example. The service provider tells you more about integration surface than the docs do.

First use case: publish the config, resolve the package's main entry point from the container in php artisan tinker, and confirm it comes back correctly wired before touching application code:

php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" --tag=config
php artisan tinker
>>> app(Vendor\Package\MainService::class);

If that resolves, the upgrade is effectively done — the rest is verifying behaviour in your own tests.

Implementation Patterns

Resolve from the container, never instantiate directly. Bindings configured in the service provider (drivers, HTTP clients, config objects) are lost the moment you new the class yourself. Inject the interface into constructors, or use the facade if the package exposes one.

Drive configuration through env, then cache. Keep environment-specific values in .env, reference them from the published config, and always re-run php artisan config:cache as part of deploy. In tests, use config()->set() inside the test rather than editing the config file.

Swap implementations for tests. Bind a fake or stub of the package's interface in a test service provider, or use the container's instance() binding. This is the cleanest seam the package gives you and keeps feature tests free of network calls.

Run a version matrix in CI. Given v2.0 explicitly supports Symfony 5.4 through 8, a matrix that pins symfony/* to each supported major on at least one job will catch the integration drift that a single-version pipeline hides. Keep the Laravel version axis too if the package spans multiple Laravel majors.

Gate formatting in CI. v2.0 added PHP CS Fixer. If you contribute patches or maintain a fork, run the fixer in dry-run mode as a CI step so your PR matches the project's style without a round-trip:

vendor/bin/php-cs-fixer fix --dry-run --diff

Use the documented testing helpers. The Composer helper scripts added in v2.0 are the intended entry point for running the package's own suite. Read the contribution guidelines before running ad-hoc PHPUnit commands — they document the supported invocation and the expected Symfony version setup.

Gotchas and Tips

The breaking changes are environmental, not syntactic. Nothing in your application code should need to change for v2.0. If a test fails after upgrading, suspect the dependency graph (a transitive Symfony package resolving differently) before you suspect the package's API.

PHP 8.2 is a hard floor. Watch for composer.json config.platform.php entries that lie about your runtime — they'll let the install succeed and then fail at runtime with a version-constant or syntax error. Grep for platform in composer.json and any composer.lock-generating CI config.

Symfony 5.4 floor ripples through Laravel. Older Laravel releases pin older symfony/* components. If composer why-not points at the framework rather than at the package, you need a Laravel upgrade first — this is the most common reason a v2.0 upgrade stalls, and it isn't the package's fault.

The PHPStan autoloading fix matters if you develop against the package. The v2.0 release notes call out a fix for PHPStan losing autoloading when switching Symfony versions mid-development. If you maintain a fork or a downstream package, clear vendor/composer/autoload_*.php and any PHPStan result cache after changing Symfony constraints, then regenerate the baseline — stale baselines otherwise report phantom errors.

No automated config migration. After upgrading, diff the package's shipped config against your published copy. New keys added since 1.x will silently fall back to defaults, which is fine until a default is not what you want in production. Re-publish to a temp path and diff rather than overwriting.

Debugging resolution failures. composer why-not identifies the blocker by package name; composer update --dry-run -v shows the solver's reasoning. When the message is a PHP version conflict rather than a package conflict, it's almost always a stale platform config or a CI image that hasn't been rebuilt.

Extension points are unchanged. Custom drivers, decorators, and container overrides written against 1.x remain valid — the release contains no deprecations and no removed extension hooks. That makes this a good window to upgrade: the surface you'd have to re-verify is small, and staying on 1.x will eventually strand you on unsupported Symfony versions.

Watch for the next major. Symfony 8 support arriving means the package is tracking Symfony's release cadence closely. Expect future majors to raise the floor again; pinning to ^2.0 rather than a wider constraint keeps those jumps deliberate instead of accidental.