Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Regular Expressions

PHP preg_last_error() and preg_last_error_msg()

Reference for PHP preg_last_error() and preg_last_error_msg(): find out why a preg function failed, the PREG_*_ERROR constants, bad UTF-8, backtracking and the JSON-style check.

The preg_* functions do not throw exceptions. When something goes wrong they return false (or null for the replace functions) and remember the reason in a global error state. preg_last_error() returns that reason as an integer constant, and preg_last_error_msg() returns it as readable text.

Two things can go wrong. A compile error (a broken pattern such as an unbalanced bracket) emits a warning and leaves preg_last_error() at PREG_INTERNAL_ERROR. A runtime error (invalid UTF-8 input, too much backtracking) returns the failure value silently. Always check the return value first and ask for the reason second.

PHP
<?php
if (preg_match('/./u', "\xff") === false) {
    echo preg_last_error_msg();
}

Try it

PHP Detecting a failed match

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP 0 versus false, and a safe wrapper

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
preg_last_error(): int
preg_last_error_msg(): string
Constant Meaning
PREG_NO_ERROR The last preg_* call succeeded.
PREG_INTERNAL_ERROR An internal PCRE error, which includes a pattern that failed to compile.
PREG_BACKTRACK_LIMIT_ERROR pcre.backtrack_limit was exceeded.
PREG_RECURSION_LIMIT_ERROR pcre.recursion_limit was exceeded.
PREG_BAD_UTF8_ERROR The subject is not valid UTF-8 (with /u).
PREG_BAD_UTF8_OFFSET_ERROR The offset does not point to the start of a UTF-8 character.
PREG_JIT_STACKLIMIT_ERROR The JIT compiler ran out of stack space.

Return value: preg_last_error() returns one of the constants above. preg_last_error_msg() (added in PHP 8.0) returns a short text such as No error or Malformed UTF-8 characters, possibly incorrectly encoded.

Errors / Exceptions: none. Neither function changes the error state.

Usage notes

  • Check the return value first. The state is reset by every successful preg_* call, so ask for the error right after the call that failed.
  • false is not 0. preg_match() returns 0 for "no match" and false for an error. Compare with === 1 or === false; never use if (!preg_match(...)) for input that might be invalid.
  • Replace functions return null on failure, preg_split(), preg_grep() and preg_match_all() return false.
  • Compile errors also warn. A broken pattern emits E_WARNING with the position of the problem. The @ operator hides it, but logging it during development is more useful.
  • Backtracking limits protect the server from patterns such as (a+)+$. When you hit one, fix the pattern (see PCRE syntax); raising the limit only makes attacks cheaper.
  • Untrusted input: treat errors as "reject the input", not as "no match".
  • Throwing wrapper: there is no built-in exception mode, so a small helper like the one above is common. Unlike json_decode() (see JSON errors and flags), there is no JSON_THROW_ON_ERROR equivalent.