ARTIGOS

Expressões regulares no PHP

[Fonte](http://php.net/pCRE)

É importante para qualquer programador conhecer e saber usar o básico sobre expressões regulares. Se você ainda não conhece ou tem dúvidas do uso básico de expressões regulares o tutorial de introdução.

O `PHP` fornece várias funções para manipular informação com expressões regulares:

|Função   |Descrição  |
|---------|-----------|
|preg_filter | Realiza uma pesquisa por expressão regular e a substitui. |
|preg_grep  | Retorna as entradas do vetor que combinam com o padrão. |
|preg_last_error  | Retorna o código de erro da última regex PCRE executada. |
|preg_match_all   | Realiza uma procura global por expressão regular. |
|preg_match | Realiza uma procura por expressão regular. |
|preg_quote | Adiciona escape em caracteres da expressão regular. |
|preg_replace_callback_array  | Realiza uma procura por uma expressão regular e substitui usando callbacks. |
|preg_replace_callback        | Executa uma busca usando expressão regular e modifica usando uma callback. |
|preg_replace  | Realiza uma pesquisa por uma expressão regular e a substitui. |
|preg_split    | Divide uma string por uma expressão regular |

## preg_filter e preg_replace

Realiza uma pesquisa por expressão regular e a substitui. As duas funções são idênticas.

```php
preg_filter(mixed $padrao, mixed $substituicao, mixed $sujeito [, int $limite = -1 [int &$contador]])

preg_replace(mixed $padrao, mixed $substituicao, mixed $sujeito [, int $limite = -1 [int &$contador]])
```

### `$padrao`
O padrão a ser pesquisado, pode ser uma string ou um vetor com strings.

### `$substituicao`

Uma string ou vetor com strings para substituir.

Se este parâmetro é uma string e o parâmetro `$padrao` é um vetor, todos padrões vão ser substituídos por esta string. Se ambos parâmetros `$padrao` e `$substituicao` são vetores, cada padrão vai ser substituído pelo seu substituto  correspondente. Se houver menos elementos no vetor `$substituicao` do que no vetor `$padrao`, qualquer `$padrao` extra será substituído por uma string vazia.

### `$sujeito`

String ou um vetor com strings para pesquisar e substituir. Se o `$sujeito` é um vetor, então a pesquisa e a substituição são executadas em cada entrada do `$sujeito`, e o valor de retorno é um vetor também.

### `$limite`

O máximo possível de substituições para cada `$padrao` em cada string `$sujeito`. O padrão é `-1`, ou seja, sem limite.

### `$count`

Se especificado, essa variável será preenchida com o número de substiuições realizadas.

### Valor retornado

Se a correspondência for encontrada, o novo  `$sujeito`  será devolvido, caso contrário  `$sujeito`  será devolvido inalterado ou  **`NULL`**  se ocorrer algum erro.

### Exemplo

```php
<?php

$string = 'A rápida raposa marrom pulou sobre o cão preguiçoso.';

$patterns   = array();
$patterns[] = '/rápida/';
$patterns[] = '/marrom/';
$patterns[] = '/raposa/';

$replacements   = array();
$replacements[] = 'lenta';
$replacements[] = 'preta';
$replacements[] = 'ursa';

echo preg_filter($patterns, $replacements, $string);
echo preg_replace($patterns, $replacements, $string);
```

As duas funções acima irão retornar a mesma string: `A lenta ursa preta pulou sobre o cão preguiçoso.`

## preg_grep

Retorna as entradas do array que combinaram com o padrão.

```php
preg_grep(string $padrao, array $entrada [, int $flags])
```

### `$padrao`

A string do padrão.

### `$entrada`

O vetor de entrada.

### `$flags`

Se usado  **`PREG_GREP_INVERT`**, esta função retorna os elementos do array de entrada que  não casam com o dado  `$padrao`.

### Valor retornado

Retorna um vetor consistindo dos elementos do vetor de  `$entrada`  que combinaram com o dado do  `$padrao`.

### Exemplo

```php
<?php

$array = [
	'João da Nica',
	'Azul 23',
	'12.13',
	1231212312,
	'email@conta.com.br',
	2456.31212,
	'R$ 1250.33',
];

// retorna todos os elementos do array contendo números de ponto flutuante
$fl_array = preg_grep("/^(\d+)?\.\d+$/", $array);
```

O vetor resultante será:
```php
array(size=2)
  2 => string '12.13' (length=5)
  5 => float 2456.31212
```

## preg_last_error

Retorna o código de erro da última regex PCRE executada.

```php
preg_last_error(void)
```

### Valores retornados
Retorna uma das seguintes constantes:

¹ Limite de backtracking da PCRE. Padrão em 100000 para PHP < 5.3.7.
² Limite de recursões da PCRE. Nota que se você definir este valor para um número bem alto poderá consumir toda a pilha de processo disponível e eventualmente travar o PHP (devido a alcançar o limite do tamanho da pilha imposto pelo Sistema Operacional).

```php
<?php  
  
preg_match('/(?:\D+|<\d+>)*[!?]/', 'foobar foobar foobar');  
  
if (preg_last_error() == PREG_BACKTRACK_LIMIT_ERROR) {  
print 'Backtrack limit was exhausted!';  
}

```

Esse código irá imprimir a seguinte mensagem:
`Backtrack limit was exhausted!`

## preg_match_all

Realiza uma procura global por expressão regular.

```php
int preg_match_all(string $padrao, string $sujeito [, array &$ocorrencias [,int $flags = PREG_PATTERN_ORDER [, int $offset = 0]]])
```

Procura todas as ocorrências do `$padrao` no `$sujeito` e coloca elas dentro de `$ocorrencias`, na ordem definida pela `$flag`.

### `$padrao`

String com o padrão para procurar.

### `$sujeito`

String para procurar.

### `$ocorrencias`

Vetor com todos as ocorrências do padrão, na ordem definida pela flag.

### `$flag`
 Pode ser usada uma das seguintes flags:

- **`PREG_PATTERN_ORDER`**
- **`PREG_SET_ORDER`**
- **`PREG_OFFSET_CAPTURE`**
- **`PREG_UNMATCHED_AS_NULL`**

Para informações detalhadas de cada uma das flag e ver alguns exemplos [acesso o site](http://php.net/manual/pt_BR/function.preg-match-all.php#refsect1-function.preg-match-all-parameters).

### `$offset`

O `$offset` pode ser usado para definir um início da procura diferente que o início da string. Ele é definido em bytes.

### Valor retornado

Retorna o número de correspondências completas de padrões (que podem ser zero) ou `FALSE` se um erro ocorreu.

### Exemplo

```php
<?php

$texto =
	"Cep antigo é 98534123. Lorem ipsum dolor sit amet, consectetur adipiscing
elit. Nullam faucibus justo et ligula gravida, quis facilisis mauris egestas.
Suspendisse ac dictum sapien. Sed dapibus est sed lorem vehicula varius. Maecenas
molestie pellentesque mauris id maximus. Etiam tincidunt accumsan erat vel pharetra.
Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos
himenaeos. Integer in leo in quam blandit pellentesque. Lorem ipsum dolor sit amet,
consectetur adipiscing elit. Meu cep é 95900-000";

$expressao_regular_obter_cep = "/\d{5}-?\d{3}/";

preg_match_all($expressao_regular_obter_cep, $texto, $ocorrencias);

```
O valor de `$ocorrências` é:

```php
array(size=1)
  0 => 
    array(size=2)
      0 => string '98534123' (length=8)
      1 => string '95900-000' (length=9)
```

## preg_match

Realiza uma procura por expressão regular.

```php
int preg_match(string $padrao, string $sujeito [, array &$ocorrencias [,int $flags = 0 [, int $offset = 0]]])
```

Procura uma ocorrência do `$padrao` no `$sujeito`.

### `$padrao`

String com o padrão para procurar.

### `$sujeito`

String para procurar.

### `$ocorrencias`

Se `$ocorrencias` for fornecido, então é preenchido com os resultados da busca.

`$ocorrencias[0]` conterá o texto que correspondeu ao padrão completo.
`$ocorrencias[1]` terá o texto que correspondeu ao primeiro subpadrão entre parênteses capturado. 
 Funciona da mesma maneira que o offset da função `substr()`.

### `$flag`

Pode ser usada uma das seguintes flags:

- **`PREG_OFFSET_CAPTURE`**
- **`PREG_UNMATCHED_AS_NULL`**

Para mais informações sobre a diferenças das flags [acesse o site](http://php.net/manual/pt_BR/function.preg-match.php#refsect1-function.preg-match-parameters).

### `$offset`

O `$offset` pode ser usado para definir um início da procura diferente que o início da string. Ele é definido em bytes.

### Valor retornado

Retorna 1 se o padrão corresponder a determinado assunto, 0 se não corresponder ou FALSE se um erro ocorrer.

### Exemplo

Encontrar uma palavra:

```php
<?php  
// A letra "i" depois do padrão indica uma busca sem case-insensitive
if (preg_match("/php/i", "PHP é a melhor linguagem web."))
{  
	echo "Ocorrência encontrada.";  
}
else
{
	echo "Ocorrência NÃO encontrada.";  
}

```

Encontrar um padrão:

```php
<?php

$texto = "Cep antigo é 98534123. Lorem ipsum dolor sit amet, consectetur adipiscing
elit. Nullam faucibus justo et ligula gravida, quis facilisis mauris egestas.
Suspendisse ac dictum sapien. Sed dapibus est sed lorem vehicula varius. Maecenas
molestie pellentesque mauris id maximus. Etiam tincidunt accumsan erat vel pharetra.
Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos
himenaeos. Integer in leo in quam blandit pellentesque. Lorem ipsum dolor sit amet,
consectetur adipiscing elit. Meu cep é 95900-000";

$expressao_regular_obter_cep = "/\d{5}-?\d{3}/";

preg_match($expressao_regular_obter_cep, $texto, $ocorrencias, PREG_UNMATCHED_AS_NULL);
```

O valor de `$ocorrências` é:

```php
array (size=1)
  0 => string '98534123' (length=8)
```

## preg_quote

Adiciona escape em caracteres da expressão regular.

```php
string preg_quote(string $str [, string $delimiter])
```

Pega `$str` e coloca uma barra invertida antes de cada caractere que é parte da sintaxe da expressão regular. Isto é útil se você tem uma string em tempo de execução que você precisa combinar em algum texto e a string pode conter caracteres especiais de regex.

Os caracteres especiais da expressão regular são  _. \ + * ? [ ^ ] $ ( ) { } = ! < > | :_

### `$str`

A string de entrada.

### `$delimiter`

Se o opcional `delimiter` é especificado, ele também terá escape antecedendo. Isto é útil para adicionar escape em delimitadores que é requerido pelas funções PCRE. A `/` é o delimitador mais comumente usado.

### Valor retornado

Retorna a string modificada.

### Exemplo

```php
<?php  
$keywords = 'R$40 por um quadro de  120/40';  
$keywords = preg_quote($keywords, '/');  
echo $keywords; // retorna R\$40 por um quadro de 120\/40

```

## # preg_replace_callback_array

Realiza uma busca em uma expressão e faz a substituição usando callbacks.

```php
mixed preg_replace_callback_array(
	array $padroes_e_callbacks,
	mixed $sujeito
	[, int  $limit = -1 [, int &$count]]
)
```

### `$padroes_e_callbacks`

Um vetor associado mapeando padrões (chaves) com as callbacks (valores).

### `$sujeito`

A string or um vetor com strings para procurar.

### `$limit`

As substituições máximas possíveis para cada padrão em cada sequência de assunto. O padrão é -1 (sem limite).

### `$count`

Se especificado, esta variável será preenchida com o número de substituições feitas

### Valor retornado

Retorna um vetor se o parâmetro `$sujeito` for um vetor, ou uma string caso contrário. Se ocorreram erros, o valor de retorno é NULL.

### Exemplo

```php
<?php
$subject = 'Aaaaaa Bbb';

preg_replace_callback_array(
    [
        '~[a]+~i' => function ($ocorrencia) {
			echo "Foram encontradas " . strlen($ocorrencia[0]) .  ' vezes a letra  "a"';
        },
        '~[b]+~i' => "countOcorrencias"
    ],
    $subject
);

function countOcorrencias($ocorrencia)
{
	echo "Foram encontradas " . strlen($ocorrencia[0]) .  ' vezes a letra  "b"';
}

```

O exemplo irá imprimir:
```
Foram encontradas 6 vezes a letra "a"  
Foram encontradas 3 vezes a letra "b"
```

## preg_split

Divide a string por uma expressão regular.

```php
preg_split(string $padrao, string $sujeito [, int $limit [, int $flags]])
```
### `$padrao`

O padrão a ser usado.

### `$sujeito`

A string de entrada.

### `$limit`

Se especificado, então somente  `$limit`  pedaços da string serão retornados, e se  `$limit`  for -1, significa "sem limite", que é útil quando especificando`$flags`.

### `$flags`

Pode ser uma combinação das seguintes flag:

**`PREG_SPLIT_NO_EMPTY`**

Se esta flag é usada, somente pedaços não vazios serão retornados pela  **preg_split()**.

**`PREG_SPLIT_DELIM_CAPTURE`**

Se esta flag é usada, expressão entre parênteses no padrão serão capturados e retornados também.

**`PREG_SPLIT_OFFSET_CAPTURE`**

Se esta flag é usada, para cada combinação o offset da string será também retornado. Note que isto modifica o valor de retorno em um array onde cada elemento é um array contendo a string combinada no índice  _0_  e o offset da mesma em  `$sujeito`  no índice  _1_.

### Valor retornado

Retorna um vetor contendo pedaços de strings de `$sujeito` divididos pelo que for combinado pelo `$padrao`.

### Exemplo

```php
<?php

// reparte a frase por número,vírgula ou espaço
// incluindo " ", \r, \t, \n e \f
$keywords = preg_split("/[\s,\d]+/", "hypertext language, programming texto,com,virgula abc123abc");

```
`$keywords` conterá:

```php
array(size=8)
  0 => string 'hypertext' (length=9)
  1 => string 'language' (length=8)
  2 => string 'programming' (length=11)
  3 => string 'texto' (length=5)
  4 => string 'com' (length=3)
  5 => string 'virgula' (length=7)
  6 => string 'abc' (length=3)
  7 => string 'abc' (length=3)
```

ARTIGOS

Expressões regulares no PHP

COMENTE SOBRE