Luminova Framework

User Input Escaper

Last updated: 2024-08-07 20:17:24

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:

ParameterTypeDescription
$encodingstring|nullThe character encoding to use (default: 'utf-8').

Throws:


__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:

ParameterTypeDescription
$namestringThe name of the method being called.
$argumentsarrayThe arguments passed to the method.

Return Value:

mixed - Return the result of the method call.

Throws:


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:

ParameterTypeDescription
$encodingstringThe character encoding to use (e.g: 'utf-8').

Return Value

Luminova\Functions\Escape Return instance of escape class.

Throws:


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:

ParameterTypeDescription
$stringstringThe string to be escaped.

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:

ParameterTypeDescription
$stringstringThe string to be escaped.

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:

ParameterTypeDescription
$stringarray|stringThe string or array of strings to be escaped.

Return Value:

string - The escaped string or array of strings.


escapeCss

Escape CSS special characters.

protected escapeCss(string $string): string

Parameters:

ParameterTypeDescription
$stringstringThe string to be escaped.

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:

ParameterTypeDescription
$stringstringThe URL to be escaped.

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:

ParameterTypeDescription
$stringstringThe URL to be escaped.
$rulesarray<string,string>An associative array where keys are patterns and values are replacements.

Return Value:

string - Return the escaped string.


toUtf8

Convert a string to UTF-8 encoding.

protected toUtf8(string $string): string

Parameters:

ParameterTypeDescription
$stringstringThe string to be converted.

Return Value:

string - Return the converted string.

Throws:


fromUtf8

Convert a string from UTF-8 encoding.

protected fromUtf8(string $string): string

Parameters:

ParameterTypeDescription
$stringstringThe string to be converted.

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:

ParameterTypeDescription
$stringarray|stringThe string or array of strings to be converted.
$tostringThe target character encoding.
$fromarray|string|nullThe source character encoding. Defaults to null (auto-detection).

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.

TypeDescription
iso-8859-1ISO 8859-1 Latin-1 (Western European)
iso8859-1Alternative notation for ISO 8859-1
iso-8859-5ISO 8859-5 Latin/Cyrillic
iso8859-5Alternative notation for ISO 8859-5
iso-8859-15ISO 8859-15 Latin-9 (Western European with Euro)
iso8859-15Alternative notation for ISO 8859-15
utf-8Unicode Transformation Format - 8 bits
cp866Code Page 866 (Cyrillic)
ibm866IBM Code Page 866 (Cyrillic)
866Alternative notation for Code Page 866
cp1251Code Page 1251 (Cyrillic)
windows-1251Windows Code Page 1251 (Cyrillic)
win-1251Alternative notation for Windows Code Page 1251
1251Alternative notation for Code Page 1251
cp1252Code Page 1252 (Western European)
windows-1252Windows Code Page 1252 (Western European)
1252Alternative notation for Code Page 1252
koi8-rKOI8-R (Cyrillic)
koi8-ruKOI8-RU (Cyrillic)
koi8rAlternative notation for KOI8-R
big5Big5 (Traditional Chinese)
950Alternative notation for Big5
gb2312GB 2312 (Simplified Chinese)
936Alternative notation for GB 2312
big5-hkscsBig5-HKSCS (Traditional Chinese with Hong Kong Supplementary Character Set)
shift_jisShift JIS (Japanese)
sjisAlternative notation for Shift JIS
sjis-winShift JIS (Japanese) for Windows
cp932Code Page 932 (Japanese)
932Alternative notation for Code Page 932
euc-jpEUC-JP (Japanese)
eucjpAlternative notation for EUC-JP
eucjp-winEUC-JP (Japanese) for Windows
macromanMacRoman (Western European)