Document ZipArchive deferred write behavior

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

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;