User Input Escaper

The Escape class is designed to provide a useful set of methods for escaping and sanitizing data. This ensures that input data is safe to use in HTML, JavaScript, URLs, and other contexts where untrusted input could potentially lead to security vulnerabilities, such as Cross-Site Scripting (XSS) attacks.

Features

• HTML Escaping: Prevents HTML injection attacks by escaping characters that could be interpreted as HTML tags or attributes.
• JavaScript Escaping: Escapes characters that might be interpreted as JavaScript code, ensuring that data is safely embedded in scripts.
• URL Escaping: Encodes special characters in URLs to ensure they are correctly transmitted and interpreted.
• Attribute Escaping: Escapes characters in HTML attributes to prevent malicious data injection.
• Custom Escaping: Allows for custom escaping rules and contexts as needed.

Third-Party Libraries

The Escape class also supports integration with third-party libraries such as \Laminas\Escaper\Escaper. To utilize the methods provided by this library, you first need to install it. You can do so by running the following command:

composer require laminas/laminas-escaper

Once installed, whenever you call escape methods, it will use the \Laminas\Escaper\Escaper instead of the built-in Escape class methods for enhanced escaping functionality.

• Class namespace: \Luminova\Functions\Escape

Properties

encoding

The Escaper encoding (default: utf-8).

protected string $encoding = 'utf-8';

encodingFlags

The Escaper encoding flags for special characters to HTML entities (default: ENT_QUOTES|ENT_SUBSTITUTE).

protected int $encodingFlags = ENT_QUOTES | ENT_SUBSTITUTE;

supportedEncodings

The list of supported encodings for escaper.Full supported list can be found below in this documentation.

protected string[] $supportedEncodings = [
    'utf-8',
    //...
]

Methods

More easy approach is to use the global helper function. to escape input which also supports escaping array.

<?php 
echo escape('<script>alert("XSS")</script>');

Or escaping an array.

<?php 
echo escape([
    'html' => '<script>alert("XSS")</script>',
    'js' => 'alert("XSS")'
]);

Initialization

Luminova provide different ways initialize the and use escape class.

<?php 
$escaper = factory()>escaper();

<?php 
$escaper = factory('escaper');

Use the Factory class loader.

<?php 
use Luminova\Application\Factory;

$escaper = Factory::escaper();

Initializing directory.

<?php
use \Luminova\Functions\Escape;

$escaper = new Escape();

Escape HTML special characters.

<?php
echo $escaper->escapeHtml('<script>alert("XSS")</script>');

// Output: &lt;script&gt;alert(&quot;XSS&quot;)&lt;/script&gt;

Escapes JavaScript characters.

<?php
echo $escaper->escapeJs('alert("XSS")');

// Output: alert(&quot;XSS&quot;);

Encodes special characters in a URL.

<?php
echo $escaper->escapeUrl('https://example.com/?search=foo&bar=baz');

// Output: https%3A%2F%2Fexample.com%2F%3Fsearch%3Dfoo%26bar%3Dbaz

Escape HTML attribute values.

<?php
echo $escaper->escapeHtmlAttr('" onmouseover="alert(\'XSS\')"');

// Output: &quot; onmouseover=&quot;alert('XSS')&quot;

Escape with custom patterns.

<?php
echo $escaper->escapeWith('<div>Example</div>', [
    '/</' => '&lt;',
    '/>/' => '&gt;',
]);

// Output: &lt;div&gt;Example&lt;/div&gt;

constructor

Initialize the escaper constructor.

public __construct(string|null $encoding = 'utf-8'): mixed

Parameters:

Throws:

• \Luminova\Exceptions\InvalidArgumentException - Throws if unsupported encoding or empty string is provided.

__call

The magic call method allows you to call methods specifically for third-party PHP escaper class using \Laminas\Escaper\Escaper.

public __call(string $name, array $arguments): mixed

Parameters:

Return Value:

mixed - Return the result of the method call.

Throws:

• \Luminova\Exceptions\BadMethodCallException - When the called method does not exist.

setEncoding

Set escaper encoding type.If set encoding is called when using Laminas Escaper library, new instance of Laminas Escaper will be created.

public setEncoding(string $encoding): self

Parameters:

Return Value

Luminova\Functions\Escape Return instance of escape class.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - Throws if unsupported encoding or empty string is provided.

getEncoding

Get the character encoding used by the escaper.

protected getEncoding(): string

Return Value:

string - Return the character encoding.

escapeHtml

Escapes HTML characters in a string to prevent HTML injection attacks.Converts special characters to their HTML entities.

protected escapeHtml(string $string): string

Parameters:

Return Value:

string - Return the escaped string.

escapeHtmlAttr

Escapes characters in HTML attributes to prevent injection attacks within HTML attributes.

protected escapeHtmlAttr(string $string): string

Parameters:

Return Value:

string - Return the escaped string.

escapeJs

Escapes characters in a string that might be interpreted as JavaScript code.Ensures that data used in JavaScript contexts is safe.

protected escapeJs(array|string $string): string

Parameters:

Return Value:

string - The escaped string or array of strings.

escapeCss

Escape CSS special characters.

protected escapeCss(string $string): string

Parameters:

Return Value:

string - Return the escaped string.

escapeUrl

Encodes special characters in a URL to ensure it is correctly interpreted by browsers and servers.

protected escapeUrl(string $string): string

Parameters:

Return Value:

string - Return the escaped URL.

escapeWith

Applies custom escaping rules to the input string.Allows for flexibility in handling various contexts.

protected escapeWith(string $string, array<string,string> $rules): string

Parameters:

Return Value:

string - Return the escaped string.

toUtf8

Convert a string to UTF-8 encoding.

protected toUtf8(string $string): string

Parameters:

Return Value:

string - Return the converted string.

Throws:

• \Luminova\Exceptions\RuntimeException - When the string is not valid UTF-8 or cannot be converted.

fromUtf8

Convert a string from UTF-8 encoding.

protected fromUtf8(string $string): string

Parameters:

Return Value:

string - Return the converted string.

convertEncoding

Convert a string to a different character encoding.

protected convertEncoding(array|string $string, string $to, array|string|null $from = null): string

Parameters:

Return Value:

string - Return the converted string.

Example Usage

Here’s a practical example demonstrating how to use the Escaper class to safely output user-generated content in different contexts:

<?php
$userInput = '<script>alert("XSS")</script>';

// Safe HTML output
echo $escaper->escapeHtml($userInput);

// Safe JavaScript output
echo $escaper->escapeJs($userInput);

// Safe URL output
echo 'https://example.com/?search=' . $escaper->escapeUrl($userInput);

// Safe HTML attribute output
echo '<input type="text" value="' . $escaper->escapeHtmlAttr($userInput) . '">';

Supported Encodings

The $supportedEncodings array lists the character encodings supported by the system. Each entry represents a specific encoding type that the system can handle.