Ui Bundle Laravel Package

Getting Started

Start by reading the repo before installing — with 1 star and zero dependents you are the documentation. Clone it, open composer.json, src/, and Resources/ (or templates/), and map out what the bundle actually ships: Twig extensions, form themes, layouts, or asset helpers.

Minimal path:

composer require spipu/ui-bundle

• Confirm Flex auto-registered it in config/bundles.php; if not, add Spipu\UiBundle\SpipuUiBundle::class => ['all' => true].
• Publish config and assets if the bundle exposes them:

  php bin/console config:dump-reference spipu_ui
  php bin/console assets:install public
  

• Register the Twig namespace in config/packages/twig.yaml if templates are not in the default @SpipuUi path.

First use case: render the bundle's base layout (or a single widget) inside an existing controller via $this->render('@SpipuUi/...') and confirm it renders in isolation before wiring it into a real page. That one smoke test tells you which assets, form themes, and blocks the bundle expects.

Implementation Patterns

Layout inheritance. Rather than consuming the bundle's layout directly, extend it and override blocks locally. Keep a project-level templates/base_ui.html.twig that does {% extends '@SpipuUi/layout.html.twig' %} so future bundle upgrades don't leak into your pages.

Form theme integration. If the bundle ships form themes, register them per-form (not globally) via $builder->setAttribute('form_theme', ...) or in twig.yaml under form_themes — scoped registration avoids fighting your own theme.

Widget/macro usage. Prefer the bundle's Twig functions/macros over hand-rolled markup, but wrap them in project-level macros so swapping the dependency later is a one-file change.

Service override. Small bundles usually register a few services (menus, asset managers, UI configurators). Configure via config/services.yaml setDecoratedService or a compiler-pass override rather than editing vendor files.

Controller integration. Keep UI concerns in a thin AbstractController layer — pass pre-shaped view models to templates, and let the bundle handle only rendering. That leaves you free to drop the bundle's markup without touching your domain layer.

Workflow when extending. Follow the bundle's own conventions: mirror its directory structure under templates/bundles/SpipuUiBundle/ and its service IDs in your config. Overrides then apply cleanly on every composer update.

Gotchas and Tips

• Sparse docs. Assume the README is thin. Run php bin/console debug:twig and debug:container --tag=twig.extension to discover what the bundle actually exposes before guessing at template names.
• No dependents, so no community answers. Before filing an issue, inspect the bundle's own tests (vendor/spipu/ui-bundle/tests/) — those are the real usage examples.
• Bundle not in Flex recipe. Recent or low-adoption bundles often skip Symfony Flex recipes; expect to add the class to config/bundles.php manually and manually register Twig paths.
• Assets. If the bundle references CSS/JS via asset(), verify those files are actually published (assets:install) or available in vendor/.../Resources/public. Missing assets render as silent broken layouts, not exceptions.
• Form theme ordering. Form themes are stack-based; a bundle theme registered globally can silently clobber your own. Register per-form when possible, or set twig.form_themes order deliberately.
• Twig namespace collisions. If both your app and the bundle define a @.../layout.html.twig, the Symfony bundle override path (templates/bundles/<BundleName>/) wins only for the bundle's own namespace — check your paths.
• Template override path. Use templates/bundles/SpipuUiBundle/<relative path> — the exact bundle name matters, and case sensitivity bites on Linux.
• Pin the version. With one star and no downstream users, composer require spipu/ui-bundle:^X.Y (explicit constraint) protects you from an unannounced BC break. Check CHANGELOG.md on every bump.
• Debug Twig render errors with APP_DEBUG=1 and twig.debug: true; a missing block in a bundle layout often surfaces as a confusing "block not found" from your own template, not the bundle's.
• Extension points. Look for interfaces (e.g. a menu or asset provider) and implement them in your app rather than copying vendor code — small bundles frequently leave the intended extension seams undocumented but structurally obvious in src/Service/.
• Exit strategy. Because the package is tiny, keep a thin adapter layer (your own Twig macros + a small service) between your app and the bundle. If it stops being maintained, you swap the adapter for hand-written Twig in an afternoon.