<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.22 $ -->
<refentry id="function.preg-match-all">
<refnamediv>
<refname>preg_match_all</refname>
<refpurpose>Perform a global regular expression match</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<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>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>pattern</parameter></term>
<listitem>
<para>
The pattern to search for, as a string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>subject</parameter></term>
<listitem>
<para>
The input string.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>matches</parameter></term>
<listitem>
<para>
In this case, $matches[0] is the first set of matches, and
<varname>$matches[0][0]</varname> has text matched by full pattern,
<varname>$matches[0][1]</varname> has text matched by first
subpattern and so on. Similarly, <varname>$matches[1]</varname> is
the second set of matches, etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>flags</parameter></term>
<listitem>
<para>
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><constant>PREG_PATTERN_ORDER</constant></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>
&example.outputs;
<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><constant>PREG_SET_ORDER</constant></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>
&example.outputs;
<screen role="html">
<![CDATA[
<b>example: </b>, example:
<div align="left">this is a test</div>, this is a test
]]>
</screen>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>PREG_OFFSET_CAPTURE</constant></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 value of
<parameter>matches</parameter> 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>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
If no order flag is given, <constant>PREG_PATTERN_ORDER</constant> is
assumed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<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.
</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>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns the number of full pattern matches (which might be zero),
or &false; if an error occurred.
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>4.3.3</entry>
<entry>
The <parameter>offset</parameter> parameter was added
</entry>
</row>
<row>
<entry>4.3.0</entry>
<entry>
The <constant>PREG_OFFSET_CAPTURE</constant> flag was added
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<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>
&example.outputs;
<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>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>preg_match</function></member>
<member><function>preg_replace</function></member>
<member><function>preg_split</function></member>
</simplelist>
</para>
</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
-->