Laminas Escaper

https://github.com/laminas/laminas-escaper
Admin
Laminas Escaper is a PHP library that provides contextual escaping for HTML, HTML attributes,...
Tokens:29,427
Snippets:193
Trust Score:9.7
License:BSD-3-Clause
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install laminas-escaper with Composer

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/intro.md

Install the laminas-escaper component using Composer. This command adds the package to your project's dependencies.

```bash
$ composer require laminas/laminas-escaper
```

--------------------------------

### escapeHtml() basic example

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Escapes a string containing HTML tags and quotes. Output shows the escaped result.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

$input = '<script>alert("laminas")</script>';
echo $escaper->escapeHtml($input);
// &lt;script&gt;alert(&quot;laminas&quot;)&lt;/script&gt;
```

--------------------------------

### getEncoding() usage example

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Creates an Escaper with 'shift_jis' encoding and prints the result of getEncoding(), which outputs 'shift_jis'.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('shift_jis');
echo $escaper->getEncoding(); // shift_jis
```

--------------------------------

### escapeCss() basic example

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Escapes a CSS string containing a URL and script tag. Output is a series of CSS hex escapes.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

$input = "body { background-image: url('http://example.com/foo.jpg?</style><script>alert(1)</script>'); }";
echo $escaper->escapeCss($input);
// body\20 \7B \A \20 \20 \20 \20 background\2D image\3A \20 url\28 ...
```

--------------------------------

### escapeJs() error handling

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Example of catching a RuntimeException when the input cannot be converted to valid UTF-8. On failure, the safe string is set to an empty string and not emitted.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    $safe = $escaper->escapeJs($userInput);
} catch (RuntimeException $e) {
    // treat as invalid input — do not emit
    $safe = '';
}
```

--------------------------------

### escapeUrl() basic example

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Escapes a string for use in a URL subcomponent using Laminas Escaper. Outputs %22%20onmouseover%3D%22alert%28%27laminas%27%29.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

$input = '" onmouseover="alert(\'laminas\')';
echo $escaper->escapeUrl($input);
// %22%20onmouseover%3D%22alert%28%27laminas%27%29
```

--------------------------------

### Good HTML escaping example (encoding match)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-html.md

Correct usage: the escaper uses UTF-8 and the document is served as UTF-8, ensuring the encodings match. This example shows the right way to set encodings.

```php
<?php
$input = '<script>alert("laminas")</script>';
$escaper = new Laminas\Escaper\Escaper('utf-8');
?>
<?php header('Content-Type: text/html; charset=UTF-8'); ?>
<!DOCTYPE html>
<html>
<head>
    <title>Encodings set correctly!</title>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<?php
    // Good! The escaper's and the document's encodings are same!
    echo $escaper->escapeHtml($input);
?>
</body>
```

--------------------------------

### Good URL escaping example using escapeUrl()

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-url.md

Demonstrates proper URL escaping with escapeUrl() to prevent XSS. The input is escaped before being inserted into the URL, neutralizing the malicious attribute.

```php
<?php header('Content-Type: application/xhtml+xml; charset=UTF-8'); ?>
<!DOCTYPE html>
<?php
$input = <<<INPUT
" onmouseover="alert('laminas')
INPUT;

$escaper = new Laminas\Escaper\Escaper('utf-8');
$output = $escaper->escapeUrl($input);
?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Unescaped URL data</title>
    <meta charset="UTF-8"/>
</head>
<body>
    <a href="http://example.com/?name=<?= $output ?>">Click here!</a>
</body>
</html>
```

--------------------------------

### Validation failure handling

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/configuration.md

Shows how to catch InvalidArgumentException when an unsupported encoding is passed. The example falls back to a safe default escaper.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\InvalidArgumentException;

try {
    new Escaper('not-an-encoding');
} catch (InvalidArgumentException $e) {
    // configuration error — fall back to safe default
    $escaper = new Escaper();
}
```

--------------------------------

### Basic escapeJs() usage

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Basic example of escaping a JavaScript string with the Laminas Escaper. The output begins with 'bar\x26quot\x3B\x3B\x20alert\x28...' and is safe from XSS.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

$input = 'bar&quot;; alert(&quot;Meow!&quot;); var xss=&quot;true';
// result begins with: bar\x26quot\x3B\x3B\x20alert\x28...  (safe from XSS)
echo $escaper->escapeJs($input);
```

--------------------------------

### Instance-based escaping with Laminas Escaper

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/index.md

Create an Escaper instance with an optional encoding and call context-specific methods for HTML, attributes, JavaScript, CSS, and URLs. The example uses UTF-8 encoding and demonstrates each method with a comment indicating the context.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

echo $escaper->escapeHtml($_POST['name']);      // HTML body context
echo $escaper->escapeHtmlAttr($_POST['title']); // HTML attribute context
echo $escaper->escapeJs($jsonFragment);         // JavaScript literal context
echo $escaper->escapeCss($styleValue);          // CSS context
echo $escaper->escapeUrl($queryPart);           // URL / URI parameter context
```

--------------------------------

### Basic escapeHtmlAttr() usage example

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Escapes a string for use in an HTML attribute context. The output shows the escaped value with special characters converted to hexadecimal entities.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

$input = "faketitle onmouseover=alert(/Laminas!/);";
echo $escaper->escapeHtmlAttr($input);
// faketitle&#x20;onmouseover&#x3D;alert&#x28;&#x2F;Laminas&#x21;&#x2F;&#x29;&#x3B;
```

--------------------------------

### Bad HTML escaping example (encoding mismatch)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-html.md

Incorrect usage: the escaper uses UTF-8 but the document is served as ISO-8859-1, causing encoding mismatch. This example shows the wrong way to set encodings.

```php
<?php
$input = '<script>alert("laminas")</script>';
$escaper = new Laminas\Escaper\Escaper('utf-8');
?>
<?php header('Content-Type: text/html; charset=ISO-8859-1'); ?>
<!DOCTYPE html>
<html>
<head>
    <title>Encodings set incorrectly!</title>
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
</head>
<body>
<?php
    // Bad! The escaper's and the document's encodings are different!
    echo $escaper->escapeHtml($input);
?>
</body>
```

--------------------------------

### Escaping in a non-UTF-8 encoding

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/configuration.md

Example of using the escaper with a Latin-1 document. The input is converted to/from UTF-8 internally for escapeHtmlAttr(). The document must use the same encoding as the escaper instance.

```php
use Laminas\Escaper\Escaper;

// Latin-1 document
header('Content-Type: text/html; charset=ISO-8859-1');
$escaper = new Escaper('iso-8859-1');

$input = "Caf" . chr(0xE9);        // "Café" in Latin-1
echo $escaper->escapeHtmlAttr($input);
// Caf&#xE9;  (internally converted to/from UTF-8)
echo $escaper->getEncoding();      // iso-8859-1
```

--------------------------------

### Catch InvalidArgumentException from Escaper constructor

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Example of catching InvalidArgumentException when constructing an Escaper with a blank or unsupported encoding. The constructor throws for blank encoding or encodings not in $supportedEncodings.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\InvalidArgumentException;

try {
    $escaper = new Escaper(''); // or: new Escaper('utf-16')
} catch (InvalidArgumentException $e) {
    printf('Invalid escaper configuration: %s', $e->getMessage());
}
```

--------------------------------

### Bad URL escaping example (XSS vulnerability)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-url.md

Shows an unescaped URL insertion that allows XSS attacks. The input contains a malicious onmouseover attribute that would be executed if not escaped.

```php
<?php header('Content-Type: application/xhtml+xml; charset=UTF-8'); ?>
<!DOCTYPE html>
<?php
$input = <<<INPUT
" onmouseover="alert('laminas')
INPUT;
?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Unescaped URL data</title>
    <meta charset="UTF-8"/>
</head>
<body>
    <a href="http://example.com/?name=<?= $input ?>">Click here!</a>
</body>
</html>
```

--------------------------------

### Catching RuntimeException from escapeHtmlAttr

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Example of catching RuntimeException when escapeHtmlAttr receives malformed UTF-8. The exception message is 'String to be escaped was not valid UTF-8 or could not be converted: ...'. The code fails closed by setting $escaped to an empty string.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    $escaped = $escaper->escapeHtmlAttr("\xC3\x28"); // malformed UTF-8
} catch (RuntimeException $e) {
    // "String to be escaped was not valid UTF-8 or could not be converted: ..."
    $escaped = ''; // fail closed: emit nothing
}
```

--------------------------------

### Bad CSS escaping example

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-css.md

Shows an XSS vulnerability when user-controlled CSS is inserted without escaping. The input contains a closing style tag and script, allowing an attacker to execute arbitrary JavaScript.

```php
<?php header('Content-Type: application/xhtml+xml; charset=UTF-8'); ?>
<!DOCTYPE html>
<?php
$input = <<<INPUT
body {
    background-image: url('http://example.com/foo.jpg?</style><script>alert(1)</script>');
}
INPUT;
?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Unescaped CSS</title>
    <meta charset="UTF-8"/>
    <style>
    <?= $input ?>
    </style>
</head>
<body>
    <p>User controlled CSS needs to be properly escaped!</p>
</body>
</html>
```

--------------------------------

### Bad Javascript Escaping using json_encode()

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-javascript.md

Shows incorrect escaping for the Javascript context using json_encode(), which leaves the data vulnerable to XSS. The example results in an alert popup when the page loads because the data is not properly escaped.

```php
<?php header('Content-Type: application/xhtml+xml; charset=UTF-8'); ?>
<!DOCTYPE html>
<?php
$input = <<<INPUT
bar&quot;; alert(&quot;Meow!&quot;); var xss=&quot;true
INPUT;

$output = json_encode($input);
?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Unescaped Entities</title>
    <meta charset="UTF-8"/>
    <script type="text/javascript">
        <?php
        // this will result in
        // var foo = "bar&quot;; alert(&quot;Meow!&quot;); var xss=&quot;true";
        ?>
        var foo = <?= $output ?>;
    </script>
</head>
<body>
    <p>json_encode() is not good for escaping javascript!</p>
</body>
</html>
```

--------------------------------

### Import EscaperInterface

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Import the EscaperInterface at the top-level Laminas\Escaper namespace.

```php
use Laminas\Escaper\EscaperInterface;
```

--------------------------------

### Basic Constructor Usage

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Creates Escaper instances with default and custom encodings. Encoding is case-insensitive and stored lowercased.

```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper();          // defaults to utf-8
$latin1  = new Escaper('iso-8859-1');
$same    = new Escaper('UTF-8');   // case-insensitive, stored as 'utf-8'
var_dump($same->getEncoding());    // string(5) "utf-8"
```

--------------------------------

### Dispatch contextually with match on escape methods

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Demonstrates a function that selects the appropriate escape method based on a context string. It uses match to call escapeHtml, escapeHtmlAttr, escapeJs, escapeCss, or escapeUrl.

```php
use Laminas\Escaper\EscaperInterface;

function emitContextual(EscaperInterface $escaper, string $context, string $value): string
{
    return match ($context) {
        'html'      => $escaper->escapeHtml($value),
        'attribute' => $escaper->escapeHtmlAttr($value),
        'js'        => $escaper->escapeJs($value),
        'css'       => $escaper->escapeCss($value),
        'url'       => $escaper->escapeUrl($value),
    };
}
```

--------------------------------

### Constructor Signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Shows the constructor signature with an optional encoding parameter. Throws InvalidArgumentException for blank or unsupported encodings.

```php
/**
 * Constructor: Single parameter allows setting of global encoding for use by
 * the current object.
 *
 * @param non-empty-string|null $encoding
 * @throws Exception\InvalidArgumentException
 */
public function __construct(?string $encoding = null)
```

--------------------------------

### Type-hint against EscaperInterface in a class constructor

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Shows how to accept an escaper via constructor injection using the EscaperInterface type. The renderName method uses escapeHtml to safely emit a name into an HTML body context.

```php
use Laminas\Escaper\EscaperInterface;

final class TemplateRenderer
{
    public function __construct(private EscaperInterface $escaper)
    {
    }

    public function renderName(string $name): string
    {
        // emit safely into an HTML body context
        return sprintf('<div>%s</div>', $this->escaper->escapeHtml($name));
    }
}
```

--------------------------------

### escapeCss() error handling

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Catches RuntimeException when escapeCss() cannot convert input to valid UTF-8, falling back to an empty string.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    $style = $escaper->escapeCss($userProvidedCss);
} catch (RuntimeException $e) {
    $style = ''; // refuse to emit invalid data
}
```

--------------------------------

### getEncoding() method signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Returns the encoding configured at construction time, in lowercased form. Defaults to 'utf-8'.

```php
/**
 * Return the encoding that all output/input is expected to be encoded in.
 *
 * @return non-empty-string
 */
public function getEncoding()
```

--------------------------------

### Import ExceptionInterface

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Import path for the Laminas\Escaper\Exception\ExceptionInterface marker interface.

```php
use Laminas\Escaper\Exception\ExceptionInterface;
```

--------------------------------

### Constructor Error Handling

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Catches InvalidArgumentException when an unsupported encoding is passed. The error message includes the invalid encoding value.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\InvalidArgumentException;

try {
    $escaper = new Escaper('klingon');
} catch (InvalidArgumentException $e) {
    // "Value of 'klingon' passed to Laminas\Escaper\Escaper constructor
    //  parameter is invalid. Provide an encoding supported by htmlspecialchars()"
    echo $e->getMessage();
}
```

--------------------------------

### Escaper::__construct

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/index.md

Constructor for the Escaper class. Initializes the escaper with an optional encoding, defaulting to UTF-8 if not provided.

```APIDOC
## Escaper::__construct

### Description
Constructor for the Escaper class. Initializes the escaper with an optional encoding, defaulting to UTF-8 if not provided.

### Method
__construct

### Signature
`public function __construct(?string $encoding = null)`

### Parameters
- **$encoding** (?string) - Optional - The character encoding to use. If null, defaults to UTF-8.

### Return Type
void
```

--------------------------------

### Escaping the same string in different HTML contexts

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/theory-of-operation.md

Shows how the same input string is escaped differently by each escaper method: escapeHtml, escapeHtmlAttr, escapeJs, escapeCss, and escapeUrl. Each method applies context-specific OWASP rules and returns the escaped output as shown in the comments.

```php
$escaper = new Laminas\Escaper\Escaper('utf-8');

// &lt;script&gt;alert(&quot;laminas&quot;)&lt;/script&gt;
echo $escaper->escapeHtml('<script>alert("laminas")</script>');

// &lt;script&gt;alert&#x28;&quot;laminas&quot;&#x29;&lt;&#x2F;script&gt;
echo $escaper->escapeHtmlAttr('<script>alert("laminas")</script>');

// \x3Cscript\x3Ealert\x28\x22laminas\x22\x29\x3C\x2Fscript\x3E
echo $escaper->escapeJs('<script>alert("laminas")</script>');

// \3C script\3E alert\28 \22 laminas\22 \29 \3C \2F script\3E
echo $escaper->escapeCss('<script>alert("laminas")</script>');

// %3Cscript%3Ealert%28%22laminas%22%29%3C%2Fscript%3E
echo $escaper->escapeUrl('<script>alert("laminas")</script>');
```

--------------------------------

### Constructor encoding option usage

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/configuration.md

Shows how to instantiate Laminas\Escaper\Escaper with different encodings. The $encoding parameter is optional, defaults to 'utf-8', and is case-insensitive (stored lowercased). Invalid encodings throw InvalidArgumentException.

```php
use Laminas\Escaper\Escaper;

$default = new Escaper();          // utf-8
$latin1  = new Escaper('iso-8859-1');
$caseIns = new Escaper('UTF-8');   // accepted; stored as 'utf-8'
```

--------------------------------

### EscaperInterface signature with five escaping methods

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Defines the contract for context-specific escaping methods: escapeHtml, escapeHtmlAttr, escapeJs, escapeUrl, and escapeCss. Each method returns non-empty-string when the input is non-empty-string.

```php
/**
 * Interface for context specific methods for use in secure output escaping
 */
interface EscaperInterface
{
    /**
     * Escape a string for the HTML Body context where there are very few characters
     * of special meaning. Internally this will use htmlspecialchars().
     *
     * @return ($string is non-empty-string ? non-empty-string : string)
     */
    public function escapeHtml(string $string);

    /**
     * Escape a string for the HTML Attribute context. We use an extended set of characters
     * to escape that are not covered by htmlspecialchars() to cover cases where an attribute
     * might be unquoted or quoted illegally (e.g. backticks are valid quotes for IE).
     *
     * @return ($string is non-empty-string ? non-empty-string : string)
     */
    public function escapeHtmlAttr(string $string);

    /**
     * Escape a string for the Javascript context. This does not use json_encode(). An extended
     * set of characters are escaped beyond ECMAScript's rules for Javascript literal string
     * escaping in order to prevent misinterpretation of Javascript as HTML leading to the
     * injection of special characters and entities. The escaping used should be tolerant
     * of cases where HTML escaping was not applied on top of Javascript escaping correctly.
     * Backslash escaping is not used as it still leaves the escaped character as-is and so
     * is not useful in a HTML context.
     *
     * @return ($string is non-empty-string ? non-empty-string : string)
     */
    public function escapeJs(string $string);

    /**
     * Escape a string for the URI or Parameter contexts. This should not be used to escape
     * an entire URI - only a subcomponent being inserted. The function is a simple proxy
     * to rawurlencode() which now implements RFC 3986 since PHP 5.3 completely.
     *
     * @return ($string is non-empty-string ? non-empty-string : string)
     */
    public function escapeUrl(string $string);

    /**
     * Escape a string for the CSS context. CSS escaping can be applied to any string being
     * inserted into CSS and escapes everything except alphanumerics.
     *
     * @return ($string is non-empty-string ? non-empty-string : string)
     */
    public function escapeCss(string $string);
}
```

--------------------------------

### escapeHtml(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the HTML Body context. Internally uses htmlspecialchars(). Returns the escaped string.

```APIDOC
## escapeHtml(string $string)

### Description
Escapes for the HTML Body context; internally uses `htmlspecialchars()`.

### Method
`escapeHtml`

### Parameters
- **$string** (string) - Required - The raw (unescaped) data to escape

### Return
- **string** - The escaped string. Psalm conditional return type: `($string is non-empty-string ? non-empty-string : string)` — empty input guarantees empty output, non-empty input guarantees non-empty output.

### Source
`src/EscaperInterface.php:18`
```

--------------------------------

### escapeHtmlAttr() error handling for invalid UTF-8

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Shows how to catch a RuntimeException when the input is not valid UTF-8. The error message is logged via error_log().

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    echo $escaper->escapeHtmlAttr("\xC3\x28"); // invalid UTF-8 sequence
} catch (RuntimeException $e) {
    // "String to be escaped was not valid UTF-8 or could not be converted: ..."
    error_log($e->getMessage());
}
```

--------------------------------

### Import RuntimeException class

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Import the Laminas Escaper RuntimeException exception class for use in your code.

```php
use Laminas\Escaper\Exception\RuntimeException;
```

--------------------------------

### escapeHtml(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the HTML Body context. Internally uses htmlspecialchars(). Returns a non-empty string if the input is non-empty.

```APIDOC
## escapeHtml(string $string)

### Description
Escapes a string for the HTML Body context where there are very few characters of special meaning. Internally this will use htmlspecialchars().

### Method
`escapeHtml`

### Parameters
- **$string** (string) - Required - The string to escape.

### Return Value
- (string) - The escaped string. Returns non-empty-string if input is non-empty-string.

```

--------------------------------

### escapeUrl(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the URI or Parameter contexts. Should not be used to escape an entire URI, only a subcomponent. A simple proxy to rawurlencode() which implements RFC 3986.

```APIDOC
## escapeUrl(string $string)

### Description
Escape a string for the URI or Parameter contexts. This should not be used to escape an entire URI - only a subcomponent being inserted. The function is a simple proxy to rawurlencode() which now implements RFC 3986 since PHP 5.3 completely.

### Method
`escapeUrl`

### Parameters
- **$string** (string) - Required - The string to escape.

### Return Value
- (string) - The escaped string. Returns non-empty-string if input is non-empty-string.

```

--------------------------------

### escapeCss(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the CSS context. Escapes everything except alphanumerics. Returns the escaped string.

```APIDOC
## escapeCss(string $string)

### Description
Escapes for the CSS context; escapes everything except alphanumerics.

### Method
`escapeCss`

### Parameters
- **$string** (string) - Required - The raw (unescaped) data to escape

### Return
- **string** - The escaped string. Psalm conditional return type: `($string is non-empty-string ? non-empty-string : string)` — empty input guarantees empty output, non-empty input guarantees non-empty output.

### Source
`src/EscaperInterface.php:57`
```

--------------------------------

### Import InvalidArgumentException

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Import path for the Laminas\Escaper\Exception\InvalidArgumentException class.

```php
use Laminas\Escaper\Exception\InvalidArgumentException;
```

--------------------------------

### escapeUrl(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for URI / Parameter contexts. Acts as a proxy to rawurlencode() (RFC 3986); not for escaping entire URIs. Returns the escaped string.

```APIDOC
## escapeUrl(string $string)

### Description
Escapes for URI / Parameter contexts; proxy to `rawurlencode()` (RFC 3986); not for escaping entire URIs.

### Method
`escapeUrl`

### Parameters
- **$string** (string) - Required - The raw (unescaped) data to escape

### Return
- **string** - The escaped string. Psalm conditional return type: `($string is non-empty-string ? non-empty-string : string)` — empty input guarantees empty output, non-empty input guarantees non-empty output.

### Source
`src/EscaperInterface.php:49`
```

--------------------------------

### escapeUrl() signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Method signature for escapeUrl() from src/Escaper.php:215.

```php
/** @inheritDoc */
public function escapeUrl(string $string)
```

--------------------------------

### Import Laminas Escaper class

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Import the Escaper class for use in your PHP code. This is the standard import statement for the Laminas Escaper library.

```php
use Laminas\Escaper\Escaper;
```

--------------------------------

### escapeJs()

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Escapes a string for safe inclusion in a JavaScript string literal context. This method converts the input to UTF-8, escapes all characters except alphanumerics and a few safe punctuation marks, and returns the escaped string.

```APIDOC
## `escapeJs()`

### Description
Escapes a string for safe inclusion in a JavaScript string literal context. This method converts the input to UTF-8, escapes all characters except alphanumerics and a few safe punctuation marks, and returns the escaped string.

### Method
`escapeJs`

### Signature
```php
public function escapeJs(string $string)
```

### Parameters
- `$string` (string) - Required - Data to escape for the JavaScript string-literal context

### Return Value
`string`: the escaped JavaScript string content. Escapes everything except `a-zA-Z0-9 , . _` (empty / digits-only strings are returned unchanged).

### Behavior
1. Converts the input to UTF-8 (`toUtf8()`); throws `RuntimeException` on invalid UTF-8.
2. Returns early if the string is `''` or `ctype_digit($string)`.
3. Matches `/[^a-z0-9,._]/iu` and replaces via `jsMatcher()`:
   - Single-byte characters → `\x%02X` (e.g. `<` → `\x3C`, `\0` → `\x00`, `' '` → `\x20`).
   - Multi-byte characters are converted to UTF-16BE; ≤ 4 hex digits → `\u%04s` (e.g. `Ā` → `\u0100`); longer values → a surrogate pair `\u%04s\u%04s` (e.g. U+10000 → `\uD800\uDC00`).
4. Converts back from UTF-8 to the configured encoding.

This method deliberately does **not** use `json_encode()`; it extends the ECMAScript/JSON escaping rules with HTML special characters (`<` → `\x3C`, `>` → `\x3E`, `&` → `\x26`, etc.) to prevent HTML-entity injection.

### Throws
- `Laminas\Escaper\Exception\RuntimeException` - Input cannot be converted to valid UTF-8

### Examples
Basic:
```php
use Laminas\Escaper\Escaper;

$escaper = new Escaper('utf-8');

$input = 'bar&quot;; alert(&quot;Meow!&quot;); var xss=&quot;true';
// result begins with: bar\x26quot\x3B\x3B\x20alert\x28...  (safe from XSS)
echo $escaper->escapeJs($input);
```

Error handling (catch conversion failure):
```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    $safe = $escaper->escapeJs($userInput);
} catch (RuntimeException $e) {
    // treat as invalid input — do not emit
    $safe = '';
}
```
```

--------------------------------

### escapeHtml() method signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Escapes a string for the HTML body context. Internally uses htmlspecialchars with ENT_QUOTES | ENT_SUBSTITUTE.

```php
/** @inheritDoc */
public function escapeHtml(string $string)
```

--------------------------------

### Catch Escaper exceptions in consumer code

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/errors.md

Shows how to catch exceptions thrown by Laminas\Escaper\Escaper methods and constructor. The first try block catches RuntimeException for invalid UTF-8 data and ExceptionInterface for other library failures. The second try block catches InvalidArgumentException during construction to fall back to default encoding.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\ExceptionInterface;
use Laminas\Escaper\Exception\InvalidArgumentException;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    echo $escaper->escapeHtmlAttr($userInput);
} catch (RuntimeException $e) {        // invalid UTF-8 data
    echo '<!-- invalid input suppressed -->';
} catch (ExceptionInterface $e) {      // any other library failure (currently only InvalidArgumentException)
    error_log($e->getMessage());
}

// Configuration errors are best caught at construction time:
try {
    $configured = new Escaper(getenv('APP_ENCODING') ?: 'utf-8');
} catch (InvalidArgumentException $e) {
    $configured = new Escaper(); // fall back to the default
}
```

--------------------------------

### escapeCss() signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Method signature for escapeCss() from src/Escaper.php:221.

```php
/** @inheritDoc */
public function escapeCss(string $string)
```

--------------------------------

### Catch all laminas-escaper exceptions with ExceptionInterface

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Shows catching any laminas-escaper failure using the marker interface. Catches both InvalidArgumentException and RuntimeException.

```php
use Laminas\Escaper\Exception\ExceptionInterface;

try {
    $escaper = new Laminas\Escaper\Escaper('utf-8');
    echo $escaper->escapeJs($input);
} catch (ExceptionInterface $e) {
    // catches both InvalidArgumentException and RuntimeException
    log($e);
}
```

--------------------------------

### escapeJs() method signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

The signature of the escapeJs() method as defined in src/Escaper.php:201. It accepts a string and returns the escaped JavaScript string content.

```php
/** @inheritDoc */
public function escapeJs(string $string)
```

--------------------------------

### Basic HTML escaping with escapeHtml()

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-html.md

Use Laminas\Escaper\Escaper's escapeHtml() method to safely output user-provided input in an HTML body context. It internally uses PHP's htmlspecialchars() with correct flags and encoding. The document's encoding must match the escaper's encoding.

```php
// Outputting this without escaping would be a bad idea!
$input = '<script>alert("laminas")</script>';

$escaper = new Laminas\Escaper\Escaper('utf-8');

// somewhere in an HTML template
<div class="user-provided-input">
    <?= $escaper->escapeHtml($input) // all safe! ?>
</div>
```

--------------------------------

### ExceptionInterface definition

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/types.md

Marker interface for all exceptions thrown by the library. Extends Throwable and is implemented by InvalidArgumentException and RuntimeException.

```php
interface ExceptionInterface extends Throwable
{
}
```

--------------------------------

### ExceptionInterface signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Verbatim signature of the marker interface extending Throwable. All laminas-escaper exceptions implement it.

```php
use Throwable;

interface ExceptionInterface extends Throwable
{
}
```

--------------------------------

### escapeJs(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the Javascript context. Does not use json_encode(). Escapes an extended set of characters beyond ECMAScript's rules to prevent misinterpretation of Javascript as HTML.

```APIDOC
## escapeJs(string $string)

### Description
Escape a string for the Javascript context. This does not use json_encode(). An extended set of characters are escaped beyond ECMAScript's rules for Javascript literal string escaping in order to prevent misinterpretation of Javascript as HTML leading to the injection of special characters and entities. The escaping used should be tolerant of cases where HTML escaping was not applied on top of Javascript escaping correctly. Backslash escaping is not used as it still leaves the escaped character as-is and so is not useful in a HTML context.

### Method
`escapeJs`

### Parameters
- **$string** (string) - Required - The string to escape.

### Return Value
- (string) - The escaped string. Returns non-empty-string if input is non-empty-string.

```

--------------------------------

### Laminas\Escaper\Exception\ExceptionInterface

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

Marker interface implemented by all exceptions thrown by the laminas-escaper library. Extends PHP's built-in Throwable interface. Allows consumers to catch all laminas-escaper failures with a single type.

```APIDOC
## Interface: Laminas\Escaper\Exception\ExceptionInterface

### Description
Marker interface that all exceptions thrown by the library implement. Extends PHP's built-in `Throwable` interface.

### Import Path
```php
use Laminas\Escaper\Exception\ExceptionInterface;
```

### Signature
```php
use Throwable;

interface ExceptionInterface extends Throwable
{
}
```

### Usage Example
```php
use Laminas\Escaper\Exception\ExceptionInterface;

try {
    $escaper = new Laminas\Escaper\Escaper('utf-8');
    echo $escaper->escapeJs($input);
} catch (ExceptionInterface $e) {
    // catches both InvalidArgumentException and RuntimeException
    log($e);
}
```
```

--------------------------------

### escapeJs(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the Javascript context. Does not use json_encode(); extends ECMAScript literal-string escaping without backslash escaping. Returns the escaped string.

```APIDOC
## escapeJs(string $string)

### Description
Escapes for the Javascript context; does **not** use `json_encode()`; extends ECMAScript literal-string escaping; no backslash escaping.

### Method
`escapeJs`

### Parameters
- **$string** (string) - Required - The raw (unescaped) data to escape

### Return
- **string** - The escaped string. Psalm conditional return type: `($string is non-empty-string ? non-empty-string : string)` — empty input guarantees empty output, non-empty input guarantees non-empty output.

### Source
`src/EscaperInterface.php:40`
```

--------------------------------

### Escaper::getEncoding

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/index.md

Returns the current encoding used by the escaper. This is useful for verifying the configured encoding.

```APIDOC
## Escaper::getEncoding

### Description
Returns the current encoding used by the escaper. This is useful for verifying the configured encoding.

### Method
getEncoding

### Signature
`public function getEncoding(): string`

### Parameters
None

### Return Type
string - The current encoding.
```

--------------------------------

### escapeUrl() in a link query string

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Uses escapeUrl() to safely insert a user-supplied query parameter into an HTML href attribute.

```php
$escaper = new Escaper('utf-8');
$name    = $_GET['name'] ?? '';
?>
<a href="http://example.com/?name=<?= $escaper->escapeUrl($name) ?>">Click here!</a>
```

--------------------------------

### Good Javascript Escaping using escapeJs()

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/docs/book/escaping-javascript.md

Shows correct escaping for the Javascript context using Laminas\Escaper\Escaper::escapeJs(). The output escapes dangerous characters as hexadecimal or unicode escapes, preventing XSS attacks. The Javascript parser may report a SyntaxError, but the application remains safe.

```php
<?php header('Content-Type: text/html; charset=UTF-8'); ?>
<!DOCTYPE html>
<?php
$input = <<<INPUT
bar&quot;; alert(&quot;Meow!&quot;); var xss=&quot;true
INPUT;

$escaper = new Laminas\Escaper\Escaper('utf-8');
$output = $escaper->escapeJs($input);
?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Escaped Entities</title>
    <meta charset="UTF-8"/>
    <script type="text/javascript">
        <?php
        // this will look like
        // var foo =
bar\x26quot\x3B\x3B\x20alert\x28\x26quot\x3BMeow\x21\x26quot\x3B\x29\x3B\x20var\x20xss\x3D\x26quot\x3Btrue;
        ?>
        var foo = <?= $output ?>;
    </script>
</head>
<body>
    <p>Laminas\Escaper\Escaper::escapeJs() is good for escaping javascript!</p>
</body>
</html>
```

--------------------------------

### Catch RuntimeException for invalid UTF-8 input

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/errors.md

Thrown when escapeJs (or other context methods) receive a non-empty string that fails UTF-8 validation. Catch RuntimeException or ExceptionInterface.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    $escaper->escapeJs("\xFF");           // malformed UTF-8 byte
} catch (RuntimeException $e) {
    // "String to be escaped was not valid UTF-8 or could not be converted: ..."
}
```

--------------------------------

### escapeHtmlAttr() method signature

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

Signature of the escapeHtmlAttr() method from src/Escaper.php:187. It accepts a string and returns the escaped attribute value.

```php
/** @inheritDoc */
public function escapeHtmlAttr(string $string)
```

--------------------------------

### Catch InvalidArgumentException for blank encoding

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/errors.md

Thrown when constructing Escaper with an empty string encoding. Catch either InvalidArgumentException or the marker interface ExceptionInterface.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\InvalidArgumentException;

try {
    new Escaper('');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(); // ... does not allow a blank value
}
```

--------------------------------

### escapeHtmlAttr(), escapeJs(), escapeCss() - Invalid UTF-8 Input

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/errors.md

Throws RuntimeException when the input string is not valid UTF-8 or cannot be converted. This occurs in the escape methods for attribute, JavaScript, and CSS contexts.

```APIDOC
## [METHOD] escapeHtmlAttr(), escapeJs(), escapeCss()

### Description
Throws RuntimeException when the input string is not valid UTF-8 or cannot be converted. This occurs in the escape methods for attribute, JavaScript, and CSS contexts.

### Method
Escape methods

### Endpoint
`$escaper->escapeHtmlAttr($string)`, `$escaper->escapeJs($string)`, `$escaper->escapeCss($string)`

### Parameters
#### Method Parameters
- **$string** (string) - Required - The input string to escape; must be valid UTF-8.

### Request Example
```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\RuntimeException;

$escaper = new Escaper('utf-8');

try {
    $escaper->escapeJs("\xFF");           // malformed UTF-8 byte
} catch (RuntimeException $e) {
    // "String to be escaped was not valid UTF-8 or could not be converted: ..."
}
```

### Response
#### Exception Thrown
- **RuntimeException** - Thrown when the input is not valid UTF-8 or cannot be converted.

#### Exception Message
`String to be escaped was not valid UTF-8 or could not be converted: <result>`

```

--------------------------------

### escapeHtmlAttr(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the HTML Attribute context. Uses an extended escape set beyond htmlspecialchars() for unquoted or illegally quoted attributes. Returns the escaped string.

```APIDOC
## escapeHtmlAttr(string $string)

### Description
Escapes for the HTML Attribute context; extended escape set beyond `htmlspecialchars()` for unquoted/illegally quoted attributes.

### Method
`escapeHtmlAttr`

### Parameters
- **$string** (string) - Required - The raw (unescaped) data to escape

### Return
- **string** - The escaped string. Psalm conditional return type: `($string is non-empty-string ? non-empty-string : string)` — empty input guarantees empty output, non-empty input guarantees non-empty output.

### Source
`src/EscaperInterface.php:27`
```

--------------------------------

### Catch InvalidArgumentException for unsupported encoding

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/errors.md

Thrown when the encoding is not in the supported list after lowercasing. Note that 'UTF-8' is valid but 'utf-16' is not.

```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\InvalidArgumentException;

try {
    new Escaper('utf-16'); // not in the supported list
} catch (InvalidArgumentException $e) {
    // "Value of 'utf-16' passed to Laminas\Escaper\Escaper constructor
    //  parameter is invalid. Provide an encoding supported by htmlspecialchars()"
}
```

--------------------------------

### new Escaper('') - Blank Encoding

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/errors.md

Throws InvalidArgumentException when a blank encoding is passed to the Escaper constructor. The exception message indicates that the constructor parameter does not allow a blank value.

```APIDOC
## [CONSTRUCTOR] new Escaper('')

### Description
Throws InvalidArgumentException when a blank encoding is passed to the Escaper constructor. The exception message indicates that the constructor parameter does not allow a blank value.

### Method
Constructor

### Endpoint
`new Escaper($encoding)`

### Parameters
#### Constructor Parameters
- **$encoding** (string) - Required - The encoding to use; must not be blank.

### Request Example
```php
use Laminas\Escaper\Escaper;
use Laminas\Escaper\Exception\InvalidArgumentException;

try {
    new Escaper('');
} catch (InvalidArgumentException $e) {
    echo $e->getMessage(); // ... does not allow a blank value
}
```

### Response
#### Exception Thrown
- **InvalidArgumentException** - Thrown when the encoding is blank.

#### Exception Message
`Laminas\Escaper\Escaper constructor parameter does not allow a blank value`

```

--------------------------------

### escapeHtmlAttr(string $string)

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper-interface.md

Escapes a string for the HTML Attribute context. Uses an extended set of characters beyond htmlspecialchars() to cover cases where an attribute might be unquoted or quoted illegally.

```APIDOC
## escapeHtmlAttr(string $string)

### Description
Escape a string for the HTML Attribute context. We use an extended set of characters to escape that are not covered by htmlspecialchars() to cover cases where an attribute might be unquoted or quoted illegally (e.g. backticks are valid quotes for IE).

### Method
`escapeHtmlAttr`

### Parameters
- **$string** (string) - Required - The string to escape.

### Return Value
- (string) - The escaped string. Returns non-empty-string if input is non-empty-string.

```

--------------------------------

### RuntimeException class definition

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/exceptions.md

The RuntimeException class extends the PHP built-in \RuntimeException and implements ExceptionInterface. It declares no additional members.

```php
/**
 * Invalid argument exception
 */
class RuntimeException extends \RuntimeException implements
    ExceptionInterface
{
}
```

--------------------------------

### Escaper class signature with @final annotation

Source: https://github.com/laminas/laminas-escaper/blob/2.19.x/_autodocs/api-reference/escaper.md

The class signature for Laminas\Escaper\Escaper. It is annotated @final and implements EscaperInterface. This is the class declaration as shown in the source.

```php
/**
 * Context specific methods for use in secure output escaping
 *
 * @final
 */
class Escaper implements EscaperInterface
```
Tokens:
Raw