ramsey/uuid · error · InvalidArgumentException

Value must be a signed integer or a string containing only d

Error message

Value must be a signed integer or a string containing only digits 0-9 and, optionally, a sign (+ or -)

What it means

Ramsey\Uuid\Type\Integer stores integers as strings so values beyond PHP_INT_MAX work on all platforms. prepareValue() casts the input to string, removes one optional leading '+' or '-', and requires the remainder to match /^\d+$/. Anything else — decimal points, scientific notation, separators, empty strings — throws Ramsey\Uuid\Exception\InvalidArgumentException. Floats are cast to their string form first, so a float like 12.5 fails the digit check.

Source

Thrown at src/Type/Integer.php:134

        $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);
        }

        if (!preg_match('/^\d+$/', $value)) {
            throw new InvalidArgumentException(
                'Value must be a signed integer or a string containing only '
                . 'digits 0-9 and, optionally, a sign (+ or -)'
            );
        }

        // Trim any leading zeros.
        $value = ltrim($value, '0');

        // Set to zero if the string is empty after trimming zeros.
        if ($value === '') {
            $value = '0';
        }

        // Add the negative sign back to the value.
        if ($sign === '-' && $value !== '0') {
            $value = $sign . $value;

            /** @phpstan-ignore property.readOnlyByPhpDocAssignNotInConstructor */

View on GitHub (pinned to da5b521600)

Solutions

1. Pass native ints or digit-only strings: new Integer(1000) or new Integer('1000')
2. Cast floats that are whole numbers to int first: new Integer((int) 12.0)
3. Strip separators/whitespace before construction: preg_replace('/[^0-9+-]/', '', $value)
4. Validate with the same rule the class uses: preg_match('/^[+-]?\d+$/', (string) $value)

Example fix

// before
$integer = new Integer('1,000');
// InvalidArgumentException: Value must be a signed integer or a string containing only digits 0-9...

// after: strip separators and validate
$normalized = str_replace(',', '', '1,000');
if (!preg_match('/^[+-]?\d+$/', $normalized)) {
    throw new \InvalidArgumentException('Expected a signed integer');
}
$integer = new Integer($normalized); // '1000'

// Run before constructing Integer (mirrors the library's rule)
$value = (string) $input;
if (!preg_match('/^[+-]?\d+$/', $value)) {
    throw new \InvalidArgumentException('Expected a signed integer, got: ' . $input);
}

// For float input, cast only whole numbers
if (is_float($input) && floor($input) !== $input) {
    throw new \InvalidArgumentException('Integer cannot hold fractional values');
}

function isIntegerValue(float | int | string $value): bool
{
    return preg_match('/^[+-]?\d+$/', (string) $value) === 1;
}

use Ramsey\Uuid\Exception\InvalidArgumentException;

try {
    $integer = new Integer($input);
} catch (InvalidArgumentException $e) {
    throw new \InvalidArgumentException('count must be an integer', 0, $e);
}

When it happens

Trigger: Constructing new Integer('1,000') (thousands separator), new Integer(12.5) (float stringifies to '12.5'), new Integer('1e3'), new Integer('') or new Integer('0x1A'). Also passing '007' works, but ' 42' with whitespace fails.

Common situations: Locale-formatted numbers ('1.000' in de_DE means one thousand but parses as digits with a dot, which fails); floats with fractional parts; scientific notation from JSON parsing of large numbers; concatenated empty strings from optional inputs.

Related errors

• Value must be a signed decimal or a string containing only d
• Value must be a hexadecimal number
• Fields used to create a UuidV2 must represent a version 2 (D
• Fields used to create a UuidV3 must represent a version 3 (n
• Fields used to create a UuidV4 must represent a version 4 (r

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