out()

function out(?string $input, string $output_format = 'html', string $encoding = 'UTF-8'): string

Description

Parameters

Return Value

Output Formats

Example #1: Basic HTML Output

This example demonstrates how the out() function escapes user-generated content to prevent XSS attacks when displaying it in HTML:

Result in the browser (what the user sees):

The dangerous tags are displayed as plain text rather than being interpreted as HTML or JavaScript. Importantly, no alert box appears - the JavaScript is not executed.

The key point to notice, here, is that the JavaScript code does not get executed.

Generated HTML source (viewable via "View Page Source"):

The out() function converts characters like <, >, and & into their corresponding HTML entities, ensuring the content is rendered safely as text.

Example #2: HTML Attribute Output

This example demonstrates how the out() function safely escapes user data when inserting it into HTML attributes, preventing attribute injection attacks:

Result in the browser (what the user sees):

The browser displays the visible content of the div element:

If the 'title' attribute was being used for generating tooltips, hovering over the element would display:

Generated HTML source (viewable via "View Page Source"):

The out() function with the 'attribute' parameter converts special characters like & and " into their HTML entity equivalents (& and "), preventing attackers from breaking out of the attribute context or injecting malicious attributes.

Example #3: XML Output

This example demonstrates how the out() function safely escapes content when generating XML documents, ensuring well-formed and valid XML output:

Result in the browser (what the user sees):

When viewed in a browser that renders XML, the content displays as:

Generated XML source (viewable via "View Page Source"):

The out() function with the 'xml' parameter converts special characters that have meaning in XML into their corresponding entity references. In this example, & becomes & and the apostrophe becomes '. This ensures the XML remains well-formed and parseable by XML processors, preventing syntax errors or data corruption when the XML is consumed by other systems.

Example #4: JSON API Response

This example demonstrates how the out() function safely encodes content when generating JSON responses, preventing XSS attacks in JavaScript contexts and ensuring valid JSON syntax:

Result in the browser (what the user sees):

When this JSON response is received by a client application and parsed, the message value would be:

Importantly, the dangerous script tags are treated as plain text data, not executable code.

Generated JSON source (viewable via "View Page Source" or network inspector):

The out() function with the 'json' parameter uses JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, and JSON_HEX_QUOT flags to convert potentially dangerous characters into their Unicode escape sequences. In this example, < becomes \u003C, > becomes \u003E, and quotes are properly escaped. This prevents XSS attacks when the JSON is embedded in HTML or processed by JavaScript, while maintaining valid JSON syntax that can be safely parsed by any JSON decoder.

Example #5: Embedding JSON in HTML

This example demonstrates how the out() function safely embeds JSON data within HTML <script> tags, allowing JavaScript to consume server-side data without creating security vulnerabilities:

Result in the browser (what the user sees):

The JavaScript executes successfully and the console displays:

The userData object is properly initialized and accessible to JavaScript code throughout the page.

Generated HTML source (viewable via "View Page Source"):

The out() function with the 'json' parameter ensures that the JSON data is properly escaped for embedding within <script> tags. This prevents XSS attacks that could occur if user-controlled data contained malicious payloads like </script><script>alert('XSS')</script>. By converting characters like <, >, &, and quotes into their Unicode escape sequences, the function ensures the data remains safely contained within the JavaScript context while being fully parseable as valid JSON.

Example #6: JavaScript String Literal

This example demonstrates how the out() function safely escapes string values when embedding them directly inside JavaScript string literals, preventing syntax errors and code injection attacks:

Result in the browser (what the user sees):

An alert box appears displaying:

The JavaScript correctly interprets the string literal with the embedded quotes.

Generated HTML source (viewable via "View Page Source"):

The out() function with the 'javascript' parameter properly escapes special characters that would break JavaScript string syntax. In this example, the double quotes within the string are escaped as \", preventing them from prematurely terminating the string literal. The function also handles other dangerous characters like single quotes, backslashes, and line breaks, ensuring the resulting JavaScript code is syntactically valid and immune to injection attacks where malicious users might try to break out of the string context to execute arbitrary code.

Example #7: Using Named Parameters

This example demonstrates how to use PHP's named parameters feature (introduced in PHP 8.0) with the out() function, providing clearer and more maintainable code when specifying parameters:

Understanding the examples:

In the first example, encoding: 'ISO-8859-1' explicitly names the third parameter, making it clear that we're overriding the default UTF-8 encoding. This is particularly useful when working with legacy systems or databases that use different character encodings.

In the second example, output_format: 'json' names the second parameter, making the intent obvious even without seeing the function signature. This approach is especially valuable in larger codebases where developers may not be familiar with every function's parameter order.

Using named parameters with the out() function enhances code clarity and makes your intentions explicit, particularly when overriding default values like the encoding parameter or when you want to emphasize which output format is being used. This is especially valuable in team environments where code readability and maintainability are priorities.

Output Comparison

Given the input: <script>alert('xss')</script>

Exceptions

Notes

• The function guarantees a string return value by converting null inputs to empty strings
• Character encoding is critical for security - mismatched encoding can allow XSS attacks
• The 'html' and 'attribute' formats produce identical output but represent different semantic contexts
• JSON output includes proper Unicode escapes for dangerous characters, providing defense-in-depth protection
• The function follows a "fail fast" approach, throwing exceptions rather than silently producing unsafe output
• Requires PHP 7.3+ for JSON_THROW_ON_ERROR flag support