[DOC-CVS] [doc-en] master: ext/intl: Add IntlListFormatter class documentation (PHP 8.5) (#5692)
[email protected] (Louis-Arnaud via GitHub) Wed, 22 Jul 2026 20:20:09 +0000
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-07-22T22:20:06+02:00
Commit: https://github.com/php/doc-en/commit/e1b9f588815a51682acf68f9b8929f49ad612488
Raw diff: https://github.com/php/doc-en/commit/e1b9f588815a51682acf68f9b8929f49ad612488.diff
ext/intl: Add IntlListFormatter class documentation (PHP 8.5) (#5692)
Changed paths:
A reference/intl/intllistformatter.xml
A reference/intl/intllistformatter/construct.xml
A reference/intl/intllistformatter/format.xml
M appendices/migration85/new-classes.xml
M reference/intl/book.xml
Diff:
diff --git a/appendices/migration85/new-classes.xml b/appendices/migration85/new-classes.xml
index d47bed152f20..86fa4e0360c5 100644
--- a/appendices/migration85/new-classes.xml
+++ b/appendices/migration85/new-classes.xml
@@ -29,6 +29,13 @@
<!-- RFC: https://wiki.php.net/rfc/filter_throw_on_failure -->
</sect2>
+ <sect2 xml:id="migration85.new-classes.intl">
+ <title>Intl</title>
+ <simplelist>
+ <member><classname>IntlListFormatter</classname></member>
+ </simplelist>
+ </sect2>
+
<sect2 xml:id="migration85.new-classes.uri">
<title>URI</title>
<simplelist>
diff --git a/reference/intl/book.xml b/reference/intl/book.xml
index 611d0b91cf5f..664685fe385b 100644
--- a/reference/intl/book.xml
+++ b/reference/intl/book.xml
@@ -9,26 +9,26 @@
<!-- {{{ Preface -->
<preface xml:id="intro.intl">
&reftitle.intro;
- <para>
+ <simpara>
Internationalization extension (further is referred as Intl) is a wrapper
for <link xlink:href="&url.icu.home;">ICU</link>
library, enabling PHP programmers to perform various locale-aware operations including
but not limited to formatting, transliteration, encoding conversion, calendar operations,
<link xlink:href="&url.icu.uca;">UCA</link>-conformant collation, locating
text boundaries and working with locale identifiers, timezones and graphemes.
- </para>
+ </simpara>
- <para>
+ <simpara>
It tends to closely follow ICU APIs, so that people having experience
working with ICU in either C/C++ or Java could easily use the PHP API.
Also, this way ICU documentation would be useful to understand various ICU
functions.
- </para>
+ </simpara>
- <para>
+ <simpara>
Intl consists of several modules, each of them exposes the corresponding
ICU API:
- </para>
+ </simpara>
<itemizedlist>
<listitem>
@@ -98,13 +98,13 @@
<title>Links</title>
<itemizedlist>
<listitem>
- <para><link xlink:href="&url.icu.docs;">Miscellaneous ICU docs</link></para>
+ <simpara><link xlink:href="&url.icu.docs;">Miscellaneous ICU docs</link></simpara>
</listitem>
<listitem>
- <para><link xlink:href="&url.icu.userguide;">ICU User Guide</link></para>
+ <simpara><link xlink:href="&url.icu.userguide;">ICU User Guide</link></simpara>
</listitem>
<listitem>
- <para><link xlink:href="&url.icu.uca;">Unicode Collation Algorithm</link></para>
+ <simpara><link xlink:href="&url.icu.uca;">Unicode Collation Algorithm</link></simpara>
</listitem>
</itemizedlist>
</section>
@@ -133,6 +133,7 @@
&reference.intl.intlrulebasedbreakiterator;
&reference.intl.intlcodepointbreakiterator;
&reference.intl.intldatepatterngenerator;
+ &reference.intl.intllistformatter;
&reference.intl.intlpartsiterator;
&reference.intl.uconverter;
diff --git a/reference/intl/intllistformatter.xml b/reference/intl/intllistformatter.xml
new file mode 100644
index 000000000000..fc5884527796
--- /dev/null
+++ b/reference/intl/intllistformatter.xml
@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<reference xml:id="class.intllistformatter" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>The IntlListFormatter class</title>
+ <titleabbrev>IntlListFormatter</titleabbrev>
+
+ <partintro>
+
+ <!-- {{{ IntlListFormatter intro -->
+ <section xml:id="intllistformatter.intro">
+ &reftitle.intro;
+ <simpara>
+ Formats, orders, and punctuates a list of items according to locale-specific rules.
+ Requires ICU 67 or later.
+ </simpara>
+ </section>
+ <!-- }}} -->
+
+ <section xml:id="intllistformatter.synopsis">
+ &reftitle.classsynopsis;
+
+ <!-- {{{ Synopsis -->
+ <classsynopsis class="class">
+ <ooclass>
+ <classname>IntlListFormatter</classname>
+ </ooclass>
+
+ <classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname linkend="intllistformatter.constants.type-and">IntlListFormatter::TYPE_AND</varname>
+ </fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname linkend="intllistformatter.constants.type-or">IntlListFormatter::TYPE_OR</varname>
+ </fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname linkend="intllistformatter.constants.type-units">IntlListFormatter::TYPE_UNITS</varname>
+ </fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname linkend="intllistformatter.constants.width-wide">IntlListFormatter::WIDTH_WIDE</varname>
+ </fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname linkend="intllistformatter.constants.width-short">IntlListFormatter::WIDTH_SHORT</varname>
+ </fieldsynopsis>
+ <fieldsynopsis>
+ <modifier>public</modifier>
+ <modifier>const</modifier>
+ <type>int</type>
+ <varname linkend="intllistformatter.constants.width-narrow">IntlListFormatter::WIDTH_NARROW</varname>
+ </fieldsynopsis>
+
+ <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.intllistformatter')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='IntlListFormatter'])">
+ <xi:fallback/>
+ </xi:include>
+ <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.intllistformatter')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='IntlListFormatter'])">
+ <xi:fallback/>
+ </xi:include>
+ </classsynopsis>
+ <!-- }}} -->
+
+ </section>
+
+ <section xml:id="intllistformatter.constants">
+ &reftitle.constants;
+ <variablelist>
+ <varlistentry xml:id="intllistformatter.constants.type-and">
+ <term><constant>IntlListFormatter::TYPE_AND</constant></term>
+ <listitem>
+ <simpara>
+ Formats a list using conjunction (e.g. "A, B, and C").
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="intllistformatter.constants.type-or">
+ <term><constant>IntlListFormatter::TYPE_OR</constant></term>
+ <listitem>
+ <simpara>
+ Formats a list using disjunction (e.g. "A, B, or C").
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="intllistformatter.constants.type-units">
+ <term><constant>IntlListFormatter::TYPE_UNITS</constant></term>
+ <listitem>
+ <simpara>
+ Formats a list of units (e.g. "3 ft, 7 in").
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="intllistformatter.constants.width-wide">
+ <term><constant>IntlListFormatter::WIDTH_WIDE</constant></term>
+ <listitem>
+ <simpara>
+ Uses the widest (most verbose) list format, typically with conjunctions spelled out in full.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="intllistformatter.constants.width-short">
+ <term><constant>IntlListFormatter::WIDTH_SHORT</constant></term>
+ <listitem>
+ <simpara>
+ Uses a short list format, typically using abbreviations.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry xml:id="intllistformatter.constants.width-narrow">
+ <term><constant>IntlListFormatter::WIDTH_NARROW</constant></term>
+ <listitem>
+ <simpara>
+ Uses the narrowest list format, with minimal punctuation.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section role="changelog" xml:id="intllistformatter.changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.5.0</entry>
+ <entry>
+ The class was added.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ </partintro>
+
+ &reference.intl.entities.intllistformatter;
+
+</reference>
+<!-- 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:"~/.phpdoc/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
+-->
diff --git a/reference/intl/intllistformatter/construct.xml b/reference/intl/intllistformatter/construct.xml
new file mode 100644
index 000000000000..e80d7d8d28b1
--- /dev/null
+++ b/reference/intl/intllistformatter/construct.xml
@@ -0,0 +1,115 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="intllistformatter.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>IntlListFormatter::__construct</refname>
+ <refpurpose>Creates a new IntlListFormatter instance</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <constructorsynopsis role="IntlListFormatter">
+ <modifier>public</modifier> <methodname>IntlListFormatter::__construct</methodname>
+ <methodparam><type>string</type><parameter>locale</parameter></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer><constant>IntlListFormatter::TYPE_AND</constant></initializer></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter>width</parameter><initializer><constant>IntlListFormatter::WIDTH_WIDE</constant></initializer></methodparam>
+ </constructorsynopsis>
+ <simpara>
+ Creates a new <classname>IntlListFormatter</classname> instance for the given locale.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <variablelist>
+ <varlistentry>
+ <term><parameter>locale</parameter></term>
+ <listitem>
+ <simpara>
+ The locale to use for formatting.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem>
+ <simpara>
+ The list type. One of the <constant>IntlListFormatter::TYPE_<replaceable>*</replaceable></constant> constants:
+ <constant>IntlListFormatter::TYPE_AND</constant>,
+ <constant>IntlListFormatter::TYPE_OR</constant>, or
+ <constant>IntlListFormatter::TYPE_UNITS</constant>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>width</parameter></term>
+ <listitem>
+ <simpara>
+ The list width. One of the <constant>IntlListFormatter::WIDTH_<replaceable>*</replaceable></constant> constants:
+ <constant>IntlListFormatter::WIDTH_WIDE</constant>,
+ <constant>IntlListFormatter::WIDTH_SHORT</constant>, or
+ <constant>IntlListFormatter::WIDTH_NARROW</constant>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="errors">
+ &reftitle.errors;
+ <simpara>
+ Throws an <exceptionname>IntlException</exceptionname> if the formatter cannot be created
+ (e.g. invalid locale or ICU version is below 67).
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+ &reftitle.changelog;
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>&Version;</entry>
+ <entry>&Description;</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>8.5.0</entry>
+ <entry>
+ The class was added.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>IntlListFormatter::format</methodname></member>
+ </simplelist>
+ </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:"~/.phpdoc/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
+-->
diff --git a/reference/intl/intllistformatter/format.xml b/reference/intl/intllistformatter/format.xml
new file mode 100644
index 000000000000..a26abe885a96
--- /dev/null
+++ b/reference/intl/intllistformatter/format.xml
@@ -0,0 +1,88 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="intllistformatter.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+ <refname>IntlListFormatter::format</refname>
+ <refpurpose>Format a list of items</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis role="IntlListFormatter">
+ <modifier>public</modifier> <type class="union"><type>string</type><type>false</type></type><methodname>IntlListFormatter::format</methodname>
+ <methodparam><type>array</type><parameter>list</parameter></methodparam>
+ </methodsynopsis>
+ <simpara>
+ Formats a list of items as a locale-appropriate string.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <variablelist>
+ <varlistentry>
+ <term><parameter>list</parameter></term>
+ <listitem>
+ <simpara>
+ An array of strings to format as a list.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <simpara>
+ The formatted list as a string, or &false; on failure.
+ </simpara>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title><methodname>IntlListFormatter::format</methodname> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$fmt = new IntlListFormatter('en_US', IntlListFormatter::TYPE_AND, IntlListFormatter::WIDTH_WIDE);
+echo $fmt->format(['one', 'two', 'three']);
+// one, two, and three
+
+$fmt = new IntlListFormatter('en_US', IntlListFormatter::TYPE_OR, IntlListFormatter::WIDTH_WIDE);
+echo $fmt->format(['one', 'two', 'three']);
+// one, two, or three
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <simplelist>
+ <member><methodname>IntlListFormatter::__construct</methodname></member>
+ </simplelist>
+ </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:"~/.phpdoc/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
+-->