Kirby Db Laravel Package

Getting Started

The 4.0.1 release is functionally a maintenance release, but it carries two changes that affect your environment before you write a single line of code: the minimum PHP version is now 8.2 (8.1 support dropped), and the package now declares support for Kirby 5.x alongside its existing targets. Treat the upgrade as a minor migration rather than a drop-in patch.

1. Check your runtime first. Run php -v and confirm >= 8.2 locally (Herd/Valet/Sail images included), then composer why-not <vendor>/<package> 4.0.1 to see what is pinning you to 4.0.0. If your composer.json has "php": "^8.1" or your Docker base image is php:8.1-fpm, bump both — otherwise composer update will silently keep you on 4.0.0.
2. Read the constraint, not the changelog. Inspect the package's own composer.json (require, require-dev, suggest) to see exactly which Kirby versions are allowed and whether the Kirby dependency is ^4.0 || ^5.0 or ^5.0 only. That single line tells you whether 4.0.1 is safe for an existing Kirby 4 site.
3. Look at the tests/ directory first. The switch from PHPUnit to Pest means the test suite is now the most readable documentation of the public API — Pest's it('...') descriptions and expect() chains read as prose. Start there for the first use case rather than the README.
4. First use case: install into a single Kirby 5 site, register the plugin, and confirm it boots before touching anything else. Only after that works should you port a second, larger site.

If you are maintaining a Laravel application that talks to a Kirby-powered site, this package is still a Kirby-side dependency — the Laravel work is limited to the HTTP/API boundary and your CI pipeline.

Implementation Patterns

• Pin deliberately, then relax. Go to "vendor/package": "4.0.1" (exact) while you validate, then move to "^4.0" once green. Because the PHP 8.1 drop landed in a patch release, floating constraints (^4.0 is fine; * is not) will surprise you later.
• Update the CI matrix in the same PR as the dependency bump. The package's own GitHub Actions were reworked in this release, and your pipeline needs the mirror treatment: drop 8.1 from shivammathur/setup-php matrices, set php-version: ['8.2', '8.3', '8.4'], and re-run the matrix against PHP 8.2 minimum. A green build on 8.1-only is now meaningless.
• Containerise the PHP version. FROM php:8.2-cli (or 8.3) in your dev/staging Dockerfile, and update docker-compose.yml, Sail config, Forge/Envoyer recipes, and any Lambda/Vapor runtime in lockstep. This is the most common source of "works locally, fails on deploy" in this kind of upgrade.
• Adopt the Pest conventions if you extend the package. If you fork, patch, or maintain your own tests against this package, follow the project's move: pestphp/pest in require-dev, remove phpunit/phpunit from direct requirements, keep phpunit.xml only if you still need it for coverage config, and use it()/expect() in place of test* methods.
• Keep Kirby 4 and Kirby 5 sites on separate branches. If the constraint permits both, run one branch per major to avoid an accidental dependency resolution pulling 5.x into a Kirby 4 project. If 4.0.1 requires Kirby 5, that becomes your migration trigger rather than a bug.
• Bridge to Laravel at the boundary. For Laravel apps consuming the same content, wrap the Kirby site's exposed endpoints behind a small Http client with retry() and a cached response layer — do not try to share the plugin's internals across runtimes.

Gotchas and Tips

• Semver smell: PHP 8.1 dropped in a patch. Anything in 4.0.x should be non-breaking by convention. Audit whether your lockfile is holding you back, and audit whether any of your consumers declare php: ^8.1 — Composer's platform check will fail at install time with a your requirements could not be resolved error, not a friendly warning.
• Confirm Kirby 5.x support means "also", not "instead". The changelog sentence is ambiguous. Verify via composer show --tree or the package's require block. If it's Kirby 5-only, existing Kirby 4 sites are stuck on 4.0.0 and you now maintain two versions — plan that explicitly.
• Pest migration changes your debugging story. phpunit --filter still works, but stack traces, --parallel behaviour, and the dataset API differ. If you have custom TestCase bootstrapping or PHPUnit extensions, they may need rewriting as Pest uses() / beforeEach() blocks.
• The GitHub Actions rework can break self-hosted or pinned runners. If you consume the workflow templates (or vendor them), re-check actions/checkout, setup-php cache keys, and any matrix.php-versions you copied — stale matrices are the number-one cause of red builds after a release like this.
• Extension points to test explicitly after upgrading: plugin registration/boot hooks, config file publishing, and any event or tag-based listeners. These are the places where a Kirby major-version bump (4 → 5) usually bites, and they won't be covered by a simple smoke test.
• Debug in this order: composer why-not → PHP binary actually in use (php -v inside the container, not on the host) → Kirby version resolved → plugin boot → test suite. Skipping step 2 wastes hours chasing a mismatch that has nothing to do with the code.