perldoc > Cpanel::JSON::XS

🔖 NAME

Cpanel::JSON::XS — cPanel fork of JSON::XS, fast and correct serializing

🚀 Quick Reference

Use CaseCommandDescription
⭐ Encode Perl to JSON (UTF-8)encode_json $dataConverts Perl data structure to UTF-8 JSON string
⭐ Decode JSON to Perldecode_json $json_textParses UTF-8 JSON string to Perl structure
🛠️ OO coder with optionsCpanel::JSON::XS->new->utf8->pretty->encode($data)Create configurable encoder/decoder
🔍 Check booleanCpanel::JSON::XS::is_bool($scalar)Returns true if scalar is JSON true/false
🔐 Safe decode (no refs)$json->allow_nonref(0)->decode($text)Reject non-array/object top-level values
📏 Limit nesting depth$json->max_depth(512)Prevent stack overflow
📦 Limit text size$json->max_size(1000000)Reject overly large JSON texts
🧹 Pretty-print$json->pretty->encode($data)Human-readable indented output
🔤 ASCII-only output$json->ascii->encode($data)Escapes non-ASCII characters
🔡 Latin1 output$json->latin1->encode($data)Escapes only characters > 255
🔢 Binary (raw bytes)$json->binary->encode($data)No UTF-8 detection, uses \xNN escapes
🔄 Incremental parsing$json->incr_parse($chunk)Parse JSON from stream
🏷️ Object serialization$json->allow_tags->encode($obj)Encode perl objects via FREEZE/THAW

📖 SYNOPSIS

use Cpanel::JSON::XS;

# exported functions, they croak on error
# and expect/generate UTF-8

$utf8_encoded_json_text = encode_json $perl_hash_or_arrayref;
$perl_hash_or_arrayref  = decode_json $utf8_encoded_json_text;

# OO-interface

$coder = Cpanel::JSON::XS->new->ascii->pretty->allow_nonref;
$pretty_printed_unencoded = $coder->encode ($perl_scalar);
$perl_scalar = $coder->decode ($unicode_json_text);

# Note that 5.6 misses most smart utf8 and encoding functionalities
# of newer releases.

# Note that JSON::MaybeXS will automatically use Cpanel::JSON::XS
# if available, at virtually no speed overhead either, so you should
# be able to just:

use JSON::MaybeXS;

# and do the same things, except that you have a pure-perl fallback now.

Note that this module will be replaced by a new JSON::Safe module soon,
with the same API just guaranteed safe defaults.

📝 DESCRIPTION

This module converts Perl data structures to JSON and vice versa. Its primary goal is to be correct and its secondary goal is to be fast. To reach the latter goal it was written in C.

As this is the n-th-something JSON module on CPAN, what was the reason to write yet another JSON module? While it seems there are many JSON modules, none of them correctly handle all corner cases, and in most cases their maintainers are unresponsive, gone missing, or not listening to bug reports for other reasons.

See below for the cPanel fork.

See MAPPING, below, on how Cpanel::JSON::XS maps perl values to JSON values and vice versa.

✨ Features

🔧 cPanel fork

Since the original author MLEHMANN has no public bugtracker, this cPanel fork sits on GitHub.

Source: https://github.com/rurban/Cpanel-JSON-XS | Original: http://cvs.schmorp.de/JSON-XS/

Issue tracker: GitHub or RT

Changes from JSON::XS:

📦 FUNCTIONAL INTERFACE

The following convenience methods are exported by default:

$json_text = encode_json $perl_scalar, [json_type]

Converts Perl data to UTF-8 encoded JSON string. Croaks on error. Equivalent to Cpanel::JSON::XS->new->utf8->encode($perl_scalar, $json_type) but faster.

$perl_scalar = decode_json $json_text [, $allow_nonref [, my $json_type ] ]

Parses UTF-8 JSON string to Perl data. Croaks on error. Optional $allow_nonref (default false) allows top-level scalars per RFC 7159. Equivalent to Cpanel::JSON::XS->new->utf8->decode($json_text, $json_type) but faster.

$is_boolean = Cpanel::JSON::XS::is_bool $scalar

Returns true if the scalar is a JSON boolean (JSON::PP::true/false, or from JSON::XS).

🗑️ DEPRECATED FUNCTIONS

🌐 A FEW NOTES ON UNICODE AND PERL

Since this often leads to confusion, here are a few very clear words on how Unicode works in Perl, modulo bugs.

  1. Perl strings can store characters with ordinal values > 255.
  2. Perl does not associate an encoding with your strings.
  3. The internal utf-8 flag has no meaning with regards to the encoding of your string.
  4. A "Unicode String" is simply a string where each character can be validly interpreted as a Unicode code point.
  5. A string containing "high" (> 255) character values is not a UTF-8 string.
  6. Unicode noncharacters only warn, as in core.
  7. Raw non-Unicode characters above U+10FFFF are disallowed.

🧩 OBJECT-ORIENTED INTERFACE

The object oriented interface lets you configure your own encoding or decoding style.

$json = new Cpanel::JSON::XS

Creates a new JSON object. All boolean flags are disabled by default. Mutators return the JSON object, allowing chaining.

🔧 Configuration Options

$json_text = $json->encode ($perl_scalar, $json_type)

Converts Perl data to JSON string. For type argument see Cpanel::JSON::XS::Type.

$perl_scalar = $json->decode ($json_text, my $json_type)

Parses JSON string to Perl data. Croaks on error.

($perl_scalar, $characters) = $json->decode_prefix ($json_text)

Like decode, but returns number of characters consumed, allowing trailing garbage.

Deprecated methods

🔄 INCREMENTAL PARSING

Allows parsing JSON streams. Methods:

Limitations: allow_nonref not supported; numbers cannot be incrementally parsed.

📋 Examples

Simple prefix extraction:

my $text = "[1,2,3] hello";
my $json = new Cpanel::JSON::XS;
my $obj = $json->incr_parse ($text);
my $tail = $json->incr_text;
# $tail now contains " hello"

Multiple objects from TCP stream:

my $json = new Cpanel::JSON::XS;
while (sysread $socket, my $buf, 4096) {
   for my $request ($json->incr_parse ($buf)) {
      # act on $request
   }
}

Parsing comma-separated objects:

my $text = "[1],[2], [3]";
my $json = new Cpanel::JSON::XS;
$json->incr_parse ($text);
while (my $obj = $json->incr_parse) {
   # do something
   $json->incr_text =~ s/^ \s* , //x;
}

Gigantic array-of-objects: See full man page for detailed example with manual [ parsing and element extraction.

📌 BOM

Detects Unicode Byte Order Marks (UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE) on decode. BOM handling is per-call, does not change object state. Older Perl (< 5.20) requires loading Encode module for multi-byte BOMs. RFC 7159 recommends UTF-8 only; future versions may reject UTF-16/32 BOMs.

🔀 MAPPING

JSON → Perl

Perl → JSON

📦 Object Serialization

Precedence: allow_tags (FREEZE) → convert_blessed (TO_JSON) → stringification overload → allow_blessed (null) → exception. Deserialization via THAW method when allow_tags enabled.

🏷️ ENCODING/CODESET FLAG NOTES

Flags control output encoding and escaping:

These flags are symmetric: encode with same flags as decode for correct round-trip.

🤝 INTEROP with JSON and JSON::XS

Cpanel::JSON::XS is the only known JSON decoder that passes all seriot.ch tests while being the fastest. It accepts booleans from JSON::XS, JSON::PP, and Mojo::JSON. For interoperability, load JSON and JSON::XS before Cpanel::JSON::XS to handle boolean objects correctly.

Tagged value syntax (allow_tags) can be converted to standard JSON arrays via regex for compatibility with other decoders.

📜 RFC 7159

RFC 7159 allows top-level scalars. For security, Cpanel::JSON::XS defaults to RFC 4627 (no scalars). Use ->allow_nonref to enable RFC 7159 behavior. Future versions may change the default; application authors should explicitly set allow_nonref(0) if they need strict mode.

🔒 SECURITY CONSIDERATIONS

JSON is inherently secure compared to other serializers because it does not deserialize objects by default. However, always:

🔄 vs. NEW JSON (RFC 4627 vs. RFC 7159)

Old JSON (RFC 4627) requires top-level array or object. New JSON (RFC 7159) allows scalars. For security, the default remains old. To enable new: my $json = JSON::XS->new->allow_nonref;

🧵 THREADS

Cpanel::JSON::XS supports ithreads (unlike JSON::XS). Report any thread-related bugs.

🐛 BUGS

Report issues at GitHub. The original JSON::XS author prefers private emails; please report both places for cross-fix.

📄 LICENSE

This module is available under the same licenses as Perl: Artistic License and GPL.

👁️ SEE ALSO

👤 AUTHOR

Reini Urban <rurban@cpan.org>

Marc Lehmann <schmorp@schmorp.de>, http://home.schmorp.de/

🧑‍💻 MAINTAINER

Reini Urban <rurban@cpan.org>

Cpanel::JSON::XS □✕
🔖 NAME 🚀 Quick Reference 📖 SYNOPSIS 📝 DESCRIPTION
✨ Features 🔧 cPanel fork
📦 FUNCTIONAL INTERFACE
$json_text = encode_json $perl_scalar, [json_type] $perl_scalar = decode_json $json_text [, $allow_nonref [, my $json_type ] ] $is_boolean = Cpanel::JSON::XS::is_bool $scalar
🗑️ DEPRECATED FUNCTIONS 🌐 A FEW NOTES ON UNICODE AND PERL 🧩 OBJECT-ORIENTED INTERFACE
$json = new Cpanel::JSON::XS 🔧 Configuration Options $json_text = $json->encode ($perl_scalar, $json_type) $perl_scalar = $json->decode ($json_text, my $json_type) ($perl_scalar, $characters) = $json->decode_prefix ($json_text) Deprecated methods
🔄 INCREMENTAL PARSING
📋 Examples
📌 BOM 🔀 MAPPING
JSON → Perl Perl → JSON 📦 Object Serialization
🏷️ ENCODING/CODESET FLAG NOTES 🤝 INTEROP with JSON and JSON::XS 📜 RFC 7159 🔒 SECURITY CONSIDERATIONS 🔄 vs. NEW JSON (RFC 4627 vs. RFC 7159) 🧵 THREADS 🐛 BUGS 📄 LICENSE 👁️ SEE ALSO 👤 AUTHOR 🧑‍💻 MAINTAINER

Generated by phpman v4.9.27 · Markdown · JSON · MCP Author: Che Dong Under GNU General Public License
2026-07-17 14:12 @216.73.216.114
CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Valid XHTML 1.0 Transitional!Valid CSS!
Enhanced by LLM: deepseek-v4-flash / taotoken.net / www.chedong.com - original format

^_top_^