preg_split

Introdução

preg_split() divide uma string em um array de substrings, usando uma expressão regular para descrever o delimitador. É a versão com suporte a regex de explode(): enquanto explode() só divide por uma string fixa, preg_split() pode dividir por um padrão — qualquer sequência de espaços em branco, um de vários caracteres de pontuação, uma fronteira de dígitos, etc.

Esta página cobre a assinatura da função, todas as flags, o valor de retorno e os padrões práticos (e armadilhas) que você encontrará ao usá-la em código real.

Sintaxe

preg_split(
    string $pattern,
    string $subject,
    int $limit = -1,
    int $flags = 0
): array|false

A função retorna um array de substrings em caso de sucesso, ou false se o padrão for inválido. Ela nunca lança exceções — verifique false (e consulte preg_last_error()) caso uma divisão possa falhar.

Um exemplo básico

Um caso de uso clássico é dividir uma string em um delimitador que varia — aqui, qualquer sequência de espaços em branco ou vírgulas:

O padrão [\s,]+ corresponde a um ou mais caracteres de espaço em branco ou vírgula, portanto tanto os espaços quanto a vírgula atuam como delimitadores:

Array
(
    [0] => This
    [1] => is
    [2] => a
    [3] => test
    [4] => string
)

Como + é guloso, delimitadores consecutivos (uma vírgula e um espaço) colapsam em um único ponto de divisão em vez de produzir partes vazias.

As flags

PREG_SPLIT_NO_EMPTY

Sem essa flag, um delimitador no início ou no final da string — ou dois delimitadores seguidos que o padrão não consegue mesclar — produz strings vazias no resultado. PREG_SPLIT_NO_EMPTY as remove:

<?php

$string = ',apple,,banana,';

// Without the flag: empty pieces appear.
print_r(preg_split('/,/', $string));

// With the flag: only real values remain.
print_r(preg_split('/,/', $string, -1, PREG_SPLIT_NO_EMPTY));

A primeira chamada retorna ['', 'apple', '', 'banana', '']; a segunda retorna ['apple', 'banana'].

PREG_SPLIT_DELIM_CAPTURE

Se o padrão contiver grupos de captura, essa flag inclui o texto capturado no resultado — útil quando você quer manter os delimitadores em vez de apenas descartá-los:

<?php

$expression = '3+5*2-9';
$tokens = preg_split('/([+\-*\/])/', $expression, -1, PREG_SPLIT_DELIM_CAPTURE);

print_r($tokens);

O resultado mantém tanto os números quanto os operadores: ['3', '+', '5', '*', '2', '-', '9'] — exatamente o que um pequeno tokenizador de expressões precisa.

PREG_SPLIT_OFFSET_CAPTURE

Cada elemento se torna um par [$substring, $offset], onde $offset é a posição em bytes na string original. Útil quando você precisa saber de onde cada parte veio.

Limitando o número de divisões

$limit define quantas partes você recebe; o elemento final mantém o restante da string sem dividir. Esta é a forma idiomática de dividir "os primeiros N campos e depois tudo mais":

<?php

$logLine = 'ERROR 2024-01-01 Something broke: details here';

// Split into at most 3 parts on whitespace.
$parts = preg_split('/\s+/', $logLine, 3);

print_r($parts);

Isso produz ['ERROR', '2024-01-01', 'Something broke: details here'] — o terceiro elemento mantém seus espaços internos porque o limite foi atingido.

preg_split() vs explode()

Use explode() quando o delimitador for uma única string fixa — é mais rápido e mais claro. Use preg_split() quando o delimitador for um padrão: espaços em branco variáveis, uma escolha de caracteres, correspondência sem distinção entre maiúsculas e minúsculas, ou quando você precisar manter os delimitadores via PREG_SPLIT_DELIM_CAPTURE. Para reunir um array de volta em uma string, use implode().

Armadilhas comuns

• Esquecer os delimitadores do padrão. O primeiro argumento é uma regex completa, portanto precisa de delimitadores: '/,/', não ','. Passar uma string simples é o erro mais comum para iniciantes.
• Caracteres especiais sem escape. Caracteres como ., +, | e * são metacaracteres de regex. Para dividir por um ponto literal, faça o escape ('/\./') ou use preg_quote() em entradas dinâmicas.
• Strings vazias inesperadas. Delimitadores no início/fim criam partes vazias — adicione PREG_SPLIT_NO_EMPTY se não quiser tê-las.

Funções relacionadas

• explode() — divide por um delimitador de string fixo.
• implode() — une um array de volta em uma string.
• preg_match() / preg_match_all() — encontra correspondências em vez de dividir.
• preg_replace() — substitui texto por padrão.

Prática