Capturas nomeadas em expressões regulares do PHP

Suponha que usando preg_match nós queiramos dividir uma data em dia, mês e ano. Vamos usar capturas para isso:

php<?php
  $str = '2025-10-29';
  $reg = '#(\d{4})-(\d{2})-(\d{2})#';
  
  preg_match($reg, $str, $match);
  var_dump($match); // retornará ['2025-10-29', '2025', '10', '29']
?>

Como você pode ver, como resultado obtemos um array, no qual no elemento zero estará a data completa, no primeiro - o ano, no segundo - o mês, no terceiro - o dia.

Às vezes, porém, seria conveniente obter o conteúdo das capturas na forma de um array associativo. Ou seja, no nosso caso, seria bom obter um array como este:

php[
  'year'  => '2025',
  'month' => '10',
  'day'   => '29'
]

Para isso, existe uma sintaxe especial em expressões regulares. Aqui está: (?<name>pattern), onde pattern - é a expressão regular, e name - é o nome da captura.

Vamos reescrever nossa expressão regular para a data usando capturas nomeadas:

php<?php
  $str = '2025-10-29';
  $reg = '#(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})#';
  
  preg_match($reg, $str, $match);
  var_dump($match);
?>

Como resultado, teremos um array associativo, no qual as chaves serão os nomes das capturas, e os valores - o que foi capturado por elas:

php[
  'year'  => '2025',
  'month' => '10',
  'day'   => '29',
]

Na verdade, no array com o resultado, os valores das capturas estarão disponíveis tanto pelo nome quanto pelo número ordinal. Ou seja, por exemplo, o ano estará disponível pela chave 'year' e pelo número 1, o mês - pela chave 'month' e pelo número 2 e assim por diante:

php[
  'year'  => '2025',
  'month' => '10',
  'day'   => '29',
  
  1       => '2025',
  2       => '10',
  3       => '29'
]

As capturas nomeadas descritas têm mais algumas sintaxes alternativas: (?P<name>pattern) e (?'name'pattern).

php<?php
  $str = '12:59:59';
?>