Ux Bundle Laravel Package

Getting Started

Step 0 — settle the stack question before writing any code. kibatic/ux-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no facade, no config/ux.php publish tag, and no container binding. composer require kibatic/ux-bundle in a Laravel app will at best install dead weight and at worst drag in symfony/framework-bundle transitively. For a Laravel developer the realistic paths are:

1. You actually maintain a Symfony service — treat the rest of this section as the onboarding path.
2. You don't — read the source as a reference implementation and port the ideas to Blade + Livewire/Inertia/Vite+Stimulus (or htmx/Turbo via hotwired-laravel). Do not attempt to retrofit the bundle.

If you have a Symfony app, minimal path to first render:

1. composer require kibatic/ux-bundle, then check for a Flex recipe: composer recipes kibatic/ux-bundle. If none ships, register manually in config/bundles.php:

   Kibatic\UxBundle\KibaticUxBundle::class => ['all' => true],
   

2. Confirm it booted and discover its real config surface — don't guess the alias:

   php bin/console debug:container KibaticUxBundle
   php bin/console debug:config kibatic_ux   # adjust to getAlias()
   

3. Publish/wire the front-end assets. On Symfony 7 prefer AssetMapper (php bin/console importmap:require ...); on legacy use Webpack Encore. Pick one — see Gotchas.
4. First use case worth trying: a single Turbo Frame wrapping one form (inline validation, partial refresh) on one low-traffic internal page. That exercises the Twig helper, the Stimulus wiring, and the Turbo integration in one go, and it is trivially revertible.

Implementation Patterns

• Leaf dependency, not foundation. Adopt behind a single layout/partial and keep usage grep-able. If removal takes more than an afternoon, you've over-adopted a 0-star package.
• Thin internal abstraction. Wrap the bundle's Twig helpers in your own Twig extension (or Blade component, if porting). Every call site then goes through code you own, so swapping to vanilla Symfony UX or in-house helpers doesn't touch product templates.
• Config-first overrides. Read the bundle config tree from debug:config and override in config/packages/kibatic_ux.yaml rather than forking. Template overrides live in templates/bundles/KibaticUxBundle/… using Twig's standard bundle-path lookup — that's the cheapest extension point.
• Turbo Frame workflow. Wrap the form in <turbo-frame id="…">, render the same frame target on both success and validation failure, and return 422 on failure so Turbo swaps the frame instead of following the redirect.
• Stimulus controller conventions. Keep your controllers in the same registration mechanism the bundle expects (AssetMapper controllers/ glob or Encore controllers.json). If the bundle ships its own controllers, verify they load alongside yours before layering behaviour on top.
• Pin and lock. Exact version in composer.json, lockfile committed, and note the version in the PR description. With zero dependents there is no field evidence of compatibility — you are generating it.
• Canary + comparison. Run one app for a full Symfony minor-upgrade cycle and keep a written comparison against what vanilla Symfony UX would have cost. That comparison is the only thing that justifies keeping the dependency.
• If porting to Laravel: map Twig helpers → Blade components, Stimulus registration → Vite import.meta.glob, bundle config → config/ux.php. Turbo semantics carry over unchanged; the Symfony wiring does not.

Gotchas and Tips

• Bundles are not packages. The single biggest pitfall is assuming cross-framework portability because the catalog lists it under PHP. Confirm the framework before it enters a roadmap; if Symfony-only, the decision is "port the ideas," not "adopt the package."
• Bus factor of one. Zero stars, zero dependents, single maintainer. Assume you are the de facto maintainer: tracking Symfony releases, patching incompatibilities, likely forking within a year or two. Budget it as an ongoing line item, not a one-time install.
• Verify the release tag. The listed last release (2026-06-11) is future-dated relative to typical consumption — check whether it's a real tag, a pre-release, or a metadata artifact, and read the changelog velocity before pinning.
• Upgrade blockade is the real failure mode. UX packages track Symfony minors closely. A bundle that pins a minor stalls the whole application on an unsupported framework version — a security-patching problem, not just a cosmetic one. Test every Symfony minor bump against it.
• Don't mix AssetMapper and Encore. Running importmap and Encore simultaneously is the most common cause of "Stimulus controller silently not registered." Pick one per app.
• Wrong alias debugging. debug:config fails with an unhelpful error if you guess the alias. Use debug:container KibaticUxBundle first, or run php bin/console list to see registered commands it adds.
• Turbo + forms: validation failures must return a non-2xx status with the frame re-rendered; returning 200 with a redirect body or a full page silently breaks the frame. CSRF tokens need to round-trip through Turbo Drive — check they aren't stripped on re-render.
• Silent divergence after upgrades. When upstream Symfony UX moves and this bundle stagnates, you get subtle rendering/asset bugs with no upstream fix. Snapshot your rendered HTML in a smoke test so drift shows up in CI rather than in a bug report.
• Extension points, in order of cost: bundle config → template override in templates/bundles/ → service decoration of its Twig extension → fork. Stop at the cheapest one that works; a fork is an indefinite maintenance tax.
• Blast radius is bounded — use that. Failures manifest in rendering and interactivity, not auth or persistence. That justifies a canary-only rollout, and it's the strongest argument for trying it on internal tooling at all.
• Don't present it as a solution. If you pitch it internally, frame it as "cheap option to test with a known exit ramp." Anything stronger will not survive a quarter of production.