[DOC-CVS] [doc-en] master: fix: add deprecation notice for auto_detect_line_endings (#5238)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-08-27T09:27:48+02:00

Commit: https://github.com/php/doc-en/commit/9e5166dc6a5ff650b649298470d19eb7c3637a63
Raw diff: https://github.com/php/doc-en/commit/9e5166dc6a5ff650b649298470d19eb7c3637a63.diff

fix: add deprecation notice for auto_detect_line_endings (#5238)

- Rewrite note.line-endings entity to remove the recommendation to enable
  a deprecated option; situate it in the past and add the alternative
  (handle "\r" line breaks manually) from the PHP 8.1 migration guide
- Add <warning> block to the auto_detect_line_endings INI directive
  description, using the correct admonition tag for deprecations
- Replace <para> with <simpara> for inline-only content in the listitem
- Use consistent "option" terminology instead of "feature"

Fixes #4586

Changed paths:
  M  language-snippets.ent
  M  reference/filesystem/ini.xml


Diff:

diff --git a/language-snippets.ent b/language-snippets.ent
index c6e8392e26e4..26c58a4a886a 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -100,11 +100,12 @@ and missing arguments are replaced with their defaults.
 This function ignores the collection of unknown named variadic arguments.
 Unknown named arguments which are collected can only be accessed through the variadic parameter.</simpara></note>'>
 
-<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>If PHP is not properly recognizing
-the line endings when reading files either on or created by a Macintosh
-computer, enabling the
+<!ENTITY note.line-endings '<note xmlns="http://docbook.org/ns/docbook"><simpara>Prior to PHP 8.1.0, the
 <link linkend="ini.auto-detect-line-endings">auto_detect_line_endings</link>
-run-time configuration option may help resolve the problem.</simpara></note>'>
+run-time configuration option could be enabled to help PHP properly recognize
+line endings when reading files created on Macintosh systems. This option has
+been deprecated as of PHP 8.1.0. If necessary, handle <literal>"\r"</literal>
+line breaks manually instead.</simpara></note>'>
 
 <!ENTITY note.no-remote '<note xmlns="http://docbook.org/ns/docbook"><simpara>This function will not work on
 <link linkend="features.remote-files">remote files</link> as the file to
diff --git a/reference/filesystem/ini.xml b/reference/filesystem/ini.xml
index 08fae311d58d..d1132d2b24e8 100644
--- a/reference/filesystem/ini.xml
+++ b/reference/filesystem/ini.xml
@@ -148,17 +148,22 @@
      <type>bool</type>
     </term>
     <listitem>
-     <para>
+     <simpara>
       When turned on, PHP will examine the data read by
       <function>fgets</function> and <function>file</function> to see if it
       is using Unix, MS-Dos or Macintosh line-ending conventions.
-     </para>
-     <para>This enables PHP to interoperate with Macintosh systems,
+     </simpara>
+     <simpara>This enables PHP to interoperate with Macintosh systems,
       but defaults to Off, as there is a very small performance penalty
       when detecting the EOL conventions for the first line, and also
       because people using carriage-returns as item separators under
       Unix systems would experience non-backwards-compatible behaviour.
-     </para>
+     </simpara>
+     <warning>
+      <simpara>
+       This option has been deprecated as of PHP 8.1.0.
+      </simpara>
+     </warning>
     </listitem>
    </varlistentry>