Hyphenator Bundle Laravel Package

Getting Started

Status check first: this bundle is archived and its last release was 2015-10-24. It was built for the Symfony 2/3 era. Use it to maintain a legacy app; for new work, prefer the underlying org_heigl/hyphenator library directly or CSS hyphens: auto with proper lang attributes.

1. composer require liip/hyphenator-bundle — pin to a version that installs against your Symfony; on Symfony 4+ you may need to register the bundle manually.
2. Register Liip\HyphenatorBundle\LiipHyphenatorBundle in AppKernel (or config/bundles.php).
3. Minimum config:

   liip_hyphenator:
       locale: de_DE
       cache_dir: '%kernel.cache_dir%/hyphenator'
   

4. Where to look first:
   • README.md — short, shows the service and config.
   • DependencyInjection/Configuration.php — authoritative list of keys (locale, cache_dir, quality, left_min, right_min, word_min, filters/no-hyphenate patterns).
   • Resources/config/services.xml — the actual service id (typically liip_hyphenator) and Twig extension wiring.
5. First use case — hyphenate a long compound word so a narrow column doesn't overflow:

   $hyphenator = $this->get('liip_hyphenator'); // or inject it
   echo $hyphenator->hyphenate('Donaudampfschifffahrtsgesellschaft');
   // Donau­dampf­schiff­fahrts­gesellschaft  (soft hyphens, U+00AD)
   

   In Twig, the bundle's extension exposes a filter:

   <h1>{{ 'Donaudampfschifffahrtsgesellschaft'|hyphenate }}</h1>
   

Why server-side hyphenation at all: CSS hyphens: auto depends on browser support and a correct lang attribute. Soft hyphens inserted server-side break consistently everywhere, including PDFs, emails, and older browsers.

Implementation Patterns

• Inject by service id in legacy config; add a type alias if you want autowiring:

  services:
      Org\Heigl\Hyphenator\Hyphenator: '@liip_hyphenator'
  

• Wrap it in a small application service so you can swap the implementation later and add pre/post-processing (strip HTML, skip code blocks, restore hard hyphens).
• Per-locale hyphenation: set a sensible default in config, then pass the request locale per call when rendering multilingual pages (hyphenate($text, $request->getLocale())). Confirm the pattern set for that locale exists.
• Render-time vs write-time: for stable CMS content, hyphenate once at save/publish and store the soft-hyphenated text; for user-generated or dynamic content, hyphenate in the view layer. Write-time saves CPU but complicates editing and search — strip U+00AD before indexing.
• Narrow layouts (sidebars, mobile cards, table headers): apply the filter only to the text nodes that overflow, not to whole pages. Pair with overflow-wrap as a fallback.
• PDF/email generation: hyphenate before handing text to DomPDF/TCPDF/wkhtmltopdf; these renderers frequently ignore hyphens: auto.
• Presenter/ViewModel pattern: keep entities clean; hyphenate in a view model or Twig extension so the database stores real text.
• Editorial rules (never hyphenate brand names, URLs, code, acronyms): use the underlying library's filter system and register a custom filter rather than regexing the output.

Gotchas and Tips

• Archived/deprecated. No fixes for modern Symfony. Expect to adapt service definitions or load the bundle manually, and plan an exit (direct library, CSS hyphenation, or a maintained fork).
• Soft hyphen (U+00AD), not -. It's invisible but present in strings: copy/paste, search, JSON APIs, and strlen all see it. Strip it (str_replace("\x{00AD}", '', $s)) at boundaries.
• Don't feed it HTML. The hyphenator doesn't know about tags and will hyphenate inside attributes and markup. Apply it per text node or strip tags first.
• cache_dir must be writable. The library parses TeX-style patterns and caches them; first use per locale is slow, and a read-only container filesystem will hurt. Clear the cache after upgrading the underlying library — the cache format can change.
• Locale/pattern mismatch. de_DE vs de, and locales without patterns may silently fall back or not hyphenate at all. Test with real compound words, not hello.
• Tune word_min / left_min / right_min. Defaults can hyphenate too aggressively; standard typography is roughly word_min 6+, left_min/right_min 2–3.
• quality trades CPU for correctness. Benchmark on long lists; consider caching hyphenated output by hash for high-traffic pages.
• Twig extension quirks. Depending on version, the filter may output ­ (needs |raw) or the literal U+00AD character. Check which, and confirm the extension is auto-registered on your Symfony version.
• Debugging. bin/console debug:container liip_hyphenator (older Symfony: container:debug) to confirm wiring; call hyphenate() in a throwaway command and inspect with bin2hex() to verify U+00AD placement.
• Extension point worth knowing. The library's filters are the clean way to encode "never hyphenate X" rules; the bundle's no-hyphenate config may only cover simple cases.