ramsey/uuid · error · ValueError

%s(): Argument #1 ($data) is invalid

Error message

%s(): Argument #1 ($data) is invalid

What it means

When PHP unserializes a Ramsey\Uuid\Type\Integer object, __unserialize(array $data) requires the array key 'string' (the shape emitted by __serialize()). A payload missing that key triggers a native ValueError with a PHP-internal-style message. The data being unserialized was not produced by this class or was corrupted.

Source

Thrown at src/Type/Integer.php:112

    /**
     * Constructs the object from a serialized string representation
     *
     * @param string $data The serialized string representation of the object
     */
    public function unserialize(string $data): void
    {
        $this->__construct($data);
    }

    /**
     * @param array{string?: string} $data
     */
    public function __unserialize(array $data): void
    {
        // @codeCoverageIgnoreStart
        if (!isset($data['string'])) {
            throw new ValueError(sprintf('%s(): Argument #1 ($data) is invalid', __METHOD__));
        }
        // @codeCoverageIgnoreEnd

        $this->unserialize($data['string']);
    }

    /**
     * @return numeric-string
     */
    private function prepareValue(float | int | string $value): string
    {
        $value = (string) $value;
        $sign = '+';

        // If the value contains a sign, remove it for the digit pattern check.
        if (str_starts_with($value, '-') || str_starts_with($value, '+')) {
            $sign = substr($value, 0, 1);
            $value = substr($value, 1);

View on GitHub (pinned to da5b521600)

Solutions

  1. Rebuild the object from its scalar: $integer = new Integer($rawNumericString)
  2. Purge the malformed cache/session entries
  3. Keep the code that writes and reads serialized values on the same library version
  4. Store numeric strings and instantiate Integer at read time instead of serializing objects

Example fix

// before
$integer = unserialize($cachedValue); // payload missing 'string'
// ValueError: Ramsey\Uuid\Type\Integer::__unserialize(): Argument #1 ($data) is invalid

// after: cache the numeric string, reconstruct on read
$integer = new Integer($cachedValue); // e.g. '12345678901234567890'
Defensive patterns

Strategy: try-catch

Validate before calling

// Validate payload shape before unserializing
$decoded = unserialize($cached, ['allowed_classes' => false]);
if (!(is_array($decoded) && isset($decoded['string']))) {
    // rebuild from the source numeric string
    $integer = new Ramsey\Uuid\Type\Integer($rawNumeric);
}

Try / catch

use Ramsey\Uuid\Type\Integer;

try {
    $integer = unserialize($cached);
} catch (\ValueError $e) {
    $integer = new Integer($rawNumeric); // rebuild from the canonical value
}

Prevention

When it happens

Trigger: unserialize() of an Integer payload whose array body lacks 'string' — hand-crafted serialized strings, cache/session values written by different code, or payloads altered in storage.

Common situations: Shared caches or sessions spanning application versions; serialized blobs migrated between systems; test fixtures containing literal serialized strings that drift from the real format.

Related errors

AI-assisted analysis of ramsey/uuid@da5b521600 (2026-08-21). Data as JSON: /api/errors/c9ae542cf3f05730. Report an issue: GitHub.