Api Components Bundle Laravel Package

Product Decisions This Supports

• Content/component composition modeling (build vs. buy). The bundle provides hierarchical component grouping with draft/published states. If the roadmap includes a composable CMS, design-system registry, or page-builder surface, adopting this replaces a meaningful chunk of custom domain modeling — evaluate it as a buy/adopt candidate before scoping bespoke work.
• Data-integrity guarantees at the API boundary. This release closes a class of corruption bug: a component can no longer be placed inside its own subtree (at any depth, with published and draft counting as one). A position that would contain its own group is now a 422 on component; assigning a group owner from inside it is a 422 on components. Previously a cycle already in the database could make ComponentVoter recurse indefinitely. For the PM this is a reliability decision, not a feature: it removes an unbounded-failure mode (authorization timeouts / 500s) and converts it into a predictable validation error.
• API contract surface for clients. Two new rejection paths on component and components mean client apps and editors need to render those 422s. This is a small, well-bounded front-end/contract task — worth ticketing explicitly so it isn't discovered in QA.
• Platform upgrade roadmap. Symfony 8.1 now resolves on the 8.1 legs instead of being capped at 7.4 by an old test dependency. That unblocks the Symfony 8 upgrade track for any consuming service and shortens the tail of "we can't upgrade because of a transitive dev dependency."
• Roadmap sequencing / maturity gating. This is 2.0.0-alpha.30 — still pre-stable. The correct roadmap artifact is a time-boxed pilot with a pin, not a committed delivery dependency.
• Team-process decisions. Behat is fully removed in favour of PHPUnit functional tests on API Platform's ApiTestCase (in-memory SQLite per process, debug-kernel group, Risky-failing configs, Infection coverage, single Codecov upload). If any internal test conventions or golden scaffolds were forked from features/, that path moved to tests/Functional/assets and tests/Functional/Fixture/scaffolds.

When to Consider This Package

Consider adopting when:

• You need hierarchical component/group composition with publish states, and you'd otherwise hand-roll graph validation, ownership rules, and cycle detection.
• You want server-side, non-recursive authority checks (ComponentVoter) over that graph rather than duplicating the rules in each client.
• You're prepared to run an alpha in a bounded scope: a spike, an internal tool, or a service behind an adapter with a pinned version and a named owner for upgrades.
• You value maintainer hygiene as a signal: functional coverage on every CI leg, mutation testing in the pipeline, Risky treated as failure. That is a credible indicator the project won't rot under you.

Look elsewhere when:

• You are on Laravel. This is an API Platform/Symfony bundle; there is no meaningful Laravel integration path. In a Laravel codebase, treat it as a reference implementation for the domain rules and build the equivalent with Eloquent/policies — do not attempt to bolt it in.
• You need stable semver, an SLA, or a security-response commitment — alpha versioning does not provide them.
• You have no Symfony 8 appetite or are pinned to older Symfony/PHP; the release is explicitly steering toward 8.1 (and symfony/yaml / symfony/translation are now direct dev dependencies).
• You depend on Behat feature files or the old features/ layout — that is a breaking change for anyone extending or forking the suite.
• Your content model is flat; the cycle/ownership machinery is cost without benefit.

Migration notes for the adopting team: expect to rewrite any Behat-based tests into PHPUnit functional tests, re-point asset and fixture paths, and re-baseline CI (one coverage upload). The cycle-prevention change is a behavioural tightening — re-run existing fixtures; data that previously slipped through will now fail with 422, and any pre-existing cycles in a database need a one-off cleanup because the voter no longer recurses but the bad data still exists.

How to Pitch It (Stakeholders)

To executives (one paragraph): We're evaluating a PHP component-tree package that supplies publishing-state component composition and server-side integrity checks. This release is notable for two reasons: it eliminates a data-corruption and infinite-recursion failure mode at the API boundary — the kind of defect that surfaces as outages and manual data repair — and it clears a platform-upgrade blocker by supporting Symfony 8.1. It remains an alpha, so the recommendation is a time-boxed pilot behind an adapter with a pinned version, not a delivery commitment. Upside: avoided custom validation and domain work. Downside risk: alpha churn and upgrade effort, both bounded by the adapter.

To engineering: The security-relevant fix is the cycle guard — component-in-own-subtree is now a 422 on component, owner-from-inside-group is a 422 on components, and ComponentVoter terminates instead of recursing on legacy bad rows. Tooling is consolidated: Behat is gone, every feature is a PHPUnit functional test on ApiTestCase with in-memory SQLite and a debug-kernel group; both PHPUnit configs fail on Risky and the functional suite runs on every Behat CI leg and in Infection. Symfony 8.1 resolves on 8.1 legs; symfony/yaml and symfony/translation are direct dev dependencies. Expect to migrate forked Behat suites and the moved tests/Functional/assets / tests/Functional/Fixture/scaffolds paths, and to handle the two new 422 responses in client error states.

Recommendation: Pilot. Adopt in a non-critical path, pin 2.0.0-alpha.30, isolate behind an interface so a swap or a Laravel-native rebuild stays cheap, and reassess at the first stable 2.0.0.