Storia Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for design-system tooling — now with a test story. Storia remains an in-app catalog for PHP/Twig components, but 0.6.0 adds storia:test, HTML snapshot comparison, and PHPUnit integration (StoriaVariants, StoriaTestCaseTrait). That changes the question from "do we buy a component gallery?" to "do we buy a gallery and a visual-regression harness?" — a materially bigger scope than 0.5.0 offered, and one that overlaps with snapshot-testing vendors.
• Docs-as-artifact and release hygiene. storia:export generates a static catalog site with assets. This unlocks publishing component docs to an internal static host (or per-PR preview) without running a Symfony app in production. Directly relevant if the roadmap includes "design system documentation" as a deliverable rather than a side effect of dev tooling.
• AI-assisted development workflows. storia:list / storia:render commands, a skills/ui-storia agent skill, and Symfony Mate tools mean the catalog is now machine-readable. This is a real input to the "how do we give coding agents grounded UI context?" decision — a cheap way to let agents enumerate and render real component variants instead of guessing at markup.
• QA cost model for a shared component library. Controls (edit variant args in a tab and see the result) plus shared data files (!data, !repeat, !lorem, PHP data providers) reduce the manual effort of covering states/variants. This supports a decision to standardize variant coverage as a QA gate, at the cost of one more thing to maintain.
• Framework-fit decisions — unchanged conclusion, narrower blast radius. Still a Symfony bundle, not Laravel. But symfony/form and symfony/ux-twig-component are now optional: the bundle compiles without them, and only the matching view types go dark. For a Laravel-first or minimal-Symfony team, the integration surface to evaluate is now smaller than the 0.5.0 assessment assumed.
• Security and data-handling posture. Args and blocks now flow through the rendering context rather than the Twig source, so data-provider values are never compiled as Twig; the storia/ folder is documented as code. This removes a class of "internal tool executes user-ish input" objections — relevant if the catalog is ever exposed beyond a laptop.
• Roadmap timing — upgraded from "watch" to "justified time-boxed spike." The feature set now spans preview, export, snapshot testing, and agent tooling, which is enough to evaluate against a real workflow rather than a demo. The adoption signals from the prior assessment (tiny star count, zero dependents) were not re-supplied with this release — the data payload came back empty — so re-check them before any commitment beyond a spike.

When to Consider This Package

Consider it when:

• Your components render in PHP/Twig (Symfony-style or a Laravel app you're willing to run a Symfony-adjacent tool alongside) and you want both a browser catalog and CI-checkable variant snapshots from one tool.
• You want component documentation published as a static site, and running the bundle in a production environment is undesirable — note the new default: Storia is enabled only when kernel.debug is true, so non-debug environments require an explicit iq2i_storia.enabled: true.
• You're investing in agent-assisted development and want agents to enumerate and render real component variants via storia:list / storia:render rather than hallucinating markup.
• You need shared, realistic fixture data (named data files, !repeat, !lorem, PHP providers) to make variant coverage tractable across teams.
• It remains an internal, reversible decision — dev tooling plus optional CI snapshots, not shipped product surface.
• You evaluate it as a time-boxed spike and account for the breaking changes if you already trialed 0.5.x.

Look elsewhere when:

• Your stack is Laravel-native and you have no appetite for introducing Symfony components or a parallel tool runtime. The optional symfony/form / ux-twig-component dependencies make it lighter, not Laravel-shaped.
• Your component library is JS/React/Vue-centric — the Storybook ecosystem still wins on breadth, community, and snapshot tooling maturity.
• You need the AI-agent integration to be vendor-neutral; the shipped tooling targets Symfony Mate specifically, so treat it as a pattern to copy, not a portable standard.
• You require a support contract, security SLA, or a maintenance owner upstream. Nothing in this release changes that the project is early-stage and single-maintainer-adjacent.
• Upgrading an existing 0.5.x spike is more work than it's worth: the menu Twig function removal, the debug-gated enablement, the block-rendering change, and the form-variant options precedence reversal will each break existing catalogs.

How to Pitch It (Stakeholders)

Executive summary: iq2i/storia-bundle 0.6.0 grows from a lightweight PHP/Twig component catalog into a three-part tool: a local preview UI, a static documentation exporter, and a variant snapshot-testing harness with commands that coding agents can call. That breadth makes it worth a short, reversible evaluation — but it is still an early-stage, Symfony-flavored, MIT-licensed project with no support commitment, and the upgrade from the prior version is breaking. Recommendation: evaluate, don't standardize.

Engineering framing: Low integration cost for a Symfony/Twig codebase, and lower than before — symfony/form and symfony/ux-twig-component are now optional. The interesting new capability is storia:test with HTML snapshots and a PHPUnit trait, which turns variant coverage into something CI can enforce; storia:export gives us static docs without running the bundle outside debug. Two things to flag: Storia is now off by default outside kernel.debug, and the iq2i_storia_menu() Twig function is gone because the bundle builds the sidebar — both will break any 0.5.x trial. Security posture improved (data-provider values no longer compiled as Twig, CSRF disabled in form previews for stable snapshots), which matters if this ever leaves a laptop. Vendor or fork to de-risk maintenance.

Decision requested: Approve a bounded spike (days, not sprints) in a non-critical repo covering three things: (1) does the catalog actually get used by design/QA, (2) does storia:test give us snapshot coverage cheaply enough to adopt, and (3) does storia:export remove the "who hosts the docs?" blocker. If any of the three lands, reopen build-vs-buy against Storybook/Fractal — the release now ships its own comparison docs, which makes that conversation cheaper to have. If none land, we've spent days and learned where our component-documentation gap actually is.