Api Component Bundle Laravel Package

Product Decisions This Supports

• Hierarchical content/component modeling — the package backs a component tree with groups, ownership, drafts and publishing. The 2.0.0-alpha.30 fix closes a real integrity hole: a component can no longer be nested inside its own subtree at any depth (published + draft treated as one), returning a 422 on component; assigning a group owner from inside that group returns a 422 on components. That turns a class of corrupt-data bugs (and a ComponentVoter infinite recursion) into a clean, client-facing validation error — a decision-enabler if your roadmap includes reordering, drag-and-drop nesting, or delegated group ownership.
• Build vs. buy for a headless content API — this is an existing Symfony/API Platform bundle with draft/publish semantics, voters/authorization, and HTTP cache + purge behavior. Adopting it replaces a bespoke "component tree + permissions + publishing" service; the new test suite (health checks, HTTP cache, rendered-HTML purge ported to PHPUnit) documents exactly which behaviors are contractually guaranteed.
• Roadmap sequencing around a 2.x alpha — the release is 2.0.0-alpha.30. Plan integration as a spike/behind-a-flag item, not a committed Q-date dependency, until a stable 2.0 lands. Budget an upgrade window for the 1.x → 2.x boundary.
• Platform currency decisions — the test environment now resolves Symfony 8.1 (previously capped at 7.4 by Behat's dependencies). Adopting this release is the low-friction path to keeping the service on a supported Symfony line; staying on older releases increasingly means pinning and diverging.
• Definition-of-done / QA standards — Behat is gone; every feature is now a PHPUnit functional test on ApiTestCase with in-memory SQLite per process, and both configs fail on Risky. This gives product a single, enforceable regression gate and one Codecov upload — useful when arguing for (or defending) release quality bars.
• API error-contract decisions — because self-nesting and cross-group ownership violations are now explicit 422s with field targets (component, components), the frontend can render precise, localized validation messages instead of generic 500s. Worth locking into the API contract docs before client teams build against it.

When to Consider This Package

Consider it when:

• You are building on PHP with Symfony + API Platform and need a component/content tree with groups, ownership, drafts and publish state — i.e., the domain model is already close to what this bundle ships.
• You need authorization-aware content operations (voters) and HTTP caching with purge semantics without hand-rolling them.
• You can absorb alpha-grade churn: 2.0.0-alpha.30 means API surface and behavior can still move between alphas; treat the version pin as a deliberate risk, not an accident.
• The team is comfortable with a PHPUnit-only test story (no Behat/Gherkin). If your org's acceptance-testing standard is Behat, the migration in #517 is a (small) process change to socialize.
• You value data-integrity guardrails over permissive writes — the new 422s are opinionated and will reject request payloads that previously "worked" (by silently creating cycles).

Look elsewhere when:

• Your stack is Laravel-first with no Symfony/API Platform footprint. This is a Symfony bundle; forcing it into a Laravel app means carrying API Platform and its assumptions — usually a worse trade than a native Laravel package or a small in-house implementation.
• You require a stable, semver-guaranteed dependency for a near-term launch. Alpha numbering (.30) signals the opposite; wait for a stable 2.0 tag or accept a support burden.
• You need multi-tenant or non-hierarchical content models — the component/group/owner tree is the core abstraction; if your model is flat or graph-like beyond trees, you'll fight it.
• Your authorization model is external (e.g., a central policy service). ComponentVoter becomes a wrapper you must reconcile rather than a benefit.
• You need PHP versions or Symfony lines older than what 2.x supports — the move to Symfony 8.1 in test environments signals where maintenance effort is directed.

Immediate integration note: treat the self-nesting rejection as a client-visible behavior change. Audit any existing importers, bulk-move endpoints, or admin UI flows that could attempt a subtree re-parent and ensure they handle 422 on component / components gracefully.

How to Pitch It (Stakeholders)

For executives (one paragraph): This release hardens a content-structuring service we would otherwise have to build ourselves. It converts a class of silent data corruption — content nested inside itself, which could also crash our permission checks — into a clean validation error the UI can explain to users. In parallel, the project consolidated its entire test suite onto one modern framework and moved onto the current Symfony generation, which lowers our long-term maintenance and upgrade cost. The caveat is maturity: this is still an alpha (2.0.0-alpha.30), so I recommend a time-boxed evaluation spike rather than a committed delivery dependency until a stable 2.0 ships.

For engineering leads: Two things landed. (1) Integrity: cycle prevention is enforced at write time at any depth (published and draft components treated as a single node), returning 422 on component for self-containment and 422 on components when a group owner is set from inside the group; ComponentVoter no longer infinite-recurses on pre-existing cycles in the database — so expect to need a data-remediation pass if any cycles are live. (2) Tooling: Behat is removed; all features are PHPUnit functional tests on ApiTestCase with per-process in-memory SQLite, the debug-kernel group, and both configs failing on Risky. CI is PHPUnit-only with a single Codecov upload; assets and the golden scaffold moved to tests/Functional/assets and tests/Functional/Fixture/scaffolds. The test environment now resolves Symfony 8.1, no longer capped at 7.4, and symfony/yaml / symfony/translation are direct dev dependencies. Net: a stricter, faster, single-path test story — but any local Behat tooling, Gherkin fixtures, or CI jobs referencing features/ paths must be updated in the same change.

For product/design: Users can no longer accidentally drop a component into its own subtree — the API rejects it with a field-level error, so we should design the empty/invalid drop state and message rather than relying on a generic failure.