<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- splitted from ./en/functions/pcre.xml, last change in rev 1.2 -->
<refentry id="function.preg-match-all">
<refnamediv>
<refname>preg_match_all</refname>
<refpurpose>Perform a global regular expression match</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>preg_match_all</methodname>
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam><type>string</type><parameter>subject</parameter></methodparam>
<methodparam><type>array</type><parameter role="reference">matches</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Searches <parameter>subject</parameter> for all matches to the regular
expression given in <parameter>pattern</parameter> and puts them in
<parameter>matches</parameter> in the order specified by
<parameter>flags</parameter>.
</para>
<para>
After the first match is found, the subsequent searches are continued
on from end of the last match.
</para>
<para>
<parameter>flags</parameter> can be a combination of the following flags
(note that it doesn't make sense to use
<constant>PREG_PATTERN_ORDER</constant> together with
<constant>PREG_SET_ORDER</constant>):
<variablelist>
<varlistentry>
<term>PREG_PATTERN_ORDER</term>
<listitem>
<para>
Orders results so that $matches[0] is an array of full
pattern matches, $matches[1] is an array of strings matched by
the first parenthesized subpattern, and so on.
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
"<b>example: </b><div align=left>this is a test</div>",
$out, PREG_PATTERN_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>
]]>
</programlisting>
<para>
This example will produce:
</para>
<screen role="html">
<![CDATA[
<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test
]]>
</screen>
<para>
So, $out[0] contains array of strings that matched full pattern,
and $out[1] contains array of strings enclosed by tags.
</para>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PREG_SET_ORDER</term>
<listitem>
<para>
Orders results so that $matches[0] is an array of first set
of matches, $matches[1] is an array of second set of matches,
and so on.
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
"<b>example: </b><div align=\"left\">this is a test</div>",
$out, PREG_SET_ORDER);
echo $out[0][0] . ", " . $out[0][1] . "\n";
echo $out[1][0] . ", " . $out[1][1] . "\n";
?>
]]>
</programlisting>
<para>
This example will produce:
</para>
<screen role="html">
<![CDATA[
<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test
]]>
</screen>
</informalexample>
</para>
<para>
In this case, $matches[0] is the first set of matches, and
$matches[0][0] has text matched by full pattern, $matches[0][1]
has text matched by first subpattern and so on. Similarly,
$matches[1] is the second set of matches, etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PREG_OFFSET_CAPTURE</term>
<listitem>
<para>
If this flag is passed, for every occurring match the appendant string
offset will also be returned. Note that this changes the return
value in an array where every element is an array consisting of the
matched string at offset <literal>0</literal> and its string offset
into <parameter>subject</parameter> at offset <literal>1</literal>.
This flag is available since PHP 4.3.0 .
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
If no order flag is given, <constant>PREG_PATTERN_ORDER</constant> is
assumed.
</para>
<para>
Normally, the search starts from the beginning of the subject string. The
optional parameter <parameter>offset</parameter> can be used to specify
the alternate place from which to start the search.
The <parameter>offset</parameter> parameter is available since
PHP 4.3.3.
</para>
<note>
<para>
Using <parameter>offset</parameter> is not equivalent to
passing <literal>substr($subject, $offset)</literal> to
<function>preg_match_all</function> in place of the subject string, because
<parameter>pattern</parameter> can contain assertions such as
<emphasis>^</emphasis>, <emphasis>$</emphasis> or
<emphasis>(?<=x)</emphasis>. See <function>preg_match</function> for
examples.
</para>
</note>
<para>
Returns the number of full pattern matches (which might be zero),
or &false; if an error occurred.
</para>
<para>
<example>
<title>Getting all phone numbers out of some text.</title>
<programlisting role="php">
<![CDATA[
<?php
preg_match_all("/\(? (\d{3})? \)? (?(1) [\-\s] ) \d{3}-\d{4}/x",
"Call 555-1212 or 1-800-555-1212", $phones);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Find matching HTML tags (greedy)</title>
<programlisting role="php">
<![CDATA[
<?php
// The \\2 is an example of backreferencing. This tells pcre that
// it must match the second set of parentheses in the regular expression
// itself, which would be the ([\w]+) in this case. The extra backslash is
// required because the string is in double quotes.
$html = "<b>bold text</b><a href=howdy.html>click me</a>";
preg_match_all("/(<([\w]+)[^>]*>)(.*)(<\/\\2>)/", $html, $matches, PREG_SET_ORDER);
foreach ($matches as $val) {
echo "matched: " . $val[0] . "\n";
echo "part 1: " . $val[1] . "\n";
echo "part 2: " . $val[3] . "\n";
echo "part 3: " . $val[4] . "\n\n";
}
?>
]]>
</programlisting>
<para>
This example will produce:
</para>
<screen role="html">
<![CDATA[
matched: <b>bold text</b>
part 1: <b>
part 2: bold text
part 3: </b>
matched: <a href=howdy.html>click me</a>
part 1: <a href=howdy.html>
part 2: click me
part 3: </a>
]]>
</screen>
</example>
</para>
<simpara>
See also <function>preg_match</function>,
<function>preg_replace</function>,
and <function>preg_split</function>.
</simpara>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->