Ux Sdc Laravel Package

Technical Evaluation

Architecture fit. tito10047/ux-sdc is a PHP package in the Symfony UX family that implements Single Directory Components (SDC): a component's template, props/schema, and co-located CSS/JS live in one directory and are auto-discovered. The 0.3.0 change ("Changed Bundle name") confirms the package ships as a bundle — i.e., it registers against a framework kernel bundle list, exposes a DI extension with a config alias, and registers Twig namespaces/tags and asset paths. That is a strong fit for Symfony-based PHP applications and a partial fit for Laravel: Laravel has no bundle/DI-extension concept, so consuming it requires a service-provider bridge or an adapter layer that re-implements discovery and config. A TPM should treat "Laravel package" here as "PHP package usable in Laravel only with a shim," and not promise drop-in Laravel support without a spike.

Integration feasibility. Mechanically simple: composer require, register the bundle (or bridge provider), point config at the component directories, and render components from templates. The 0.3.0 rename is the only integration-relevant change and it is narrow in surface but wide in blast radius: every reference to the old bundle name — bundle registration, YAML config root key, service IDs derived from the alias, Twig namespace/tag names, and any container-compile cache — must be updated in lockstep. Feasible in a single PR for a small codebase; requires a grep-and-verify pass for larger ones.

Technical risk.

• Semantic versioning: 0.3.0 is pre-1.0, so a BC break is contractually permitted. Risk is not "the maintainer broke semver," it is "we adopted a 0.x dependency and must budget for renames."
• Silent failure mode: a stale bundle name typically fails at container compile or, worse, resolves to nothing at render time — components render empty rather than erroring, which is a QA-visible-but-CI-invisible class of bug.
• Single-maintainer package with a small PR history (PR #10) — bus factor and review depth are the dominant long-term risks, not the rename itself.
• No deprecation shim mentioned: the release notes state the break but not whether an alias/back-compat layer exists. That is the single most important unknown.

Key questions.

1. What exactly was renamed — the bundle class/FQCN, the container alias, the Composer package name, the Twig namespace, or all of the above?
2. Is the old name retained as a deprecated alias in 0.3.0, or is this a hard cut with no shim?
3. Does the rename change the published config filename/root key (e.g., ux_sdc.yaml → new key), requiring config republish and diff?
4. Are asset/output paths affected (public build dir, importmap entrypoints), which would break cached/deployed assets independently of PHP?
5. Minimum PHP and framework versions for 0.3.0 — any bump bundled silently with the rename?
6. Is there a documented upgrade guide or only the one-line changelog entry?

Integration Approach

Stack fit. Best fit: Symfony 6/7 + Twig, where the bundle plugs into the kernel and the DI extension natively. Acceptable fit: Laravel via a thin service provider that registers component paths and a Blade/Twig directive — but this is our code to own and maintain, and the 0.3.0 rename shifts work onto that adapter (it must track the upstream name). Poor fit: any stack expecting stable 1.x APIs today.

Migration path. Pin explicitly. Today we are on nothing (no prior assessment), so this is a greenfield adoption decision, not an upgrade: adopt ^0.3 from the start and skip the rename entirely — the BC break costs us zero if we have not yet integrated 0.2.x. If any prototype or spike branch exists against 0.2.x, treat it as throwaway rather than migrating it. Record the chosen bundle name and config root key in our integration notes so the next 0.x rename is a one-file change.

Compatibility. Verify PHP constraint and framework constraint from composer.json before committing; confirm the bundle compiles against our current Symfony/Laravel version and that its Twig/asset requirements do not collide with our existing pipeline. Because the rename may alter autoloaded FQCNs, run a full composer dump-autoload and container cache clear as part of the compatibility check, not as a deploy step.

Sequencing.

1. Spike (1–2 days): install ^0.3 in a scratch app, build two components (one with props, one with co-located CSS/JS), confirm render output and asset emission.
2. Decide the Laravel question: native Symfony-only, or fund the bridge provider. Do not start the bridge before the spike passes.
3. Pin the version and lock file; add a CI job that runs container compile + a component render smoke test so future renames fail loudly.
4. Roll out to one non-critical surface, then widen.

Operational Impact

Maintenance. Low code volume, non-trivial version-tracking burden. Expect one breaking rename per few 0.x releases; budget a recurring half-day per minor bump for grep/rename/verify plus cache and asset rebuild. Owning the Laravel adapter materially raises this — the adapter must be re-validated on every upstream release, doubling the maintenance surface for a package we do not control.

Support. Single maintainer, small contributor base, one-line changelog entries. We should not expect migration guides; our own upgrade notes effectively become the support artifact. Internally, designate one owner for the integration and one backup — the failure mode of "only one engineer understands the component discovery config" is realistic on a small team.

Scaling. Component discovery and container compilation are build-time costs; runtime rendering is cheap. Watch compile time and cache size as the component count grows into the hundreds, and watch asset build output if every component emits co-located CSS/JS. Neither is a blocker at typical scale, but both are worth a benchmark before adopting across a large design system.

Failure modes.

• Stale bundle name after upgrade → container compile error (loud, good) or empty component render (silent, bad).
• Config root key mismatch → defaults applied silently, components resolve to wrong paths.
• Stale container/asset cache after rename in a deployed environment → works locally, fails post-deploy; mitigate by making cache clear part of the release, not a manual step.
• Missing component → confirm whether the package throws or degrades to empty output; if the latter, add a render smoke test to CI.
• Upstream abandonment → fork-and-vendor is the fallback; keep the integration thin enough that this is a day, not a quarter.

Ramp-up. Small for a developer already fluent in Twig/Blade components — the SDC mental model (one directory, co-located everything) is intuitive and the API surface is narrow. Roughly a day to first productive component, a week to comfortable. The real ramp-up cost sits with whoever owns the Laravel bridge, since that requires understanding the bundle's DI extension internals. Non-technical stakeholders need one framing: this is a pre-1.0 building block, chosen for developer ergonomics, with a known and budgeted churn cost until it reaches 1.0.