Smileybundle Laravel Package

Getting Started

This release adds a combinate Twig filter that replaces placeholder tokens in a string and outputs the result for rendering in HTML. Treat it as a small templating helper rather than a full templating engine.

1. Install/update the package:

   composer require <vendor>/<package>:^1.0
   

2. Check that the service provider is auto-discovered, then publish any config if the package exposes one:

   php artisan vendor:publish --tag=<package>-config
   

3. Look first at:

   • the package's config/ file for the filters / extensions registration array,
   • the filter class (usually under src/Filters or src/Twig/Extensions),
   • the package README for the exact filter signature.

4. First use case — substitute tokens in a stored template string and render it inside a Twig view:

   {{ 'Hello %name%, your order %order% is ready.'|combinate({
       '%name%': customer.name,
       '%order%': order.number
   }) }}
   

   Or, if the filter is designed to take a replacement map and return HTML directly:

   {{ template_body|combinate(replacements) }}
   

Because the v1.0.2 release note is terse ("Replace en Show the string in your html page"), confirm the exact argument order and whether the filter escapes output by reading the filter source or its tests before relying on it in production templates.

Implementation Patterns

Configuration-driven registration. Most Laravel/Twig bridges register custom filters in a config array. Add combinate there (or confirm it is registered by the package) so it is available in every Twig view without per-template setup.

Database-driven templates. A natural fit is notification/email templates stored in the database with placeholder tokens:

$body = $template->body; // "Hi %name%, ..."

{{ body|combinate({ '%name%': user.name }) }}

This keeps copy editable by non-developers while substitutions stay in application code.

Keep replacement data explicit. Build the replacement map in a dedicated method or presenter rather than inline in the template. This makes it testable and avoids leaking whole models into the view:

public function replacements(): array
{
    return [
        '%name%'  => $this->user->name,
        '%order%' => $this->order->reference,
    ];
}

Wrap in a mailable. Use the filter when rendering a Twig-based Mailable body, then pass the result into the mail view. Prefer rendering to a string and asserting on it in tests:

$html = view('emails.order', ['body' => $body, 'replacements' => $data])->render();

Chain deliberately. If the filter returns HTML, chain escaping/raw intentionally:

{{ body|combinate(replacements)|raw }}

Only use |raw when the template source and replacement values are trusted; otherwise let Twig escape.

Compose with existing filters. Combine with nl2br, escape, or a sanitizer filter where appropriate, and keep the order explicit so escaping happens after substitution.

Gotchas and Tips

• XSS is the main risk. A filter that "shows the string in your HTML page" likely bypasses or interacts with autoescaping. Escape user-supplied replacement values before substitution, or use an HTML sanitizer on the final output. Never feed raw request input into the replacement map.

• Confirm the filter name. The release note says "combinate", which is unusual. Verify it is registered as combinate (not combine or concatenate) and check for case sensitivity in Twig filter names.

• Argument order is undocumented here. The note is ambiguous about whether it takes a string of replacements, an array, or (search, replace). Read the filter's getName() and getFilters() implementation before adopting it.

• Placeholder collisions and ordering. Sequential string replacement can double-substitute if one replacement value contains another placeholder token. Prefer a single-pass replacement or escape placeholder syntax in user data.

• Clear caches after config changes. Twig bridges often cache compiled templates. Run:

  php artisan view:clear
  php artisan config:clear
  

  If the package has its own cache, clear that too.

• Don't mix Blade and Twig carelessly. Ensure the view uses the .twig extension and the correct rendering engine; a Blade file will not evaluate Twig filters.

• Debugging. Enable Twig's debug mode in local config and use {{ dump(variable) }} to inspect replacement data. If the filter silently returns the input unchanged, the replacement map keys probably don't match the tokens exactly (whitespace, encoding, or delimiter differences).

• Extension point. If you need different behaviour (sanitizing, multi-pass replacement, locale-aware formatting), implement a custom Twig extension/filter and register it via the package's config or your own service provider rather than modifying vendor code.

• Test the upgrade. Since this is a patch release adding a filter, run your existing Twig view tests after updating to confirm the new filter registration didn't alter escaping defaults for other templates.