php-doc-en/reference/pcre/functions/preg-match-all.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- 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>matches</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>order</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>order</parameter>.
    </para>
    <para>
     After the first match is found, the subsequent searches  are continued
     on from end of the last match.
    </para>
    <para>
     <parameter>order</parameter> can be one of two things:
     <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.
         <informalexample>
          <programlisting role="php">
<![CDATA[
preg_match_all ("|<[^>]+>(.*)</[^>]+>|U", 
    "<b>example: </b><div align=left>this is a test</div>", 
    $out, PREG_PATTERN_ORDER);
print $out[0][0].", ".$out[0][1]."\n";
print $out[1][0].", ".$out[1][1]."\n";
]]>
          </programlisting>
          <para>
           This example will produce:
           <screen>
<![CDATA[
<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test
]]>
           </screen>
           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[
preg_match_all ("|<[^>]+>(.*)</[^>]+>|U", 
    "<b>example: </b><div align=left>this is a test</div>", 
    $out, PREG_SET_ORDER);
print $out[0][0].", ".$out[0][1]."\n";
print $out[1][0].", ".$out[1][1]."\n";
]]>
          </programlisting>
         </informalexample>
         This example will produce:
         <informalexample>
          <programlisting role="php">
<![CDATA[
<b>example: </b>, example: 
<div align=left>this is a test</div>, this is a test
]]>
          </programlisting>
         </informalexample>
         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>
     </variablelist>
    </para>
    <para>
     If <parameter>order</parameter> is not specified, it is assumed
     to be PREG_PATTERN_ORDER.
    </para>
    <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[
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[
// 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);

for ($i=0; $i< count($matches[0]); $i++) {
  echo "matched: ".$matches[0][$i]."\n";
  echo "part 1: ".$matches[1][$i]."\n";
  echo "part 2: ".$matches[3][$i]."\n";
  echo "part 3: ".$matches[4][$i]."\n\n";
}
]]>
      </programlisting>
     </example>
     This example will produce:
     <programlisting>
<![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>
]]>
     </programlisting>
    </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
-->