How to convert HTML entities like – to their character equivalents?

How to convert HTML entities like – to their character equivalents?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Decoding Numeric HTML Entities in Text Files

When processing text files generated by web applications, you often encounter a mix of character encodings that don't match the file's intended output format. A common scenario involves data saved as UTF-8 containing numeric HTML entities like – instead of their actual character equivalents, such as the n-dash (–). While PHP's html_entity_decode() function handles named entities (like –) effectively, it frequently fails to decode numeric entities represented in decimal format. This leaves your text file populated with raw entity strings rather than readable punctuation or special characters.

To resolve this discrepancy without resorting to brittle string replacements for every possible character, you need a solution that interprets the numeric value directly. The standard approach involves using html_entity_decode() with an additional step to handle decimal entities specifically, or relying on a native function designed for this exact purpose depending on your environment.

In PHP, the core issue is that html_entity_decode() treats – as a literal string unless the encoding context explicitly supports decoding numeric references. Simply passing the string to the function often results in no change if the entity format isn't recognized by default settings. The most robust solution within PHP is to combine decoding logic or use a dedicated function that handles both named and numeric entities comprehensively.

If you are working within the Laravel ecosystem, the Illuminate\Support\Str facade provides utility methods that can assist with string manipulation, but for direct entity decoding, sticking to core functions with correct parameters is often more reliable. You can ensure numeric entities are decoded by explicitly setting the encoding parameter in html_entity_decode(). For instance:

$content = html_entity_decode($input, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

However, even with these flags, some legacy parsers or specific entity formats might slip through. A more comprehensive approach involves using the mb_convert_encoding() function combined with html_entity_decode(). This two-step process first converts any potential HTML character references to their actual characters, ensuring that numeric entities like – are interpreted correctly:

// First decode entities
$content = html_entity_decode($input, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');

// Ensure proper encoding context for any remaining issues
$content = mb_convert_encoding($content, 'UTF-8', 'HTML-ENTITIES');

The mb_convert_encoding() function acts as a safety net, re-interpreting the string in a way that forces numeric entities to resolve into their Unicode equivalents. This is particularly useful when dealing with dynamic data where the source might mix different entity formats.

It is crucial to understand the trade-offs involved. Using ENT_SUBSTITUTE ensures that undefined characters are replaced rather than left as-is, preventing potential encoding errors downstream. However, this also means you lose information about unknown entities, which might be a concern if data integrity for those specific cases is critical. If your application requires preserving unknown entities exactly as they appear while only fixing known numeric ones, omitting ENT_SUBSTITUTE allows the function to leave unrecognized entities untouched, though it risks leaving malformed data in the buffer.

Another consideration is performance. Applying multiple encoding conversions on large files can increase memory usage and CPU time. If you are processing massive logs or datasets, streaming the file or using a generator might be preferable to loading the entire content into memory before decoding. In such cases, wrapping the logic in a helper class or function that processes chunks of data ensures scalability without sacrificing correctness.

Ultimately, the goal is to produce a clean text file where users see the intended characters—like an n-dash instead of –—upon opening the document locally. By combining html_entity_decode() with proper encoding flags and potentially leveraging mb_convert_encoding(), you can handle dynamic entity formats reliably without hardcoding replacements for every possible character.

Our network