Statamic Cookie Consent Laravel Package

Getting Started

This assessment covers v1.0-beta.4, whose only documented change is PHP 8 support. Treat everything below as compatibility and upgrade guidance rather than a feature tour — verify the package's actual API surface against its README before building on it.

First three steps:

1. Read the PHP constraint, not the release note. "Support PHP 8" is ambiguous. Open the package's composer.json and check whether the constraint is ^8.0, >=8.0, or ^8.2. The difference determines whether you can run it on a supported PHP minor (8.0 went EOL in Nov 2023; 8.1 in Dec 2025) or whether it merely stopped crashing on 8.0.
2. Resolve it in a scratch app before touching your real one. In a throwaway Laravel skeleton on your target PHP version:

   composer require vendor/package:1.0.0-beta.4 --with-all-dependencies
   composer why-not php 8.3   # surfaces conflicting constraints
   

   If why-not returns nothing, the constraint is satisfied and you're clear to proceed.
3. Register and exercise the service provider. Most Laravel packages ship one. Run php artisan about and check the provider appears in the loaded list, then php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" to see whether there are config or migration assets you're expected to publish.

First real use case: install into a fresh Laravel app at your production PHP version, run php artisan test on your own suite with the package installed but unused. That isolates "does it break my app by existing" from "does it break my app when I call it" — two very different failure modes, and the first is much cheaper to diagnose.

Implementation Patterns

Pin the beta, hard. Pre-1.0 releases carry no backwards-compatibility promise, and ^1.0@beta will happily pull beta.5 with a renamed method. Use an exact constraint and commit the lockfile:

"vendor/package": "1.0.0-beta.4"

Loosen to ^1.0 only after a stable tag lands.

Wrap it behind your own boundary. Given the API can shift between betas, avoid calling the package directly from controllers and jobs. Put a thin adapter or dedicated service class in front of it so a rename in beta.5 costs you one file, not forty. This is cheap insurance and you can delete the adapter once the package stabilises.

Run a PHP matrix in CI. Since PHP 8 support is the headline change, prove it across the minors you actually deploy to:

strategy:
  matrix:
    php: ['8.1', '8.2', '8.3', '8.4']

A green run on 8.4 plus a green run on your oldest supported minor is what "supports PHP 8" needs to mean in practice.

Surface deprecations in tests. PHP 8.x emits deprecations rather than fatals, so they hide in logs. Convert them to failures in your test suite so package-internal deprecations surface during CI rather than in production logs:

// phpunit.xml
<ini name="error_reporting" value="-1"/>

and register an error handler in tests/TestCase.php that throws on E_DEPRECATED. This is the single highest-value thing you can do when adopting a package that just widened its PHP support.

Integrate through the container, not the facade, if both exist. Binding to an interface in your own service provider means you can swap the implementation in tests and insulate yourself from facade signature changes.

Gotchas and Tips

• "Supports PHP 8" often means "supports 8.0". Packages that added the constraint early frequently still test only against 8.0 and break on 8.4's deprecations. Check the CI config in the repo, not just the release note.
• Named arguments are a silent breaking change. PHP 8 lets callers write $package->method(foo: $x). If a later beta renames that parameter, your code breaks with no deprecation. Avoid named arguments when calling vendor code — this is the PHP 8-specific trap most people miss.
• Betas get yanked. If beta.4 is retracted, composer install from a lockfile referencing it fails. Keep the tarball or a fork pinned if this package is load-bearing.
• Widened type signatures can be a BC break in the other direction. A method that returned string and now returns string|false under PHP 8 union types will pass runtime tests and fail static analysis. Run PHPStan or Larastan at level 6+ against your integration code — this catches exactly the class of change a PHP-version bump introduces.
• Debugging order of operations: composer diagnose → composer why-not php x.y → php artisan config:clear (stale cached config is the most common "package won't load" cause) → php artisan about to confirm provider registration. Only then start reading package source.
• Extension points to look for first: container bindings in the service provider, a publishable config file (check config/ in the package), and any facade with a shouldReceive-friendly interface. A package with all three is easy to test around; one with none is worth wrapping more defensively.
• Config quirks: if the package publishes config, vendor:publish will not overwrite an existing file. After upgrading the package, diff the package's shipped config against yours — new keys added in a release are the usual cause of "it worked before the update."
• Version cadence is a signal. v1.0-beta.4 with a one-line changelog suggests either a small maintainer team or a package in maintenance mode. Check the commit history dates before adopting it for anything long-lived; if the last commit predates PHP 8.1, the "PHP 8 support" claim is untested against modern minors.