[DOC-CVS] [doc-en] master: Document ZipArchive deferred write behavior (#5274)

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

Commit: https://github.com/php/doc-en/commit/5cb356334f35b9ae452e3af47d2d9f0b1cd16b63
Raw diff: https://github.com/php/doc-en/commit/5cb356334f35b9ae452e3af47d2d9f0b1cd16b63.diff

Document ZipArchive deferred write behavior (#5274)

Fixes #3717

Changed paths:
  M  reference/zip/ziparchive/close.xml
  M  reference/zip/ziparchive/open.xml


Diff:

diff --git a/reference/zip/ziparchive/close.xml b/reference/zip/ziparchive/close.xml
index 456f540f8c22..d22285387306 100644
--- a/reference/zip/ziparchive/close.xml
+++ b/reference/zip/ziparchive/close.xml
@@ -15,6 +15,16 @@
    Close opened or created archive and save changes. This method is
    automatically called at the end of the script.
   </simpara>
+  <note>
+   <simpara>
+    All modifications to the archive (adding, removing, or renaming
+    entries) are performed in memory and only written to disk when
+    this method is called. As a result, errors related to file system
+    operations (such as permission denied or missing directories) will
+    only surface at close time rather than when the modification
+    methods are called.
+   </simpara>
+  </note>
   <simpara>
    If the archive contains no files, the file is completely removed by default
    (no empty archive is written) according to the value of the
diff --git a/reference/zip/ziparchive/open.xml b/reference/zip/ziparchive/open.xml
index 0306d884cb60..00355a7b1a53 100644
--- a/reference/zip/ziparchive/open.xml
+++ b/reference/zip/ziparchive/open.xml
@@ -18,6 +18,17 @@
   <simpara>
    Since libzip 1.6.0, an empty file is not a valid archive any longer.
   </simpara>
+  <note>
+   <simpara>
+    When creating a new archive with <constant>ZipArchive::CREATE</constant>,
+    the file is not actually written to disk until
+    <methodname>ZipArchive::close</methodname> is called. Therefore, errors
+    related to the file system (such as permission denied or a
+    non-existent parent directory) will only be reported when calling
+    <methodname>ZipArchive::close</methodname>, not when calling this
+    method.
+   </simpara>
+  </note>
  </refsect1>
  <refsect1 role="parameters">
   &reftitle.parameters;