README

md-php/html-truncation is a PHP component that provides contract and implementation to truncate HTML code.

Powered on top of libxml, dom and mbstring builtin PHP extensions.

Text truncation is the process of shortening a piece of text by cutting it off after a certain length, typically adding an ellipsis ... or another indicator to show that the content has been clipped.

It's useful to create snippets showing only relevant context around a keyword and especially useful to limit content of items in list, for example: generic entry content in admin list, blog articles content and so on.

Architecture overview

Features

• Modern. SOLID & PSR compatible / linted with strict PHPStan and Psalm
• Fast. Recursion-free algorithm
• Memory-efficient. Supports huge documents with nesting up to 100,000 elements (optionally)
• Fresh. Created in 2026, supports latest PHP versions (7.1+ and 8.0+)

Install

composer require md-php/html-truncation

Usage

$truncateHtml = new \MD\HTML\Action\Truncate(allowHugeDocument: false);
$truncateHtml->withTextLength(
    html: '<p>some very long html code</p>',
    maxLength: 10,
    ending: '...'5
);  # ... will return: '<p>some very ...</p>'

Read documentation for more examples.

Integration with Twig

Take a look for a md-php/bridge-twig-html-truncation component that provides additional Twig filter and function to truncate HTML code, like:

{{ "<p>some long html code</p>"|truncate_html_with_text_length(4) }}

or

{{ "some long markdown text"|markdown|raw|truncate_html_with_text_length(8, ';;;') }}

Documentation

Read documentation with examples: https://development.md.land/php/md-html-truncation/

Development

Initial setup:

cp .env.dist .env  # ... change `.env` for your needs
cp phpunit.php71.xml.dist phpunit.xml  # ... choose either 71 or 80 for your needs

Run checks (Psalm + PHPStan + PHPUnit):

docker compose run --build --remove-orphans --entrypoint='/usr/src/app/vendor/bin/deptrac analyse --config-file=deptrac.yaml' run-deptrac

for PHP_VERSION in '71' '80' '85'; do
  export PHP_VERSION="$PHP_VERSION"
  docker compose run -v "$PWD/vendor${PHP_VERSION}:/app/vendor" --build --remove-orphans --env-from-file .env -e XDEBUG_MODE=coverage --entrypoint="bash -c 'composer install ; mv composer.lock composer.php$PHP_VERSION.lock'" run-tests
  docker compose run -v "$PWD/vendor${PHP_VERSION}:/app/vendor" --build --remove-orphans --env-from-file .env -e XDEBUG_MODE=coverage --entrypoint="/usr/src/app/vendor/bin/phpunit --configuration /usr/src/app/phpunit.php$(( PHP_VERSION == 85 ? 80 : PHP_VERSION )).xml.dist --coverage-text" run-tests
  docker run -e "PHP_VERSION=$PHP_VERSION" -v "$PWD:/app" -v "$PWD/vendor${PHP_VERSION}:/app/vendor" --rm -it ghcr.io/danog/psalm:latest /composer/vendor/bin/psalm --no-cache
  docker run -e "PHP_VERSION=$PHP_VERSION" -v "$PWD:/app" -v "$PWD/vendor${PHP_VERSION}:/app/vendor" --rm -it ghcr.io/phpstan/phpstan analyse --configuration phpstan.neon
done;

Validate files:

composer validate --strict
find ./src ./tests -name "*.php" -exec php -l {} \;

Comparison with other solutions

• md-php/html-truncation (THIS)
  • Method: libxml ✅
  • Stars: N/A
  • Installs: N/A
  • Status: Last update: 2026-03-25
  • Features: (see features)
  • PHP version: ^7.1 or ^8.0 ✅
• urodoz/truncate-html
  • Method: regular expression ❗
  • Stars: 21
  • Installs: 287,129
  • Status:
    Last update: 2014-05-25 ❗
    Abandoned (De-facto): No updates, no activity on issues. ❗
  • PHP version: >=5.3 ❗
  • Cons:
    • Coupled to Twig component ❗️
• bluetel/twig-truncate-extension
  • Method: libxml ✅
  • Stars: 11
  • Installs: 97,376
  • Status:
    Last update: 2016-01-19 ❗
    Abandoned (De-facto): No updates, no activity on issues. ❗
  • PHP version: >=5.3 ❗
  • Cons:
    • issues in master branch ❗
      • dumps result only as HTML as full document, no fragment support.
    • recursion method ❗
    • Coupled to Twig component ❗
• judev/php-htmltruncator
  • Method: libxml ✅
  • Stars: 29
  • Installs: 271,305
  • Status:
    Last update: 2019-11-19 ❗
    Abandoned (no updates, no activity on issues) ❗
  • PHP version: >=5.6 ❗
  • Cons
    • One class per file principle violation ❗️
• dzango/TwigTruncateExtension
  • Method: regular expression ❗️
  • Stars: 13
  • Installs: 236,921
  • Status:
    Last update: 2017-12-02 ❗️
    Abandoned (no updates, no activity on issues) ❗
  • PHP version: >=5.6 ❗
  • Pros:
    • Adjust cut off in the middle of the word ✅
  • Cons:
    • One class per file principle violation ❗️
    • Coupled to Twig component ❗️

Roadmap

• add cut off in the middle of the word adjustment
• add feature to truncate text by the words count
• add feature to exclude elements from text truncation
• add benchmarks
• simplify Dockerfile

Changelog

License (MIT)