XSS Protection and Output Encoding in PHP

1. Why a single filter is not enough for XSS protection

XSS protection is reduced in many PHP codebases to a single call to htmlspecialchars(), regardless of where the value ends up in the HTML document. That works reliably in the HTML body but fails in other output contexts such as an unquoted HTML attribute, a JavaScript string, or a URL. Effective XSS protection therefore always means knowing the concrete output context and choosing the escaping function that matches exactly that context, rather than applying one function everywhere.

Cross-site scripting happens when user controlled data is inserted into a page in a way that makes the browser interpret it as code instead of data. The cause is almost never a total absence of XSS protection, but a wrong assumption about the output context. A value that was safely escaped for the HTML body can still enable script execution inside an onclick attribute, because different characters are critical there.

2. Using output encoding correctly in the HTML body

For text output directly between HTML tags, htmlspecialchars() with the flags ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5 is the foundation of any solid XSS protection concept. ENT_QUOTES ensures that both double and single quotes are encoded, which matters if the value is later reused inside an attribute. ENT_SUBSTITUTE replaces invalid UTF-8 sequences with a substitute character instead of letting the function return an empty string, which would otherwise be a potential denial of service risk.

Important for consistent XSS protection: the character encoding must be explicitly given as the third parameter as soon as the application works with an encoding other than UTF-8, otherwise older encoding bugs can arise in combination with multi byte characters. In modern PHP versions UTF-8 is the default, which reduces the risk, but legacy systems using ISO-8859-1 should always set the encoding explicitly.

<?php

declare(strict_types=1);

/**
 * Escape a value for safe placement inside an HTML text node.
 */
function escapeHtml(string $value): string
{
    return htmlspecialchars($value, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');
}

$comment = $_POST['comment'] ?? '';

// Safe: user input is treated strictly as text, not markup
echo '<p>' . escapeHtml($comment) . '</p>';

// Unsafe: raw interpolation lets any injected <script> tag execute
// echo '<p>' . $comment . '</p>';

3. HTML attributes: the most common encoding mistake

The most common mistake in XSS protection happens in unquoted HTML attributes. <div data-id=> without surrounding quotes lets an attacker inject a new attribute such as onmouseover=alert(1) using just a space, even if htmlspecialchars() was applied, because spaces are not treated as a critical character by that function. The reliable rule for XSS protection in attributes is therefore: always wrap attribute values in double quotes, never leave them unquoted.

Even with correct quoting, htmlspecialchars() with ENT_QUOTES remains the right choice for attribute values, because both single and double quotes need to be encoded regardless of which quote style the template actually uses. If ENT_QUOTES is missing and single quotes are used by accident, a gap for XSS protection bypasses remains open that is easily missed during code review.

<?php

declare(strict_types=1);

$productId = $_GET['id'] ?? '';
$safe = htmlspecialchars($productId, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');

// Safe: quoted attribute, ENT_QUOTES covers both quote styles
echo '<div data-product-id="' . $safe . '">';

// Unsafe: unquoted attribute — a space injects a new attribute like onmouseover
// echo '<div data-product-id=' . $safe . '>';

4. JavaScript context: why htmlspecialchars is not enough

If a PHP value is inserted directly into an inline <script> block, htmlspecialchars() is not sufficient for complete XSS protection, because JavaScript strings recognize different special characters than HTML. A value like ');alert(1);// would pass through htmlspecialchars() unchanged, since neither JavaScript style quotes nor semicolons belong to the HTML characters it encodes. The correct approach for XSS protection in this context is to serialize the value through json_encode(), which automatically escapes all characters critical to JavaScript strings.

In addition, json_encode() should be called with the flags JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP when the resulting value ends up inside an HTML <script> tag, so that an embedded </script> in the value cannot prematurely close the surrounding tag. Without these flags an attacker could use the string </script><script>alert(1)</script> to bypass XSS protection, even if json_encode() was used without the additional flags.

<?php

declare(strict_types=1);

$userName = $_GET['name'] ?? '';

// Safe: proper JSON encoding with HTML-context-aware flags
$jsonSafe = json_encode(
    $userName,
    JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_QUOT | JSON_HEX_AMP | JSON_THROW_ON_ERROR
);

echo '<script>const userName = ' . $jsonSafe . ';</script>';

// Unsafe: htmlspecialchars() does not escape JS-critical characters
// echo '<script>const userName = "' . htmlspecialchars($userName) . '";</script>';

5. URL context: rawurlencode instead of manual filters

When values are embedded into a URL, for example as a query parameter or part of a path, rawurlencode() is the right function for XSS protection in this context, not htmlspecialchars(). rawurlencode() encodes according to RFC 3986 and correctly handles special characters such as &, = and spaces, which could otherwise alter the URL structure itself or inject additional parameters. It is equally important to check the scheme of a user controlled URL value: a javascript: scheme inside an href attribute bypasses any encoding, because it remains syntactically valid while still executing script code.

For complete XSS protection with user controlled URLs, an allowlist of permitted schemes, typically https and mailto, is recommended before the value is even inserted into an attribute. A value that does not start with an allowed scheme should either be discarded or reset to a safe default, rather than blindly encoded and output.

<?php

declare(strict_types=1);

/**
 * Validate and encode a user-supplied URL for safe use in an href attribute.
 */
function safeHref(string $url): string
{
    $allowedSchemes = ['https', 'mailto'];
    $parsed = parse_url($url);

    if (!isset($parsed['scheme']) || !in_array(strtolower($parsed['scheme']), $allowedSchemes, true)) {
        return '#'; // Reject javascript:, data:, and unknown schemes outright
    }

    return htmlspecialchars($url, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, 'UTF-8');
}

$profileLink = $_GET['link'] ?? '';
echo '<a href="' . safeHref($profileLink) . '">Profile</a>';

6. DOM-based XSS: when the server is not involved at all

Not every XSS vulnerability originates on the server. DOM-based XSS occurs when client side JavaScript writes a controllable value, for example from location.hash or document.referrer, unchecked into innerHTML or a similarly dangerous sink, without a PHP server ever touching that value. Server side XSS protection using htmlspecialchars() has no effect on DOM-based XSS, because the problematic data flow happens entirely inside the browser.

For PHP applications that ship JavaScript, this means: the server side escaping rules from this article do not automatically protect against DOM-based XSS in your own frontend code. Hyvä themes and Alpine.js components that use x-html instead of x-text should therefore be reviewed especially carefully for which values are actually rendered as markup rather than plain text, and whether those values originate from a trusted, already server side escaped source.

7. Templates and automatic escaping

Modern template engines such as Twig or Blade offer automatic escaping as default behavior, eliminating a large share of manual XSS protection effort. Every expression in {{ variable }} is automatically escaped for the HTML body context without developers having to think about it. The risk shifts to the explicit deactivation of escaping, for example via {{ variable|raw }} in Twig, which should be used deliberately and rarely, only for values demonstrably originating from trusted sources.

In plain PHP without a template engine, XSS protection remains the developer's responsibility at every single output point. A practical intermediate solution is a small helper class with context specific methods such as e() for HTML, eAttr() for attributes and eJs() for JavaScript, used consistently in templates instead of the raw variable, which significantly reduces the risk of forgotten escaping.

8. Common mistakes in output encoding

The most common mistake is calling htmlspecialchars() without ENT_QUOTES and then relying on the assumed XSS protection inside a single quoted attribute. Without this flag, only double quotes are encoded, and a single quote inside the attribute value can terminate the attribute prematurely. A second mistake is double escaping, where an already escaped value is passed through htmlspecialchars() a second time, resulting in visible HTML entities like < instead of correctly rendered characters.

A third, more subtle mistake concerns confusing escaping with validation. XSS protection through output encoding prevents a value from being interpreted as code, but says nothing about whether the value is meaningful or expected. An email address should additionally be validated on top of escaping, because escaping alone lets a semantically invalid input pass without complaint as long as it does not technically enable script execution.

9. Escaping functions compared

Choosing the right escaping function depends entirely on the output context. The overview below maps the most important PHP functions for XSS protection to their respective context.

Applying this table consistently covers the overwhelming majority of real world XSS attack vectors. An application's XSS protection is only ever as strong as its weakest, incorrectly handled output context.

10. Summary

Effective XSS protection in PHP is not a single function call, but a decision per output context: htmlspecialchars() with ENT_QUOTES for the HTML body and quoted attributes, json_encode() with HEX flags for JavaScript strings, rawurlencode() plus a scheme allowlist for URLs. DOM-based XSS is a reminder that server side output encoding alone is not enough once client side JavaScript writes values unchecked into dangerous sinks such as innerHTML.

The most reliable way to implement XSS protection consistently is a small library of context specific escaping helpers, used in every template instead of raw PHP output. Template engines with automatic escaping take over a large share of this responsibility, but they do not replace understanding when and why a particular escaping function is the right choice.

11. FAQ: XSS Protection and Output Encoding in PHP