Weave Code
Twig Truncate Extension Laravel Package
dzango/twig-truncate-extension
Twig extension that truncates text while preserving HTML tags. Adds a truncate filter with options for length, ending, exact word cutting, and HTML handling—works with rendered markdown or raw content. Easy to register in Twig or Symfony2.
A Twig extension to truncate text while preserving HTML tags
Frequently asked questions about Twig Truncate Extension
- Can I use this package directly in Laravel Blade templates without Twig?
- Yes, but you’ll need to create a custom Blade directive to wrap the Twig extension’s logic. The package itself is Twig-focused, so Laravel’s Blade won’t natively support its filters. Example: Register a `@truncate` directive in `AppServiceProvider` to mimic the Twig filter syntax. This avoids full Twig integration while preserving HTML tags.
- How does this compare to Laravel’s built-in `Str::limit()` for truncating text?
- Unlike `Str::limit()`, which truncates plain text and breaks HTML tags, this package preserves HTML structure while cutting text. Use it for SEO snippets, excerpts, or markdown content where HTML integrity matters. For simple text truncation, `Str::limit()` is lighter and faster. Benchmark both for your specific use case.
- Will this work with Markdown content rendered in Laravel?
- Absolutely. The extension handles rendered Markdown (converted to HTML) seamlessly, as long as you pipe it through Twig’s `raw` filter before truncating. Example: `{{ $markdownContent|markdown|raw|truncate(100) }}`. This ensures HTML tags like `<strong>`, `<a>`, or `<img>` remain intact during truncation.
- What Laravel versions does this package support, and are there any Twig compatibility issues?
- The package targets Laravel 8+ (Twig 2.x) by default. For Laravel 7, use Twig 1.x compatibility mode. If you’re using `twig/bridge` or `twiglumen/twig`, pin Twig versions explicitly in `composer.json` to avoid conflicts. Test thoroughly, as Laravel’s bundled Twig may differ from the package’s dependencies.
- How do I handle edge cases like malformed HTML or nested tags (e.g., tables, SVGs)?
- The extension uses DOM parsing, which may struggle with malformed HTML or complex structures like nested tables or SVGs. Pre-sanitize input with `DOMDocument` or libraries like `masterminds/html5` to ensure valid markup. For edge cases, add validation logic or fall back to a simpler truncation method if HTML integrity isn’t critical.
- Is there a performance impact for high-traffic Laravel applications (e.g., API responses)?
- Yes, DOM parsing for truncation is heavier than string operations. Benchmark with tools like Laravel Debugbar or Blackfire to measure impact. For high-throughput APIs, consider caching truncated snippets or using a lighter alternative like `Str::limit()` if HTML preservation isn’t mandatory.
- Can I integrate this with Symfony components in a Laravel app, or is it Laravel-only?
- The package is framework-agnostic and works with Twig in any PHP environment. If your Laravel app uses Symfony components (e.g., Lumen or Symfony bundles), you can leverage the `TwigTruncateBundle` for automatic service registration. Otherwise, manually add the extension to your Twig environment or use Blade directives for Laravel-specific integration.
- How do I migrate from a custom truncation helper to this package?
- Start by auditing your existing truncation logic (e.g., regex-based helpers or JavaScript solutions). Replace one use case at a time, like blog excerpts or API responses, using the package’s `truncate` filter. For Blade, create a directive to match your helper’s syntax. Test edge cases (e.g., HTML entities, nested tags) before full migration.
- Are there alternatives for HTML-aware truncation in Laravel if I don’t want to use Twig?
- For Blade-only apps, consider custom directives using DOMDocument or libraries like `spatie/html` for HTML-aware truncation. Alternatively, use JavaScript-based solutions (e.g., jQuery’s `.text()` + `.html()`) for client-side truncation. However, these may not work for SEO-critical content or server-side rendering.
- How do I contribute or maintain this package long-term if Twig changes its API?
- Monitor Twig’s changelog for breaking changes and update the package accordingly. If the maintainer is inactive, fork the repository and submit pull requests upstream. For critical projects, consider pinning Twig versions in `composer.json` to avoid compatibility risks. Document your customizations for future maintenance.
Weaver
How can I help you explore Laravel packages today?