README

Convert PHP serialized data into pretty-printed JSON — safely, with error messages you can act on.

use Serialized\Serialized;

echo Serialized::toJson('a:2:{s:4:"name";s:6:"Chrome";s:6:"mobile";b:0;}');

{
    "name": "Chrome",
    "mobile": false
}

Installation

composer require roelmagdaleno/serialized

Requires PHP 8.4 or newer. No framework, no runtime dependencies.

Usage

Four verbs cover everything:

$json  = Serialized::toJson($payload);    // string, throws on any problem
$json  = Serialized::tryToJson($payload); // ?string, null instead of throwing
$value = Serialized::toArray($payload);   // mixed, the unserialized PHP value
$ok    = Serialized::isValid($payload);   // bool, never throws

Need to configure the conversion? Serialized::make() returns a converter you can tune. Every method returns a new instance, so a configured converter is safe to share, cache, or bind once in a container.

$converter = Serialized::make()
    ->withMaxBytes(1_000_000)
    ->withMaxDepth(32)
    ->withMaxElements(50_000)
    ->allowClasses([App\Models\Money::class])
    ->compact();

$json = $converter->toJson($payload);

Errors you can act on

When a payload is broken, unserialize() says Error at offset 24 and leaves you there. This package tells you what broke, where, and how to fix it:

Serialized::toJson('a:1:{s:4:"name";s:6:"Chrom";}');

String length mismatch at offset 18: declared 6 bytes, found 5.

a:1:{s:4:"name";s:6:"Chrom";}
                  ^

Fix: Change s:6 to s:5, or restore the missing bytes in the value.

The same information is available in code. Every exception carries a Diagnostic, so your app can point at the exact byte too:

try {
    Serialized::toJson($payload);
} catch (SerializedException $exception) {
    $diagnostic = $exception->diagnostic();

    $diagnostic?->code;    // DiagnosticCode::LengthMismatch
    $diagnostic?->offset;  // 18
    $diagnostic?->reason;  // 'String length mismatch at offset 18: declared 6 bytes, found 5.'
    $diagnostic?->fix;     // 'Change s:6 to s:5, or restore the missing bytes in the value.'
    $diagnostic?->context; // ['declaredByteLength' => 6, 'foundByteLength' => 5, 'prefix' => 's']
}

Write your own messages

reason and fix are defaults, not a ceiling. code is a stable enum case — use it as a translation key, a log label, or something to match on — and context holds the raw facts the sentence was built from, so you can word the failure however your product needs:

use Serialized\Diagnostics\DiagnosticCode;

$message = match ($diagnostic->code) {
    DiagnosticCode::LengthMismatch => __('errors.length', [
        'declared' => $diagnostic->context['declaredByteLength'],
        'found' => $diagnostic->context['foundByteLength'],
        'offset' => $diagnostic->offset,
    ]),
    DiagnosticCode::DisallowedClass => "Blocked: {$diagnostic->context['className']}",
    default => $diagnostic->reason,
};

Two small things: the byte offset never appears inside context, because the diagnostic already owns it. And to print the package's own message again, caret snippet included, call DiagnosticMessage::render($diagnostic).

Here is every code and the context it carries:

The five exceptions

All five implement Serialized\Exceptions\SerializedException, so one catch covers them all. Catch a specific one and diagnostic() is guaranteed non-null — except for JsonEncodingException, the only one without a diagnostic: once the payload is validated, a json_encode failure cannot be traced back to a byte.

Objects are rejected by default

Unserializing an object can run its __wakeup() and __destruct() on data the payload controls. That is where most PHP deserialization attacks begin, so objects are refused unless you name the class yourself:

Serialized::toJson('O:8:"stdClass":0:{}');
// UnsafeSerializedDataException: Payload contains an object of class "stdClass" at offset 0.

Serialized::make()->allowClasses([stdClass::class])->toJson('O:8:"stdClass":0:{}');
// {}

The full model is in SECURITY.md.

Contributing

composer check      # formatting, static analysis and tests
composer test -- --coverage --min=100   # the suite with the 100% coverage gate

License

MIT. See LICENSE.md.