Skip to content

Add IntlListFormatter class documentation (PHP 8.5) #5692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jordikroon merged 3 commits into from
Jul 22, 2026
Merged

Add IntlListFormatter class documentation (PHP 8.5) #5692

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
39928fd
feat(intl): ajoute la documentation de la classe IntlListFormatter (P…
lacatoire Jul 10, 2026
8b19aca
Apply DocBook style check: para->simpara, exceptionname
lacatoire Jul 10, 2026
5ffc64c
Unwrap simplelist from para in seealso
lacatoire Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions appendices/migration85/new-classes.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
19 changes: 10 additions & 9 deletions reference/intl/book.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -133,6 +133,7 @@
&reference.intl.intlrulebasedbreakiterator;
&reference.intl.intlcodepointbreakiterator;
&reference.intl.intldatepatterngenerator;
&reference.intl.intllistformatter;
&reference.intl.intlpartsiterator;
&reference.intl.uconverter;

Expand Down
178 changes: 178 additions & 0 deletions reference/intl/intllistformatter.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
-->
115 changes: 115 additions & 0 deletions reference/intl/intllistformatter/construct.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
-->
Loading