From 1e4fac8adf3ce312c2e3bbebd38e188d215d7916 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Wed, 24 Sep 2025 20:56:19 +0100
Subject: [PATCH 1/3] DateTimeZone::listIdentifiers improvements

---
 .../datetime/datetimezone/listidentifiers.xml | 47 ++++++++++++-------
 1 file changed, 30 insertions(+), 17 deletions(-)

diff --git a/reference/datetime/datetimezone/listidentifiers.xml b/reference/datetime/datetimezone/listidentifiers.xml
index 1dda356bb724..63630b258078 100644
--- a/reference/datetime/datetimezone/listidentifiers.xml
+++ b/reference/datetime/datetimezone/listidentifiers.xml
@@ -20,6 +20,18 @@
    <methodparam choice="opt"><type>int</type><parameter>timezoneGroup</parameter><initializer>DateTimeZone::ALL</initializer></methodparam>
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>countryCode</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
+  <para>
+   Return the list of <link xlink:href="https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones">IANA Time Zone identifiers</link>.
+  </para>
+
+  <note>
+   <para>
+    It's possible to detect the client (browser) timezone with JavaScript using
+    <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone">Intl.DateTimeFormat</link>
+    or <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets">Temporal.ZonedDateTime</link>.
+   </para>
+  </note>
+
  </refsect1>
 
  <refsect1 role="parameters">
@@ -96,25 +108,29 @@
   &reftitle.examples;
   <para>
    <example>
-    <title>A <methodname>DateTimeZone::listIdentifiers</methodname> example</title>
-    <programlisting role="php">
+    <title>List identifiers with location comments</title>
+    <programlisting role="php" annotations="interactive">
 <![CDATA[
 <?php
-$timezone_identifiers = DateTimeZone::listIdentifiers();
-for ($i=0; $i < 5; $i++) {
-    echo "$timezone_identifiers[$i]\n";
+$identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);
+
+foreach ($identifiers as $tzid) {
+    $tz = new DateTimeZone($tzid);
+    $comments = $tz->getLocation()['comments'];
+    echo $tzid . " (" . ($comments ?: 'Whole region') . ")\n";
 }
-?>
 ]]>
     </programlisting>
     &example.outputs.similar;
     <screen>
 <![CDATA[
-Africa/Abidjan
-Africa/Accra
-Africa/Addis_Ababa
-Africa/Algiers
-Africa/Asmara
+// (Output omitted due to length)
+America/Antigua (Whole region)
+America/Araguaina (Tocantins)
+America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
+America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
+America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
+// (Output omitted due to length)
 ]]>
     </screen>
    </example>
@@ -123,14 +139,13 @@ Africa/Asmara
   <para>
    <example>
     <title>Listing identifiers for a specific region</title>
-    <programlisting role="php">
+    <programlisting role="php" annotations="interactive">
 <![CDATA[
 <?php
 $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
 for ($i=0; $i < 5; $i++) {
     echo "$timezone_identifiers[$i]\n";
 }
-?>
 ]]>
     </programlisting>
     &example.outputs.similar;
@@ -149,12 +164,11 @@ Asia/Aqtau
   <para>
    <example>
     <title>Listing identifiers for multiple regions</title>
-    <programlisting role="php">
+    <programlisting role="php" annotations="interactive">
 <![CDATA[
 <?php
 $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
 echo join( ', ', $timezone_identifiers );
-?>
 ]]>
     </programlisting>
     &example.outputs.similar;
@@ -194,14 +208,13 @@ Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis
   <para>
    <example>
     <title>Listing identifiers for a single country</title>
-    <programlisting role="php">
+    <programlisting role="php" annotations="interactive">
 <![CDATA[
 <?php
 $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );
 foreach( $timezone_identifiers as $identifier ) {
     echo "$identifier\n";
 }
-?>
 ]]>
     </programlisting>
     &example.outputs.similar;

From cc79d5bfabba3fbbe1dfcc8dceef8c1b14ace3c6 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sat, 27 Sep 2025 09:48:33 +0100
Subject: [PATCH 2/3] DateTimeZone::listIdentifiers improvements

---
 reference/datetime/datetimezone/listidentifiers.xml | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/reference/datetime/datetimezone/listidentifiers.xml b/reference/datetime/datetimezone/listidentifiers.xml
index 63630b258078..d0917c69dbc5 100644
--- a/reference/datetime/datetimezone/listidentifiers.xml
+++ b/reference/datetime/datetimezone/listidentifiers.xml
@@ -21,14 +21,14 @@
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>countryCode</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Return the list of <link xlink:href="https://en.wikipedia.org/wiki/Tz_database#Names_of_timezones">IANA Time Zone identifiers</link>.
+   Return the list of <link xlink:href="&url.wiki.tzdb.names;">IANA Time Zone identifiers</link>.
   </para>
 
   <note>
    <para>
     It's possible to detect the client (browser) timezone with JavaScript using
-    <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone">Intl.DateTimeFormat</link>
-    or <link xlink:href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets">Temporal.ZonedDateTime</link>.
+    <link xlink:href="&url.js.intl-datetimeformat;">Intl.DateTimeFormat</link> or
+    <link xlink:href="&url.js.temporal-zoneddatetime;">Temporal.ZonedDateTime</link>.
    </para>
   </note>
 
@@ -124,13 +124,12 @@ foreach ($identifiers as $tzid) {
     &example.outputs.similar;
     <screen>
 <![CDATA[
-// (Output omitted due to length)
 America/Antigua (Whole region)
 America/Araguaina (Tocantins)
 America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
 America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
 America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
-// (Output omitted due to length)
+// (Output trimmed due to length)
 ]]>
     </screen>
    </example>

From 4f9d30dd613fe1e0ed54e72180f5c8f18b898b14 Mon Sep 17 00:00:00 2001
From: AllenJB <AllenJB@users.noreply.github.com>
Date: Sun, 28 Sep 2025 18:20:05 +0100
Subject: [PATCH 3/3] DateTimeZone::listIdentifiers improvements (removed
 runnable annotations - see #4887 )

---
 reference/datetime/datetimezone/listidentifiers.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/reference/datetime/datetimezone/listidentifiers.xml b/reference/datetime/datetimezone/listidentifiers.xml
index d0917c69dbc5..2904398d3514 100644
--- a/reference/datetime/datetimezone/listidentifiers.xml
+++ b/reference/datetime/datetimezone/listidentifiers.xml
@@ -109,7 +109,7 @@
   <para>
    <example>
     <title>List identifiers with location comments</title>
-    <programlisting role="php" annotations="interactive">
+    <programlisting role="php">
 <![CDATA[
 <?php
 $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);
@@ -138,7 +138,7 @@ America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF
   <para>
    <example>
     <title>Listing identifiers for a specific region</title>
-    <programlisting role="php" annotations="interactive">
+    <programlisting role="php">
 <![CDATA[
 <?php
 $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA );
@@ -163,7 +163,7 @@ Asia/Aqtau
   <para>
    <example>
     <title>Listing identifiers for multiple regions</title>
-    <programlisting role="php" annotations="interactive">
+    <programlisting role="php">
 <![CDATA[
 <?php
 $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::ASIA | DateTimeZone::PACIFIC );
@@ -207,7 +207,7 @@ Pacific/Tarawa, Pacific/Tongatapu, Pacific/Wake, Pacific/Wallis
   <para>
    <example>
     <title>Listing identifiers for a single country</title>
-    <programlisting role="php" annotations="interactive">
+    <programlisting role="php">
 <![CDATA[
 <?php
 $timezone_identifiers = DateTimeZone::listIdentifiers( DateTimeZone::PER_COUNTRY, "UA" );