Smartwig Laravel Package

Getting Started

Smartwig is a Twig extension: it registers a set of component-oriented Twig functions that emit ready-made HTML (buttons, grids, panels, modal scaffolding) instead of you hand-writing the markup in every template.

Minimal steps:

1. composer require yepsua/smartwig (it pulls in Twig and, historically, the yepsua UI helper libraries — check composer.json of the tag you install, since transitive deps may be unmaintained).
2. Register the extension with your Twig environment. In a plain setup:

   $twig->addExtension(new \Yepsua\Smartwig\Extension\SmartwigExtension());
   

   In Laravel with rcrowe/twigbridge, add it to config/twigbridge.php under extensions.
3. Look first at the extension class itself. Open src/ and read getFunctions() — that is the authoritative list of components you actually get. Documentation is thin, but the function list is small enough to read in a sitting.

First use case: render a button or a grid row from data your controller already passes in, e.g. {{ ui_button('Save', {class: 'btn-primary'}) }}. Confirm the exact function names from getFunctions() before copying any snippet — the package predates strict SemVer discipline.

Implementation Patterns

Register once, use everywhere. Wrap registration in a small service provider (or twigbridge config) so components are available in every template without per-controller wiring.

Treat functions as composition primitives. The library's value is nesting: a grid function wrapping panel functions wrapping button functions. Build a layout by passing child markup (or child component output) into the parent's content argument, rather than trying to configure everything on one call.

Wrap the raw functions in your own extension. For day-to-day work, define project-specific Twig functions (e.g. app_toolbar(), app_card()) that call Smartwig internals with your house defaults (button classes, spacing, icon set). This gives you one place to change markup when Smartwig's output doesn't match your design system, and insulates templates from the library's argument signature quirks.

Mirror data shape. These components expect simple scalars/arrays for labels, urls, and child content. Prepare those in the controller (or a view-model) rather than doing logic inside the template call — Twig's expression syntax makes multi-argument component calls hard to read when logic creeps in.

Bridge to the underlying UI library when you need programmatic construction. Smartwig is a thin Twig wrapper; if you ever need components built outside templates (mailables, JSON responses with pre-rendered fragments), use the underlying yepsua UI objects directly and render their __toString().

Integration tip: because output is HTML, keep the component calls in partials and {% include %} them, so escaping behavior and |raw decisions are localized.

Gotchas and Tips

• This package is effectively abandoned. Six stars, zero dependents, low activity score. Pin an exact version in composer.json, and verify it actually loads against your Twig major version — namespace changes between Twig 1.x, 2.x, and 3.x (Twig_Extension vs Twig\Extension\AbstractExtension) will break old extensions outright. Budget an afternoon to fork-and-fix rather than assuming it "just works."
• Escaping. Component output is already markup; if you pass it through autoescape you'll get escaped tags. Use |raw deliberately and only for values you generated, never for user input.
• Bootstrap coupling. Generated class names assume a specific Bootstrap-era convention. If your app uses Tailwind or a newer Bootstrap, expect to override or post-process markup — don't fight it in templates.
• Function name collisions. Generic names like ui_* can clash with other Twig extensions or your own. Enumerate with a one-liner during setup:

  foreach ($twig->getFunctions() as $f) { echo $f->getName(), PHP_EOL; }
  

  and confirm no duplicate registration errors.
• Silent argument mismatches. With no tests, passing the wrong option key often yields default output rather than an error. When a component renders wrong, dump the arguments you actually passed and compare against the extension's source, not against memory of the README.
• Extension points. Subclass the extension and override getFunctions() to swap or rename components; this is the cleanest way to keep a consistent API in your app while still using the library's internals.
• Debugging: start from the function definition in src/, trace to the underlying yepsua UI class, and echo the object's __toString() in isolation. Most "rendering bugs" are wrong option arrays, not Twig problems.
• Dependency hygiene. The transitive yepsua packages may pull old Symfony/Twig constraints. Run composer why and composer outdated before committing, and consider replace/exclude tricks if constraints block your primary framework upgrades.