(PHP 4, PHP 5, PHP 7, PHP 8)
preg_match — Realiza uma correspondência com expressão regular
$pattern,$subject,&$matches = null,$flags = 0,$offset = 0
Pesquisa subject por uma correspondência à expressão
regular informada em pattern.
patternA expressão sendo procurada, como uma string.
subjectA 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
offsetnão é equivalente a passarsubstr($subject, $offset)para preg_match() no lugar da string de entrada, porquepatternpode 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
\Gao invés da âncora^, ou o modificadorA, ambos funcionam com o parâmetrooffset.
preg_match() retorna 1 se pattern
corresponder a subject, 0 se não corresponder, ou false em caso de falha.
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.
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.
| Versão | Descrição |
|---|---|
| 7.2.0 |
A constante PREG_UNMATCHED_AS_NULL agora é suportada para o parâmetro
$flags.
|
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
)
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.