sscanf
Parses a string according to a format template and returns the extracted values.
sscanf(string $string, string $format, mixed &...$vars): array|int|null- Added in PHP 4.0.1
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The input string being parsed. |
$format | string | The format template, using printf-style conversion specifications with a few differences. |
$varsoptional | mixed | Optional variadic list of variables passed by reference that receive the parsed values. |
Return value
array|int|nullWith two arguments, an array of the parsed values. If variables are passed by reference, the number of values assigned is returned instead, or -1 if the end of the input is reached before anything is parsed. Returns null when the format expects more substrings than the input provides.
Errors
Throws a ValueError if the format string contains an unknown or malformed conversion specification.
sscanf is the inverse of sprintf: you describe the shape of a line and it hands back the pieces, already converted to int or float where the specifier says so. It is the shortest route from a rigidly formatted line to typed values.
When to reach for it
Reach for it when the input has a known fixed layout — a log line, a serial number like SN/2350001, a coordinate pair, a date written as 2026-08-30. The %* flag skips a field without assigning it, which is handy for columns you do not care about. For anything with optional parts, alternation or repetition, preg_match is the right tool instead.
What trips people up
The return value changes shape depending on how you call it: two arguments give you an array, extra by-reference variables give you an integer count. Assigning $result = sscanf($s, $f, $a, $b) and then treating $result as an array is the classic bug. %s stops at the first whitespace character, so it will never capture a phrase, and whitespace in the format matches any run of whitespace in the input. When the input does not match, you get null or an array padded with null entries rather than an exception — always check before using the values.
Example
When to use it
- Split a date or timestamp string into typed integer parts
- Pull the numeric portion out of a structured ID such as SN/2350001
- Parse fixed-format log lines into IP, method, path and status
- Read a "width x height" dimension string into two integers
Frequently asked questions
What is the difference between sscanf and preg_match?
sscanf matches a fixed positional layout and converts values to int or float for you, while preg_match matches an arbitrary pattern and always returns strings. Use sscanf for rigid formats and preg_match when the input has optional or repeating parts.
Why does sscanf return a number instead of an array?
Because you passed extra variables by reference. With just the string and format it returns an array of values; with reference variables it fills those and returns the count of assignments instead.
Why does %s only capture one word?
In sscanf, %s stops at the first whitespace character. To capture text containing spaces, match the surrounding structure explicitly or switch to preg_match.
More examples
Skipping fields with %*
The %*s consumes the dash column but assigns nothing, so the returned array has four entries rather than five. The final var_dump confirms the status code came back as a real integer, not the string "200", because %d converts as it parses.
<?php
$log = '192.168.0.1 - GET /index.php 200';
$data = sscanf($log, '%s %*s %s %s %d');
print_r($data);
var_dump($data[3] === 200);Detecting input that does not match
Only the first input matches the template and yields two integers. The other two fail, and the output shows that failure surfaces as nulls rather than an exception, which is why the guard checks both the array itself and its elements before using them.
<?php
$inputs = ['12x34', '12 by 34', 'x'];
foreach ($inputs as $in) {
$r = sscanf($in, '%dx%d');
if ($r === null || $r[0] === null || $r[1] === null) {
echo "'{$in}' => no match\n";
continue;
}
echo "'{$in}' => {$r[0]} by {$r[1]}\n";
}
Discussion