Twig Components Bundle Laravel Package

Getting Started

1. Install the bundle

   composer require olveneer/twig-components-bundle
   

2. Register the bundle in config/bundles.php if Flex didn't do it for you (older bundles predate Flex recipes):

   Olveneer\TwigComponentsBundle\TwigComponentsBundle::class => ['all' => true],
   

3. Configure a component directory (this is the bit to verify against the README, since option names have changed across tag releases):

   # config/packages/twig_components.yaml
   twig_components:
       components_dir: '%kernel.project_dir%/templates/components'
   

4. Create your first component. Just a Twig file in that directory — e.g. templates/components/button.html.twig:

   <a href="{{ url|default('#') }}" class="btn btn-{{ variant|default('primary') }}">
       {{ label }}
   </a>
   

5. Render it from any template. The bundle's Twig extension exposes a component() function that includes the matching file and merges the hash you pass in:

   {{ component('button', { label: 'Save', variant: 'success' }) }}
   

Where to look first: the package README, then src/Twig/ (the extension/function registration) and src/DependencyInjection/Configuration.php to see the real option names and defaults. The first practical use case is almost always an Alert, Button, or Card — repeated markup that varies only by props.

Implementation Patterns

• Presentational component library. Keep templates/components/ flat and shallow, one component per file, named after its use (button.html.twig, alert.html.twig, modal.html.twig). Treat props as an implicit contract and document them with a Twig comment at the top of each file.
• Prop-driven rendering. Pass a single hash as the second argument and use default filters inside the component so callers only supply what differs. This keeps callers terse:

  {{ component('alert', { type: 'danger', message: 'Something failed' }) }}
  

• Wrapper components with inner content. For containers (cards, modals, panels) you want the caller's markup inside the component. Depending on the tag, this is either a block form ({% component 'card' %}...{% endcomponent %}) or a slot API on a returned object. Inspect the Component base class — the slot methods are the non-obvious part of the API.
• Component classes for logic. When a component needs computed values (formatting, lookups, authorization checks), create a class alongside it and register it as a service; the Twig side becomes a thin view. Keep business logic out of .twig files — that's the whole point of the "modular" pitch.
• Nest freely. Components can call component() themselves. Build a layout/ set (header, footer, nav) and compose them in base.html.twig so page templates read like a manifest of parts.
• Integration from controllers. Anything a component needs that isn't a prop should be passed explicitly from the controller's render context rather than reaching through app.* globals — it makes components reusable in tests and in emails/PDFs rendered outside an HTTP request.

Gotchas and Tips

• Maturity check before committing. 31 stars and 0 dependents means no production track record. Pin the version (composer require olveneer/twig-components-bundle:^x.y) and read its composer.json — it likely declares Symfony ^3|^4 constraints and will need --with-all-dependencies or a compat shim on Symfony 5/6.
• Cache is your first debugging step. After adding or renaming a component file, run bin/console cache:clear. Twig caches compiled templates by name, and a renamed component can silently serve the old include or throw a "template not found" that looks like a config error.
• Filename vs. name string must match exactly. component('Button') vs button.html.twig is a case-sensitivity trap on Linux (works on macOS, breaks in CI). Pick lowercase names and stick to them.
• Context inheritance. Verify whether components inherit the parent Twig context or get an isolated one. If they inherit, a parent variable can silently override a prop and you'll get "why is variant wrong here?" bugs. Prefer explicit props for anything that matters.
• Slots are the least stable part. Block/slot handling is where lightweight component bundles usually diverge from Symfony UX Twig Components. If you hit weird whitespace or escaping inside slots, check the extension's compile function and whether it marks output as safe.
• Debug inside a component with {{ dump(_context) }} (Twig debug bundle) to see exactly which props arrived. Faster than re-reading the extension source.
• Extension points: the base Component class (subclass it to add shared helpers like attr() or class()), the Twig extension itself (register extra functions), and the configured component paths (point at multiple directories to allow project-level overrides of vendor components — order determines precedence).
• Migration path: symfony/ux-twig-component is the maintained, first-party equivalent. If you outgrow this bundle (or it goes stale against your Symfony version), the mental model — component file + props + slots — transfers directly, so the rewrite cost is mostly renames.