From 7c3e709daf8f3a6934648d84128a6664f211c64f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=AD=A6=E7=94=B0=20=E6=86=B2=E5=A4=AA=E9=83=8E?=
 <takeda@youmind.jp>
Date: Thu, 29 Oct 2026 23:11:32 +0900
Subject: [PATCH] =?UTF-8?q?intl=20=E3=82=92=E5=8E=9F=E6=96=87=E3=81=AE?=
 =?UTF-8?q?=E5=A4=89=E6=9B=B4=E3=81=AB=E8=BF=BD=E5=BE=93=20(4=E3=83=95?=
 =?UTF-8?q?=E3=82=A1=E3=82=A4=E3=83=AB)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 reference/intl/collator/set-strength.xml     | 67 +++++++++++++++++++-
 reference/intl/grapheme/grapheme-extract.xml | 32 +++++++---
 reference/intl/grapheme/grapheme-strlen.xml  | 36 ++++++++++-
 reference/intl/grapheme/grapheme-strpos.xml  | 53 +++++++++++++++-
 4 files changed, 174 insertions(+), 14 deletions(-)

diff --git a/reference/intl/collator/set-strength.xml b/reference/intl/collator/set-strength.xml
index 74c93d3cfd..609d21ec98 100644
--- a/reference/intl/collator/set-strength.xml
+++ b/reference/intl/collator/set-strength.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: e290572f2599305beb62b13988024b5da187979d Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
 <refentry xml:id="collator.setstrength" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>Collator::setStrength</refname>
@@ -205,7 +205,7 @@ $arr  = array( 'aò', 'Ao', 'ao' );
 $coll = collator_create( 'en_US' );
 
 // デフォルトの強度で配列を並べ替えます
-collator_sort( $coll, $arr ); 
+collator_sort( $coll, $arr );
 var_export( $arr );
 
 // 第一段階の強度で配列を並べ替えます
@@ -228,6 +228,68 @@ array (
   1 => 'Ao',
   2 => 'ao',
 )
+]]>
+    </screen>
+   </example>
+   <example>
+    <title>Unicode ロケール拡張のキー <literal>ks</literal> で強度を設定する</title>
+    <simpara>
+     照合強度は、<classname>Collator</classname> の生成時に、ロケール識別子の中で
+     Unicode ロケール拡張のキー <literal>ks</literal> を使って設定することもできます。
+     <literal>ks</literal> の値と <classname>Collator</classname>
+     の定数の対応は次のとおりです。
+    </simpara>
+    <informaltable>
+     <tgroup cols="2">
+      <thead>
+       <row>
+        <entry>ロケールキーの値</entry>
+        <entry>Collator の定数</entry>
+       </row>
+      </thead>
+      <tbody>
+       <row><entry><literal>ks-level1</literal></entry><entry><constant>Collator::PRIMARY</constant></entry></row>
+       <row><entry><literal>ks-level2</literal></entry><entry><constant>Collator::SECONDARY</constant></entry></row>
+       <row><entry><literal>ks-level3</literal></entry><entry><constant>Collator::TERTIARY</constant></entry></row>
+       <row><entry><literal>ks-level4</literal></entry><entry><constant>Collator::QUATERNARY</constant></entry></row>
+       <row><entry><literal>ks-identic</literal></entry><entry><constant>Collator::IDENTICAL</constant></entry></row>
+      </tbody>
+     </tgroup>
+    </informaltable>
+    <simpara>
+     <constant>Collator::DEFAULT_STRENGTH</constant> に相当する <literal>ks-*</literal>
+     の値はありません。この強度にするには <function>collator_set_strength</function>
+     を使う必要があります。
+    </simpara>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$textStyle  = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (テキスト表示の異体字セレクタ)
+$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (絵文字表示の異体字セレクタ)
+
+// デフォルトの Collator (強度は TERTIARY): 異体字セレクタは無視されます
+$collDefault = new Collator('en_US');
+var_dump($collDefault->compare($textStyle, $emojiStyle) === 0); // bool(true)
+
+// setStrength() で一致段階の強度を設定します
+$coll1 = new Collator('en_US');
+$coll1->setStrength(Collator::IDENTICAL);
+var_dump($coll1->compare($textStyle, $emojiStyle) === 0); // bool(false)
+
+// ロケール拡張のキー ks で一致段階の強度を設定しても同じです
+$coll2 = new Collator('en_US-u-ks-identic');
+var_dump($coll2->compare($textStyle, $emojiStyle) === 0); // bool(false)
+
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+bool(true)
+bool(false)
+bool(false)
 ]]>
     </screen>
    </example>
@@ -240,6 +302,7 @@ array (
    <simplelist>
     <member><link linkend="intl.collator-constants">Collator の定数</link></member>
     <member><function>collator_get_strength</function></member>
+    <member><function>collator_create</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/intl/grapheme/grapheme-extract.xml b/reference/intl/grapheme/grapheme-extract.xml
index d77880ab8b..8fb8c21a80 100644
--- a/reference/intl/grapheme/grapheme-extract.xml
+++ b/reference/intl/grapheme/grapheme-extract.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 2245ff665ae4b3037728ee52c247b409ad75de35 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
 <refentry xml:id="function.grapheme-extract" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_extract</refname>
@@ -52,12 +52,24 @@
       </para>
        <para>
         <simplelist>
-         <member>GRAPHEME_EXTR_COUNT (デフォルト) - <parameter>size</parameter> は、
+         <member><constant>GRAPHEME_EXTR_COUNT</constant> (デフォルト) - <parameter>size</parameter> は、
          抽出するデフォルト書記素クラスタの数です。</member>
-         <member>GRAPHEME_EXTR_MAXBYTES - <parameter>size</parameter> は、返すバイト数の最大値です。</member>
-         <member>GRAPHEME_EXTR_MAXCHARS - <parameter>size</parameter> は、返す UTF-8 文字数の最大値です。</member>
+         <member><constant>GRAPHEME_EXTR_MAXBYTES</constant> - <parameter>size</parameter> は、返すバイト数の最大値です。</member>
+         <member><constant>GRAPHEME_EXTR_MAXCHARS</constant> - <parameter>size</parameter> は、返す UTF-8 文字数の最大値です。</member>
         </simplelist>
        </para>
+      <caution>
+       <simpara>
+        <constant>GRAPHEME_EXTR_COUNT</constant> が制限するのは書記素クラスタ (見た目上の単位) の数であり、
+        バイト数ではありません。ひとつの書記素クラスタが多数のバイトにまたがることがあります。
+        たとえば、ZWJ シーケンスで構成された家族の絵文字 (<literal>👨‍👩‍👧‍👦</literal>) は、
+        書記素クラスタとしてはひとつですが 25 バイトあります。
+        取り出す文字列をバイト数の上限に収める必要がある場合は、
+        代わりに <constant>GRAPHEME_EXTR_MAXBYTES</constant> を使ってください。
+        <constant>GRAPHEME_EXTR_MAXBYTES</constant> は、書記素クラスタを途中で切らずに、上限に収まる分だけを返します。
+        ただし、最初の書記素クラスタだけで上限を超える場合は空文字列を返します。
+       </simpara>
+      </caution>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -149,11 +161,13 @@ o%CC%88
   <para>
    <simplelist>
     <member><function>grapheme_substr</function></member>
-     <member>
-      <link xlink:href="&uri.unicode.graphemes;">
-       Unicode Text Segmentation: Grapheme Cluster Boundaries
-      </link>
-     </member>
+    <member><function>grapheme_strlen</function></member>
+    <member><function>grapheme_strpos</function></member>
+    <member>
+     <link xlink:href="&uri.unicode.graphemes;">
+      Unicode Text Segmentation: Grapheme Cluster Boundaries
+     </link>
+    </member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/intl/grapheme/grapheme-strlen.xml b/reference/intl/grapheme/grapheme-strlen.xml
index 00da1a65b3..13cb74e224 100644
--- a/reference/intl/grapheme/grapheme-strlen.xml
+++ b/reference/intl/grapheme/grapheme-strlen.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: e7d502fecc2e84d4c57e6451b16f68bec1295ba8 Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
 <refentry xml:id="function.grapheme-strlen" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strlen</refname>
@@ -66,6 +66,38 @@ print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_
 6
 ]]>
   </screen>
+  <example>
+   <title>不正な UTF-8 入力の扱い</title>
+   <simpara>
+    <function>grapheme_strlen</function> は、入力が有効な UTF-8 でない場合など、
+    失敗したときに &null; または &false; を返します。
+    ICU のエラーの詳細は、<function>intl_get_error_code</function> と
+    <function>intl_error_name</function> で取得できます。
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$string = "\xFF"; // 不正な UTF-8 のバイト列
+$length = grapheme_strlen($string);
+
+if (!is_int($length)) {
+    $code = intl_get_error_code();
+    printf("grapheme_strlen() failed: %s (%d)\n", intl_error_name($code), $code);
+} else {
+    echo $length, PHP_EOL;
+}
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+grapheme_strlen() failed: U_INVALID_CHAR_FOUND (10)
+]]>
+   </screen>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
@@ -80,6 +112,8 @@ print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_
     <member><function>iconv_strlen</function></member>
     <member><function>mb_strlen</function></member>
     <member><function>strlen</function></member>
+    <member><function>intl_get_error_code</function></member>
+    <member><function>intl_error_name</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/intl/grapheme/grapheme-strpos.xml b/reference/intl/grapheme/grapheme-strpos.xml
index b7e970a1bc..6a955f5de2 100644
--- a/reference/intl/grapheme/grapheme-strpos.xml
+++ b/reference/intl/grapheme/grapheme-strpos.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 9a8c593c09cf7d84085989e42f3b2b23536279db Maintainer: takagi Status: ready -->
+<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
 <refentry xml:id="function.grapheme-strpos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_strpos</refname>
@@ -56,7 +56,19 @@
     <varlistentry>
      <term><parameter>locale</parameter></term>
      <listitem>
-      &intl.param.grapheme.locale;
+      <simpara>
+       使用するロケール。ロケールによって、書記素クラスターの定義と文字列の比較方法が変わります。
+       空文字列または &null; を指定すると、デフォルトのロケールを使用します。
+      </simpara>
+      <simpara>
+       ロケール識別子には、照合の挙動を制御する Unicode ロケール拡張のキーを含めることができます。
+       なかでも <literal>ks</literal> キーは照合強度を制御します。
+       たとえば <literal>en_US-u-ks-identic</literal> を指定すると一致段階で比較するようになり、
+       他の強度では同等とみなされる Unicode の異体字セレクタの違い
+       (絵文字表示とテキスト表示など) を区別します。
+       <literal>ks</literal> の値と照合強度の対応の一覧は、
+       <methodname>Collator::setStrength</methodname> を参照ください。
+      </simpara>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -117,6 +129,42 @@ print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_n
 2
 ]]>
   </screen>
+  <example>
+   <title><literal>ks-identic</literal> ロケールキーで異体字セレクタを区別する</title>
+   <simpara>
+    デフォルトでは、Unicode の異体字セレクタ (テキスト表示の U+FE0E、絵文字表示の U+FE0F)
+    は比較の際に無視されます。ロケール拡張のキー <literal>ks-identic</literal>
+    を使うと一致段階で照合するようになり、異体字セレクタの違いを区別します。
+   </simpara>
+   <note>
+    <simpara>
+     <parameter>locale</parameter> 引数は PHP 8.5.0 以降で利用可能です。
+    </simpara>
+   </note>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$textStyle  = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (テキスト表示の異体字セレクタ)
+$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (絵文字表示の異体字セレクタ)
+
+// デフォルトのロケール: 異体字セレクタは無視されるので、needle は位置 0 で見つかります
+var_dump(grapheme_strpos($textStyle, $emojiStyle));
+
+// ks-identic を指定した場合: 異体字セレクタが区別されるので、一致するものは見つかりません
+var_dump(grapheme_strpos($textStyle, $emojiStyle, 0, 'en_US-u-ks-identic'));
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+int(0)
+bool(false)
+]]>
+   </screen>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
@@ -128,6 +176,7 @@ print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_n
     <member><function>grapheme_strripos</function></member>
     <member><function>grapheme_strrpos</function></member>
     <member><function>grapheme_strstr</function></member>
+    <member><methodname>Collator::setStrength</methodname></member>
     <member>
      <link xlink:href="&uri.unicode.graphemes;">
       Unicode Text Segmentation: Grapheme Cluster Boundaries