Init Cms Bundle Laravel Package

Getting Started

Confirm the toolchain floor before you touch anything. This release drops PHP < 8.2, so the first failure most teams hit is not a package error but a Composer platform conflict.

php -v
composer check-platform-reqs
composer why-not php 8.2   # if 8.1 is still pinned anywhere

Update config.platform.php in composer.json and the CI matrix (8.2, 8.3) in the same PR as the bump — not afterwards.

Pin the release exactly while you evaluate. "vendor/package": "6.4.14", not ^6.4. The version number says patch; the release notes say "many upgrades and BC breaks". Trust the notes (see Gotchas).

Where to look first, in this order:

1. The upgrade guide / CHANGELOG for the whole 6.x line — with this many BC breaks, semver will not protect you and the guide is the only source of truth.
2. The attribute reference in the docs. This is the biggest day-to-day change: docblock annotations are no longer read, so any page/component metadata still declared the old way is silently inert rather than loudly broken.
3. The redesigned UI's published views and assets — expect renamed slots, restructured markup and new CSS hooks, plus a required re-publish of assets.
4. The serialization docs — page data now goes through the Symfony serializer, which is a different contract from whatever the package used before.

Smallest first use case: take one page class that uses annotations, convert it to attributes, and render it through the redesigned UI end to end. That single vertical slice exercises all four breaking changes at once — PHP floor, attribute syntax, new view layer, new serialization — and gives you a realistic diff size before you commit to migrating the rest.

// Illustrative shape only — confirm exact attribute names against the docs.
// Before (no longer read):
/**
 * @SomePageOption(title="Invoices")
 */

// After:
#[SomePageOption(title: 'Invoices')]
class InvoicesPage { /* ... */ }

Implementation Patterns

Treat attributes as the primary configuration surface. Native attributes are real PHP, which is the underrated win here: IDEs autocomplete them, phpstan/psalm validate the arguments, and a typo becomes a static-analysis error instead of a page that quietly renders without its options. Lean into that:

• Move any convention you previously enforced by docblock into a custom attribute class with typed, readonly constructor properties.
• Add a PHPStan rule (or a simple test that reflects over page classes) asserting required attributes are present, so missing metadata fails in CI rather than in production.
• Migrate in a single sweep per module and delete the annotation-parsing dependency if it was only there for this package — leftover annotation libraries confuse the next reader into thinking the old style still works.

Build a serialization layer you own. The switch to the Symfony serializer makes page data a first-class, versionable contract. Use it deliberately rather than letting the package infer everything:

• Define explicit page-data DTOs instead of handing Eloquent models to the serializer; normalizers will happily walk relations and expose attributes you never meant to send.
• Register custom normalizers behind NormalizerAwareInterface and tag them in a service provider — this is the supported extension point for value objects, enums and money/date types.
• Set a CircularReferenceHandler up front. Page graphs that reference back to their parent are common, and the default throws.
• Version the payload explicitly (a version key on the serialized envelope) and assert on it in tests. That's the "simplifies versioning" claim made concrete — it only pays off if you actually stamp and check the version.

Snapshot page payloads in tests. Since the serializer now owns the wire format, the highest-value regression test is a JSON snapshot of a representative page's props. It catches UI-contract drift after composer updates, which is otherwise invisible until it breaks the front end.

Stage the UI migration separately from the backend migration. The redesign is the change most likely to need visual QA. Sequence it as: (1) PHP 8.2 + attributes, ship; (2) serializer DTOs, ship; (3) new UI + re-published assets, ship behind visual review. Combining all three makes every failing test ambiguous.

Re-publish assets and clear caches as part of the deploy step, not as a debugging step:

php artisan vendor:publish --tag=<package-assets> --force
php artisan optimize:clear

Gotchas and Tips

A patch release with BC breaks is a semver violation — plan accordingly. 6.4.14 is not a safe auto-update. Pin exactly, read the upgrade guide, and if you can't migrate immediately, add a conflict constraint so a future composer update can't drag you in. Set your update policy for this package to "read notes, then bump" permanently; the version number is not a signal you can rely on.

Annotations fail silently. Nothing errors when the package stops reading docblocks — pages just render with defaults, options missing. Grep the codebase for the old annotation syntax before upgrading (@SomePage, and whatever prefix the package used) and treat any hit as an incomplete migration. This is the bug most likely to reach production, because the app still "works".

The serializer does not honour Laravel's usual contracts. Arrayable, JsonSerializable, $hidden and $appends behaviour is not guaranteed to carry over. Audit every model or DTO that ends up in page data: check for (a) attributes that were hidden by Laravel but now serialize, (b) dates whose format changed to RFC 3339 via DateTimeNormalizer, and (c) relations being traversed eagerly. Add a test asserting the exact JSON shape rather than trusting assertSee.

Front-end assertions and caches will break in confusing ways. Serialized payload changes flow into Inertia/Livewire-style prop assertions, cached page fragments, and any client-side keying on the old shape. If you cache rendered pages, bust those keys on deploy — otherwise you'll debug a fix that appears not to work.

Debugging the serializer: enable the Symfony debug serializer in a local service provider (or TraceableSerializer) to see exactly which normalizer handled which node. When output looks wrong, the question is almost always "which normalizer won?", and this answers it in one look.

Re-publishing assets without --force leaves stale compiled files after a full UI redesign. Combined with browser and view caches, this produces the classic "I upgraded but the UI looks identical" symptom.

Extension points worth knowing: custom attributes (typed, readonly) for configuration; custom normalizers plus NormalizerAwareInterface for serialization; published views for UI overrides — but for a redesign of this size, prefer the package's new component API over patching published Blade files, since patched views are the thing that breaks again next release.