JavaScript Integration

Purpose and Scope

The Js class converts PHP data to JavaScript expressions that can be safely embedded in HTML. It applies mandatory XSS protection flags during JSON encoding and intelligently wraps complex structures with JSON.parse(). For view rendering and Blade templating, see page 5.1.

---

System Overview

The Hypervel\Support\Js class src/Js.php16 provides secure PHP-to-JavaScript data conversion. It implements Htmlable and Stringable interfaces for seamless integration with view rendering contexts.

Key Components:

Component	Location	Purpose
Js	src/Js.php16	Main conversion class implementing Htmlable, Stringable
Js::from()	src/Js.php45-48	Static factory method
Js::encode()	src/Js.php79-90	JSON encoding with REQUIRED_FLAGS
convertDataToJavaScriptExpression()	src/Js.php55-72	Primary conversion logic
convertJsonToJavaScriptExpression()	src/Js.php97-108	Wraps JSON in JSON.parse()
REQUIRED_FLAGS	src/Js.php28	Security flags: `JSON_HEX_TAG

Sources: src/Js.php1-126

---

Class Structure

Interfaces Implemented:

Interface	Method	Location	Purpose
Htmlable	toHtml()	src/Js.php113-116	Returns JavaScript expression as HTML-safe string
Stringable	__toString()	src/Js.php121-124	Enables string casting, delegates to toHtml()

Sources: src/Js.php16 src/Js.php113-124

---

Conversion Pipeline

Conversion Pipeline Diagram

Sources: src/Js.php35-108

---

Type-Specific Processing

Type Handling in convertDataToJavaScriptExpression()

Input Type	Check Location	Processing	Output
Js instance	src/Js.php57-59	Return $data->toHtml() directly	JavaScript expression string
BackedEnum	src/Js.php61-63	Extract $data->value	Continue with enum value
Jsonable	src/Js.php81-83	Cast to string: (string) $data	JSON string
Arrayable (non-JsonSerializable)	src/Js.php85-87	Call $data->toArray()	Array for encoding
String input	src/Js.php67-69	Wrap in single quotes: '...'	JavaScript string literal
Other types	src/Js.php89	Pass to json_encode()	JSON representation

Processing Flow in encode()

Sources: src/Js.php55-90

---

Security: REQUIRED_FLAGS

The REQUIRED_FLAGS constant src/Js.php28 enforces XSS protection through mandatory JSON encoding flags:

Flag Breakdown:

Flag	Hex Escape	Purpose	Example
JSON_HEX_TAG	< → \u003C, > → \u003E	Prevents HTML tag injection	<script> → \u003Cscript\u003E
JSON_HEX_APOS	' → \u0027	Prevents single-quote escapes	'alert' → \u0027alert\u0027
JSON_HEX_AMP	& → \u0026	Prevents entity injection	a&b → a\u0026b
JSON_HEX_QUOT	" → \u0022	Prevents double-quote escapes	"test" → \u0022test\u0022
JSON_THROW_ON_ERROR	N/A	Throws JsonException on failure	Ensures encoding success

Application Points:

Method	Location	Usage
encode()	src/Js.php89	json_encode($data, $flags | static::REQUIRED_FLAGS, $depth)
convertJsonToJavaScriptExpression()	src/Js.php104	json_encode($json, $flags | static::REQUIRED_FLAGS)

The flags are combined with user-provided flags using bitwise OR, ensuring security flags are always applied.

Sources: src/Js.php28 src/Js.php89 src/Js.php104

---

Output Formatting

convertJsonToJavaScriptExpression() Logic

The method src/Js.php97-108 determines JavaScript output format based on JSON structure:

Output Decision Table

JSON Pattern	Condition Check	JavaScript Output	Example Input → Output
[] or {}	$json === '[]' || $json === '{}'	Raw JSON	[] → []
Starts with "	Str::startsWith($json, '"')	JSON.parse('...')	"text" → JSON.parse('"text"')
Starts with {	Str::startsWith($json, '{')	JSON.parse('...')	{"a":1} → JSON.parse('{"a":1}')
Starts with [	Str::startsWith($json, '[')	JSON.parse('...')	[1,2,3] → JSON.parse('[1,2,3]')
Primitives	Other	Raw JSON	true → true, 123 → 123, null → null

JSON.parse() Wrapping Process src/Js.php104:

1. JSON string is re-encoded with REQUIRED_FLAGS: json_encode($json, $flags | static::REQUIRED_FLAGS)
2. Outer quotes stripped: substr(..., 1, -1)
3. Wrapped: "JSON.parse('" . $strippedJson . "')"

This double-encoding ensures XSS protection for complex structures.

String Literal Conversion

For string inputs src/Js.php67-69:

1. JSON encode with REQUIRED_FLAGS: $json = static::encode($data, $flags, $depth)
2. Strip outer double quotes: substr($json, 1, -1)
3. Wrap in single quotes: "'" . $stripped . "'"

Example: "hello" → JSON: "\"hello\"" → Strip: \"hello\" → Wrap: '\"hello\"'

Sources: src/Js.php67-69 src/Js.php97-108

---

Factory Method and Constructor

Js::from() Static Factory

The static factory method src/Js.php45-48 provides a convenient instantiation interface:

Parameter	Type	Default	Description
$data	mixed	Required	PHP data to convert to JavaScript
$flags	int	0	Additional JSON flags (combined with REQUIRED_FLAGS)
$depth	int	512	Maximum recursion depth for json_encode()

Returns a new Js instance by delegating to the constructor.

Constructor

The constructor src/Js.php35-38 initializes the instance:

Calls convertDataToJavaScriptExpression() and stores result in the $js property src/Js.php37

Throws: JsonException if encoding fails src/Js.php33

Sources: src/Js.php35-48

---

Usage with View Layer

Integration Interfaces

The Js class implements interfaces for view integration src/Js.php16:

Interface	Method	Implementation
Htmlable	toHtml()	src/Js.php113-116 - Returns $this->js
Stringable	__toString()	src/Js.php121-124 - Delegates to toHtml()

Both methods return the same JavaScript expression stored in the $js property, enabling direct output in views and templates.

Usage Pattern

Typical workflow:

The Blade facade src/Facades/Blade.php compiles templates, while Js ensures secure data transfer from PHP to JavaScript contexts within those templates.

Sources: src/Js.php16 src/Js.php113-124 src/Facades/Blade.php1-54

---

Error Handling

The class enforces strict error handling through the JSON_THROW_ON_ERROR flag src/Js.php28:

• All JSON encoding operations throw JsonException on failure
• Constructor declares @throws JsonException src/Js.php33
• Factory method declares @throws JsonException src/Js.php43
• Encode method declares @throws JsonException src/Js.php77
• Conversion method declares @throws JsonException src/Js.php53

This ensures that encoding failures are immediately visible rather than silently producing incorrect JavaScript expressions.

Sources: src/Js.php28 src/Js.php33 src/Js.php43 src/Js.php53 src/Js.php77

---

Dependencies

The Js class depends on several framework components:

Dependency	Namespace	Usage
BackedEnum	PHP 8.1+	Enum value extraction src/Js.php7
Arrayable	Hyperf\Contract	Array conversion src/Js.php8
Jsonable	Hyperf\Contract	JSON serialization src/Js.php9
Str	Hyperf\Stringable	String operations src/Js.php10
Htmlable	Hyperf\ViewEngine\Contract	HTML-safe output src/Js.php11
JsonSerializable	PHP	JSON serialization interface src/Js.php13
Stringable	PHP	String casting src/Js.php14

Sources: src/Js.php7-14