marcgoertz / shorten-twig
A Twig extension for the marcgoertz/shorten package.
1.0.0
2025-08-19 13:11 UTC
Requires
- php: >=8.2
- marcgoertz/shorten: ^5.0
- twig/twig: ^3.0
Requires (Dev)
- php-coveralls/php-coveralls: ^2.4.3
- phpunit/phpunit: ^11.3.1
- squizlabs/php_codesniffer: ^3.6.0
README
A Twig extension for the
marcgoertz/shorten
package that safely truncates HTML markup while preserving tags, handling entities, and supporting Unicode/emoji with optional word-safe truncation.
Installation
I recommend using Composer for installing and using the Shorten Twig Extension:
composer require marcgoertz/shorten-twig
Usage
Basic Setup
<?php use Twig\Environment; use Twig\Loader\FilesystemLoader; use Marcgoertz\Shorten\ShortenTwigExtension; $loader = new FilesystemLoader('templates'); $twig = new Environment($loader); $twig->addExtension(new ShortenTwigExtension()); ?>
Template Usage
{{ '<a href="https://example.com/">Go to example site</a>'|shorten(10) }}
Output:
<a href="https://example.com/">Go to exam</a>…
Filters
shorten
Safely truncate text or HTML markup using the marcgoertz/shorten
library.
shorten(length = 100, suffix = '…', appendixInside = false, wordsafe = false, delimiter = ' ')
Parameters
int $length
: Maximum length of truncated text (default:400
)string $appendix
: Text added after truncated text (default:'…'
)bool $appendixInside
: Add appendix to last content in tags, increases$length
by 1 (default:false
)bool $wordsafe
: Wordsafe truncation, cuts at word boundaries (default:false
)string $delimiter
: Delimiter for wordsafe truncation (default:' '
)
Examples
{# Basic truncation #} {{ 'A very long text that needs to be shortened'|shorten(20) }} {# Output: A very long text th… #} {# Custom suffix #} {{ 'A very long text that needs to be shortened'|shorten(20, '...') }} {# Output: A very long text th... #} {# Wordsafe truncation #} {{ 'A very long text that needs to be shortened'|shorten(20, '…', true) }} {# Output: A very long text… #} {# HTML markup preservation #} {{ '<b>Bold text</b> and <i>italic text</i>'|shorten(15) }} {# Output: <b>Bold text</b> and <i>ita</i>… #}
Features
- ✅ Preserves HTML tag structure and proper nesting
- ✅ Handles HTML entities correctly
- ✅ Supports self-closing tags (both XML and HTML5 style)
- ✅ UTF-8 and multibyte character support (including emojis)
- ✅ Wordsafe truncation to avoid cutting words in the middle
- ✅ Configurable suffix text and placement
- ✅ Easy integration with existing Twig templates
- ✅ Full compatibility with
marcgoertz/shorten
v5.0+
Requirements
- PHP 8.2+
- Twig 3.0+
marcgoertz/shorten
5.0+
Development
Running Tests
composer test
Code Style
composer lint composer fix
License
MIT © Marc Görtz