Clean Phone Numbers in TYPO3: Why We Built EXT:phone_number

Why the Output Format Matters

What visitors actually read is the number printed on the page, and that’s where consistency counts. A number shown three different ways across three pages chips away at the polish of an otherwise clean site.

International visitors expect a predictable format, and in Germany the DIN 5008 standard sets clear rules for how a number should be written. Depending on the context you might want the full international form (+49 711 3400810) in your imprint and the shorter national form (0711 3400810) in a footer—ideally from the exact same stored number, without touching the backend.

Doing that formatting by hand in every template doesn’t scale. Each one ends up with its own little bit of logic, and over time you get exactly the kind of wild growth we try to avoid: many slightly different solutions to the same problem.

Our Solution: A Small ViewHelper Powered by libphonenumber

The idea behind phone_number is deliberately narrow: one Fluid ViewHelper that takes a raw phone number or a tel: URI and formats it into a clean international or national number. One line in your template, consistent output everywhere.

Installation works as usual via Composer:

Then register the namespace in your Fluid template:

From there it’s a one-liner. International format is the default:

Output: +49 711 3400810

Need the national format instead? Flip one argument:

Output: 0711 3400810

It’s not limited to German numbers, either. Pass a US number and libphonenumber formats it the American way:

Output: +1 212–555–0123

Switch to national=”1” and you get (212) 555–0123—the format US readers expect.

The country comes from the number itself: the +1 tells libphonenumber it’s a US number, so the right format follows automatically—independent of your site’s language. The defaultRegion argument (more on it below) only kicks in for numbers stored without a country code, telling the parser which country to assume.

And if a number is stored as a plain string rather than a tel: link, it normalizes that too:

Output: +49 711 3400810

This is the case the extension is really built for: a field defined as TCA type=link with allowedTypes=telephone—the Phone link type from the wizard—hands you a tel: URI, and the ViewHelper turns it straight into clean output. The number an editor picks in the backend is the number your visitor sees, cleanly formatted, every time.

The Arguments, at a Glance

The ViewHelper keeps its options short and predictable:

• value — the phone number or tel: link to format. Required.
• defaultRegion — the region used to parse numbers that come without a country code. Defaults to DE, and it only matters for those bare numbers—so set it to your company’s home country rather than the site’s language (the English site of a French company still wants FR here).
• national — format the number in national style (0711 …) instead of international. Defaults to off.

Requirements

EXT:phone_number runs on PHP 8.1 and supports TYPO3 12, 13, and 14. It’s open source under GPL-2.0-or-later, and the number parsing is handled by libphonenumber-for-php-lite—so you get battle-tested formatting rules without pulling in a heavy dependency.

Conclusion

Phone numbers are a small detail, but small details are what make a site feel finished. Instead of formatting them by hand in every template, EXT:phone_number gives you one consistent, reusable way to do it: install the extension, register the namespace, add one ViewHelper, and your numbers just look right.

Documentation and source code are available on GitHub: https://github.com/b13/phone-number