Realiza uma correspondência com expressão regular

# preg_match

(PHP 4, PHP 5, PHP 7, PHP 8)

preg_match — Realiza uma correspondência com expressão regular

### Descrição

function preg_match(
string `$pattern`,
string `$subject`,
array `&$matches` = `null`,
int `$flags` = 0,
int `$offset` = 0
): int|false

Pesquisa `subject` por uma correspondência à expressão regular informada em `pattern`.

### Parâmetros

`pattern`

  A expressão sendo procurada, como uma string.

`subject`

  A string de entrada.

`matches`

  Se `matches` for informada, será preenchida com os resultados da pesquisa. $matches[0] contéra o texto que correspondeu à expressão inteira, $matches[1] terá o texto que correspondeu à primeira sub-expressão entre parênteses capturada, e assim por diante.

`flags`

  `flags` pode ser uma combinação das seguintes constantes:

  `PREG_OFFSET_CAPTURE`

    Se esta constante for passada, para cada correspondência o deslocamento (em bytes) da string também será retornado. Observe que isto modifica o valor de `matches` para um array de arrays onde cada elemento é um array que consiste na string correspondida no elemento `0` e seu deslocamento na string `subject` no elemento `1`.

        <?php
        preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
        print_r($matches);
        ?>

    O exemplo acima produzirá:

        Array
        (
            [0] => Array
                (
                    [0] => foobarbaz
                    [1] => 0
                )

            [1] => Array
                (
                    [0] => foo
                    [1] => 0
                )

            [2] => Array
                (
                    [0] => bar
                    [1] => 3
                )

            [3] => Array
                (
                    [0] => baz
                    [1] => 6
                )

        )

  `PREG_UNMATCHED_AS_NULL`

    Se esta constante for passada, sub-expressões não correspondidas são reportadas como `null`; caso contrário elas são reportadas como strings vazias.

        <?php
        preg_match('/(a)(b)*(c)/', 'ac', $matches);
        var_dump($matches);
        preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
        var_dump($matches);
        ?>

    O exemplo acima produzirá:

        array(4) {
          [0]=>
          string(2) "ac"
          [1]=>
          string(1) "a"
          [2]=>
          string(0) ""
          [3]=>
          string(1) "c"
        }
        array(4) {
          [0]=>
          string(2) "ac"
          [1]=>
          string(1) "a"
          [2]=>
          NULL
          [3]=>
          string(1) "c"
        }

`offset`

  Normalmente, a pesquisa começa no início da string de entrada. O parâmetro opcional `offset` pode ser usado para especificar o deslocamento alternativo (em bytes) a partir do qual a pesquisa será iniciada.

  > Nota:

  > Usar `offset` não é equivalente a passar `substr($subject, $offset)` para preg_match() no lugar da string de entrada, porque `pattern` pode conter afirmações como ^, $ ou (?<=x) que depende da string inteira. Compare:

  >     <?php
  >     $subject = "abcdef";
  >     $pattern = '/^def/';
  >     preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
  >     print_r($matches);
  >     ?>

  > O exemplo acima produzirá:

  >     Array
  >     (
  >     )

  > enquanto este exemplo

  >     <?php
  >     $subject = "abcdef";
  >     $pattern = '/^def/';
  >     preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
  >     print_r($matches);
  >     ?>

  > produz

  >     Array
  >     (
  >         [0] => Array
  >             (
  >                 [0] => def
  >                 [1] => 0
  >             )

  >     )

  > Alternativamente, para evitar o uso de substr(), use a afirmação `\G` ao invés da âncora `^`, ou o modificador `A`, ambos funcionam com o parâmetro `offset`.

### Valor Retornado

preg_match() retorna 1 se `pattern` corresponder a `subject`, 0 se não corresponder, ou `false` em caso de falha.

Aviso

Esta função pode retornar o valor booleano `false`, mas também pode retornar um valor não booleano que pode ser avaliado como `false`. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

### Erros/Exceções

Se o padrão de expressão regular passado não for compilado para uma expressão regular válida, um `E_WARNING` será emitido.

### Registro de Alterações

Versão | Descrição
--- | ---
7.2.0 | A constante `PREG_UNMATCHED_AS_NULL` agora é suportada para o parâmetro `$flags`.

### Exemplos

Exemplo #1 Encontrando a string de texto "php"

    <?php
    // A letra "i" após o delimitador da expressão indica uma pesquisa insensível a maiúsculas/minúsculas
    if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
        echo "Uma correspondência foi encontrada.";
    } else {
        echo "Uma correspondência foi encontrada.";
    }
    ?>

Exemplo #2 Encontrando a palavra "web"

    <?php
    /* \b na expressão indica uma borda de palavra, portanto somente a palavra
     * separada "web" é correspondida, e não uma palavra que contém "web" como "webbing" ou "cobweb" */
    if (preg_match("/\bweb\b/i", "PHP is the web scripting language of choice.")) {
        echo "Uma correspondência foi encontrada.";
    } else {
        echo "Uma correspondência foi encontrada.";
    }

    echo "\n";

    if (preg_match("/\bweb\b/i", "PHP is the website scripting language of choice.")) {
        echo "Uma correspondência foi encontrada.";
    } else {
        echo "Uma correspondência foi encontrada.";
    }
    ?>

Exemplo #3 Obtendo o nome de domínio de uma URL

    <?php
    // obtem o nome do servidor da URL
    preg_match('@^(?:http://)?([^/]+)@i',
        "http://www.php.net/index.html", $matches);
    $host = $matches[1];

    // obtém os últimos dois segmentos do nome do servidor
    preg_match('/[^.]+\.[^.]+$/', $host, $matches);
    echo "nome de domínio é: {$matches[0]}\n";
    ?>

O exemplo acima produzirá:

    nome de domínio é: php.net

Exemplo #4 Usando sub-expressão nomeada

    <?php

    $str = 'foobar: 2008';

    preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);

    /* Alternativa */
    // preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);

    print_r($matches);

    ?>

O exemplo acima produzirá:

    Array
    (
        [0] => foobar: 2008
        [name] => foobar
        [1] => foobar
        [digit] => 2008
        [2] => 2008
    )

### Notas

Dica

Não use preg_match() se for requerido apenas verificar se uma string está contida em outra. Use strpos() em seu lugar, pois será mais rápida.

### Veja Também

- Expressões PCRE
- preg_quote() - Escapa caracteres de expressão regular
- preg_match_all() - Realiza uma correspondência global de expressão regular
- preg_replace() - Realiza uma pesquisa por uma expressão regular e substitui
- preg_split() - Divide uma string com base em expressão regular
- preg_last_error() - Retorna o código de erro da última expressão regular PCRE executada
- preg_last_error_msg() - Retorna a mensagem de erro da última execução de expressão regular PCRE

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open