[DOC-CVS] [doc-en] master: phar: Document changes done in #76774 (#4934)

Author: Niels Dossche (nielsdos)
Committer: GitHub (web-flow)
Pusher: nielsdos
Date: 2025-10-25T12:31:32+02:00

Commit: https://github.com/php/doc-en/commit/2b232242b1c4a99e689f79bd47735008c5009840
Raw diff: https://github.com/php/doc-en/commit/2b232242b1c4a99e689f79bd47735008c5009840.diff

phar: Document changes done in #76774 (#4934)

Changed paths:
  M  reference/phar/Phar.xml
  M  reference/phar/Phar/getMetadata.xml


Diff:

diff --git a/reference/phar/Phar.xml b/reference/phar/Phar.xml
index ed1f0e861ab0..fa13d20965cf 100644
--- a/reference/phar/Phar.xml
+++ b/reference/phar/Phar.xml
@@ -172,10 +172,31 @@
         Added support for the Unix timestamp extension for Zip-based archives.
        </entry>
       </row>
+      <row>
+       <entry>8.0.0</entry>
+       <entry>
+        Meta-data is no longer deserialized upon opening the archive,
+        but is deferred until <methodname>Phar::getMetadata</methodname>
+        is called.
+       </entry>
+      </row>
      </tbody>
     </tgroup>
    </informaltable>
   </section>
+
+  <section role="notes">
+   &reftitle.notes;
+   <caution>
+    <simpara>
+     Prior to PHP 8.0.0, the meta-data was deserialized upon opening the
+     archive. This could lead to security vulnerabilities.
+     Starting with PHP 8.0.0, meta-data is only deserialized when calling
+     <methodname>Phar::getMetadata</methodname>, which has options to restrict
+     deserialization for security reasons.
+    </simpara>
+   </caution>
+  </section>
  </partintro>
 
  &reference.phar.entities.Phar;
diff --git a/reference/phar/Phar/getMetadata.xml b/reference/phar/Phar/getMetadata.xml
index e283e92fd7bf..2f44a9a6511a 100644
--- a/reference/phar/Phar/getMetadata.xml
+++ b/reference/phar/Phar/getMetadata.xml
@@ -16,6 +16,15 @@
    Retrieve archive meta-data.  Meta-data can be any PHP variable that can be serialized.
   </para>
 
+  <caution>
+   <simpara>
+    Accessing the meta-data will trigger deserialization, which can trigger
+    the execution of arbitrary PHP code. Do not use this on untrusted phar
+    archives, or configure the <parameter>unserializeOptions</parameter>
+    in a secure manner.
+   </simpara>
+  </caution>
+
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;