Definition and Usage

PHP Version
4.0.4+

The ctype_digit() function checks whether a given string contains only numeric character(s) from 0 to 9.
It returns true if every character in the string passed as an argument is a digit; otherwise, it returns false.

Features

  • Whitespace characters are not evaluated as numeric
  • An empty string ('') is not evaluated as numeric.
  • Floating-point numbers (float type) such as '3.14' are evaluated as non-numeric because the string contains a . character.
  • Strings representing negative integers, such as '-123', are evaluated as non-numeric because they contain a - sign
  • Prior to PHP 8.1.0, non-string arguments could be passed; however, passing non-string arguments is no longer supported as of PHP 8.1.0.

Basic Example

PHP 
var_dump(ctype_digit('1234'));  // bool(true)
var_dump(ctype_digit('0123'));  // bool(true)

var_dump(ctype_digit(' 123 ')); // bool(false)
var_dump(ctype_digit('3.14'));  // bool(false)
var_dump(ctype_digit('-123'));  // bool(false)
var_dump(ctype_digit(''));      // bool(false)

/* As of PHP 8.1.0, passing non-string arguments is no longer supported. */
var_dump(ctype_digit(123)); // bool(false)
var_dump(ctype_digit(1e3)); // bool(false)

See also the following related functions:

Syntax

PHP 
ctype_digit(mixed $text): bool

Parameters

Description of the ctype_digit() function parameters
$text Required. The value to check.

Notes

The ctype_digit() function determines whether characters are numeric based on ASCII codes, which only include the digits 0 through 9. The ASCII range encompasses a total of 128 characters from 0x00 to 0x7F, and the digits 0 through 9 are included within this range.

However, if the value passed as an argument is an integer, you must consider the following:

If an integer between -128 and 255 (inclusive) is provided as the argument, it is interpreted as the ASCII value of a single character. This means the integer is effectively converted to that specific character.

PHP 
/* int type, integer within the ASCII range (-128 to 255) */
$x = 65; // 65, an integer between -128 and 255, is considered the ASCII value for the character 'A'
var_dump(ctype_digit($x)); // false => treated as the string 'A'

/* int type, integer outside the ASCII range (-128 to 255) */
$y = 1234; // 1234, an integer outside the -128 to 255 range, is converted to the string '1234'
var_dump(ctype_digit($y)); // true => treated as the string '1234'

The following explains the example code above:

Case of $x = 65
  1. The integer 65, which falls between -128 and 255, is treated as an ASCII value. Therefore, it corresponds to the ASCII value of the string 'A'.
  2. As a result, the value passed as the argument is considered 'A'.
  3. Since the string 'A' does not consist solely of digits, the function returns false.
Case of $y = 1234
  1. Since the integer 1234 is not within the range of -128 to 255, it is not interpreted as an ASCII value for a single character but remains the original integer 1234.
  2. When the integer 1234 is passed to the ctype_digit() function, which expects a string, the integer is converted to the string '1234'.
  3. Since the resulting string '1234' consists entirely of digits, the function returns true.

Changes as of PHP 8.1.0

As of PHP 8.1.0, passing non-string arguments to the ctype_digit() function is no longer supported.

Return Values

Returns true if every character in the string passed as an argument is a digit; otherwise, returns false.

Things to Keep in Mind

There are several important points to be aware of when using the ctype_digit() function.

Converting Arguments to Strings Before Use

As mentioned above, providing integer values within the range of -128 to 255 may lead to unintended results. Furthermore, since passing non-string arguments to ctype_digit() is no longer supported as of PHP 8.1.0, it is recommended to convert any value used as an argument into a string beforehand.

PHP 
$x = 65;

var_dump(ctype_digit($x));           // false => unintended result
var_dump(ctype_digit((string)$x));   // true

Using the trim() Function to Remove Leading and Trailing Whitespace

The ctype_digit() function does not evaluate whitespace characters as numeric. To apply ctype_digit() more strictly, it is advisable to use the trim() function to remove any potential leading or trailing whitespace from the given string. This ensures an accurate check for whether a string consists solely of digits, even if it initially contained spaces.

Additional Explanation
The trim() function removes (trims) whitespace or other specified characters from both ends of a string.

PHP 
$var = ' 123 ';

var_dump(ctype_digit($var));       // false
var_dump(ctype_digit(trim($var))); // true

Practical Examples

The ctype_digit() function is convenient or useful in the following scenarios:

Validating User Input

It is particularly useful for form validation to ensure that users enter only numeric digits.

PHP 
$user_input = trim($_POST['age']);

if (ctype_digit($user_input)) {
    // Process the input if it consists only of digits.
    $age = intval($user_input); // Can be converted to an integer for further use.
    echo "Age is {$age}.";
} else {
    echo "Please enter your age using only numbers.";
}

Code Explanation
The intval() function returns the integer value of the argument provided.

References

See also