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

Author: ndossche

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;

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;