Laminas Escaper

A common security mistake is using a different encoding for the Escaper instance than the one declared in the HTML document. This mismatch can lead to incorrect escaping and potential vulnerabilities.

Correct Pattern:

1. Set the Escaper encoding (e.g., 'utf-8').
2. Set the HTTP Content-Type header to match (e.g., text/html; charset=UTF-8).
3. Set the HTML <meta> charset tag to match (e.g., <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">).

// Good: Encodings match
$escaper = new Laminas\Escaper\Escaper('utf-8');
header('Content-Type: text/html; charset=UTF-8');

echo $escaper->escapeHtml($input);

The core of the component is the Laminas\Escaper\Escaper class. It provides five specific methods for escaping data based on the output context. To prevent Cross-Site Scripting (XSS), you must select the method that matches the specific context where the data will be rendered:

• escapeHtml: Use for data being placed inside an HTML body.
• escapeHtmlAttr: Use for data being placed inside an HTML attribute.
• escapeJs: Use for data being placed inside a JavaScript context.
• escapeCss: Use for data being placed inside a CSS context.
• escapeUrl: Use for data being placed inside a URI or URI parameter.

Note: It is the developer's responsibility to ensure the correct method is used for the intended context.

use Laminas\Escaper\Escaper;

$escaper = new Escaper();
// Example usage:
$safeHtml = $escaper->escapeHtml($unsafeString);

Standard HTML escaping (e.g., htmlspecialchars()) is only safe for HTML attributes if you can guarantee the attribute is properly quoted.

There are two primary risks when using standard escaping instead of escapeHtmlAttr():

1. Single Quoted Attributes: By default, htmlspecialchars() uses the ENT_COMPAT flag, which does not escape single quotes ('). An attacker can use a single quote to break out of a single-quoted attribute and inject new attributes like onmouseover.
2. Unquoted Attributes: In HTML5, attributes do not require quotes. Standard escaping does not account for characters like spaces or equals signs that allow an attacker to break out of an unquoted attribute context.

Always use escapeHtmlAttr() to handle these edge cases automatically.

Using json_encode() to escape data intended for JavaScript literals inside an HTML document is unsafe. json_encode() does not escape characters that might be interpreted as HTML entities or structural HTML tags, which can allow an attacker to break out of the JavaScript string and execute arbitrary code (XSS).

Always use Laminas\Escaper\Escaper::escapeJs() instead of json_encode() when the output is being placed inside a <script> block in an HTML document.

<?php
// BAD: Vulnerable to XSS in HTML context
$input = 'bar&quot;; alert(&quot;Meow!&quot;);';
$output = json_encode($input);
?>
<script>
    var foo = <?= $output ?>;
</script>

<?php
// GOOD: Safe against XSS
$escaper = new Laminas\Escaper\Escaper('utf-8');
$output = $escaper->escapeJs($input);
?>
<script>
    var foo = "<?= $output ?>";
</script>

A critical distinction in using laminas-escaper is its purpose: it is strictly for escaping data for output to prevent XSS.

Do not use laminas-escaper for filtering input data. For input sanitization and filtering, use alternative tools such as:

• laminas-filter
• HTMLPurifier
• PHP's built-in Filter functionality

To prevent XSS attacks when inserting dynamic data into a URL, use the escapeUrl() method.

Important: URL escaping should only be applied to the specific data being inserted into a URL parameter or path, not to the entire URL string itself.

Internally, escapeUrl() acts as an alias for PHP's rawurlencode(), adhering to RFC 3986.

$input = '" onmouseover="alert(\'laminas\')';
$escaper = new Laminas\Escaper\Escaper('utf-8');
$output = $escaper->escapeUrl($input);

// Use $output when building your URL
$url = "http://example.com/?name=" . $output;

When dealing with DOM-based XSS—where JavaScript in a template inserts data into the DOM—a single layer of escaping is often insufficient. If you only escape for HTML, the string might still contain malicious JavaScript. If you only escape for JavaScript, the string might contain HTML markup that gets parsed when injected.

Best Practice: Use multiple levels of escaping for nested contexts. For example, if you are placing a string inside a JavaScript variable that will eventually be inserted into the HTML DOM, you should escape the string for HTML first (to make it safe for DOM insertion), and then escape it for JavaScript (to make it safe for the current JavaScript context).

You can install laminas-escaper as a standalone component using Composer. It is designed to be used independently of the rest of the Laminas framework.

$ composer require laminas/laminas-escaper

To add laminas-escaper to your PHP project, use Composer to require the package.

$ composer require laminas/laminas-escaper