Api Component Bundle Laravel Package

Technical Evaluation

Architecture fit. First, a scoping correction: this package (components-web-app/api-components-bundle) is a Symfony bundle built on API Platform, not a Laravel package. It is a domain/API layer for a component/group hierarchy with draft-vs-published semantics and a ComponentVoter authorization layer. If our target stack is Laravel, this is not a drop-in fit — integration would require either standing up a separate Symfony service behind HTTP or a significant adapter effort. If our stack is Symfony + API Platform (PHP 8.x, Symfony 7.4/8.1), the architecture is a clean fit: the bundle owns the entity graph and validation, and exposes HTTP semantics we can consume.

Integration feasibility. Installable via Composer as a bundle; runtime surface is unchanged in this release — every change is either a validation fix or test-infrastructure work. That makes the code change low-risk to adopt, but the version carries the real feasibility question: 2.0.0-alpha.30 is the thirtieth alpha of a major version, which signals a long, still-open stabilization window and no compatibility promise. Any adoption must be a pinned, deliberate decision, not a floating constraint.

Technical risk.

• Client-visible behavior change (the only one): writes that would create a cycle — placing a component inside its own subtree at any depth, where a published component and its draft are treated as one node — now return 422 on component, and assigning a group owner from inside the group returns 422 on components. Any client that previously relied on silent acceptance (or on a 500) must handle field-scoped 422s.
• Existing data is the sharper risk: ComponentVoter previously recursed forever on a cycle already present in the database. The fix prevents the crash but does not clean that data. A cycle in production is a latent outage that will now surface as a 403/denial rather than a hang — better, but it must be found and repaired deliberately.
• Draft/publish coupling: collapsing published + draft into a single node for cycle detection is correct domain modeling, but it means validation depends on how draft state is represented. Worth confirming this holds for our publishing workflow.
• Low direct risk: Behat removal, PHPUnit/ApiTestCase migration, SQLite-per-process, failOnRisky, Infection, and the features/ → tests/Functional/{assets,Fixture/scaffolds} move are all internal. They touch us only if we consume the bundle's feature files or scaffold fixtures, or if we contribute upstream.
• Dependency signal: the test environment now resolves Symfony 8.1 instead of being capped at 7.4 by Behat's transitive dependencies. This is a dev constraint change, but it strongly implies runtime support is tracking toward 8.x — verify the actual composer.json runtime constraints before planning our Symfony upgrade path around it.

Key questions.

1. What are the runtime require constraints for Symfony and PHP in this tag, versus what the 8.1 dev resolution implies?
2. Is there a 1.x → 2.0 upgrade guide, and which of the 30 alphas introduced breaking changes we would inherit?
3. What is the GA target for 2.0.0, and is the alpha API considered frozen?
4. Does any 1.x client payload shape now legitimately produce a 422 (e.g., nested tree construction in a single request)?
5. Are the moved tests/Functional/Fixture/scaffolds assets referenced by any downstream tooling, or purely internal?
6. How is draft-vs-published modeled, and does the "counting as one" rule hold for our editorial workflow?

Integration Approach

Stack fit. Adopt only on a Symfony + API Platform service. Confirm the runtime Symfony range (7.4 vs 8.1) and PHP floor before committing; the release notes prove the test suite runs on 8.1 but say nothing binding about runtime. If our product surface is Laravel, treat this as an external service dependency with an HTTP contract, not an embedded package.

Migration path. Treat this as a data-first migration, not a code-first one:

1. Before any upgrade, run a read-only traversal over the component graph to detect cycles (including draft/published equivalence) and group-ownership self-references. Produce a data-quality report.
2. Repair any cycles found before deploying, so the ComponentVoter fix does not convert a hang into an unexplained authorization denial on live traffic.
3. Then upgrade the package, pinned to an exact alpha version.
4. Update API clients to parse field-scoped 422 errors on component and components and surface them as actionable validation messages rather than generic failures.

Compatibility. Runtime compatibility is narrow and unproven at the edges: pre-release major, 30 alphas deep, Symfony version floor in motion. Plan for the composer constraint to move under us and pin accordingly. Client compatibility is the concrete work item — the 422 contract is new and additive in spirit but behaviorally breaking for callers that build hierarchies in one shot.

Sequencing.

1. Confirm stack fit and runtime constraints (blocking).
2. Cycle/ownership data audit against a production snapshot (blocking).
3. Pin alpha in a staging environment; run our own fixture suite against it.
4. Client error-handling changes for the new 422 field contract.
5. Canary with write-path monitoring on 422 rates.
6. Only then consider broader rollout, with a GA checkpoint before long-term commitment.

Operational Impact

Maintenance. Alpha churn is the dominant ongoing cost: expect repeated upgrades and repeated re-validation until 2.0.0 GA. Budget for a named owner who tracks upstream releases rather than a passive "install and forget." The upside is real — removing Behat collapses two test runners into one, gives a single Codecov upload, and adds Infection mutation testing, all of which raise the quality signal per unit of CI time.

Support. Upstream is a small, active project (PR-numbered, contributor-driven). Escalation paths are GitHub issues, not a vendor SLA. Internal support burden shifts toward us: we own the cycle-audit runbook and the client-side 422 handling. The Behat removal is mildly negative for supportability if our team leans on Gherkin as executable documentation — that readable specification layer is now PHPUnit code, which is more precise but less stakeholder-legible.

Scaling. Cycle validation runs on the write path and walks the ancestor chain, so cost scales with hierarchy depth and requires an indexed parent reference; deep trees will pay more per write than flat ones. This is almost certainly negligible against typical write volumes, but it is a new O(depth) validation step and should be in the performance model. ComponentVoter recursion is now bounded, which removes a genuine availability risk — the previous behavior was an unbounded stack recursion reachable from ordinary authorization checks.

Failure modes.

• Silent data problem: a pre-existing cycle passes undetected until an authorization check denies access; symptom looks like a permissions bug, root cause is graph corruption. Mitigate with the pre-migration audit and a periodic integrity check.
• Client rejection: legitimate bulk/nested creation now 422s; if clients don't parse field errors, users see unexplained failures. Mitigate with explicit error-surface work.
• Version drift: an unpinned alpha pulls an incompatible API; mitigate by pinning exactly and upgrading deliberately.
• Dev-only churn misread as runtime change: the Symfony 8.1 resolution and the new direct symfony/yaml / symfony/translation dev dependencies can trigger "we must upgrade Symfony now" pressure that the release notes do not actually justify.

Ramp-up. Onboarding gets easier: PHPUnit functional tests on ApiTestCase are the idiom most PHP developers already know, so a new engineer can read and extend the suite on day one — no Behat/Gherkin context required. Conversely, the team loses the plain-language feature files as a specification artifact, so expect to invest once in a short internal note covering the tree/ownership invariants and the 422 contract. Overall ramp-up: low for the test layer, moderate for the domain rules, which are genuinely subtle (draft/published equivalence, group ownership direction).