docs: add documentation for DAV collection preloading event

Signed-off-by: Salvatore Martire <4652631+salmart-dev@users.noreply.github.com>

Author: salmart-dev

developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst

@@ -82,6 +82,11 @@ Back-end changes
 - These new attributes will be applied on a "defacto standard" basis to the best of our knowledge.
   In case an API was flagged unexpectedly, leave a comment on the respective pull request in the server repository asking for clarification.
 
+Added Events
+^^^^^^^^^^^^
+
+- New ``preloadCollection`` event emitted by the DAV server during PROPFIND requests. See :ref:`collection_preload` for details.
+
 Added APIs
 ^^^^^^^^^^
 

developer_manual/digging_deeper/index.rst

@@ -48,4 +48,5 @@ Digging deeper
    user_migration
    users
    web_host_metadata
+   webdav_collection_preload
    time

developer_manual/digging_deeper/webdav_collection_preload.rst

@@ -0,0 +1,105 @@
+.. _collection_preload:
+
+=================================
+WebDAV collection preload events
+=================================
+
+Overview
+--------
+
+During a WebDAV PROPFIND on a SabreDAV Collection with Depth > 0,
+Nextcloud emits a preload event so DAV plugins can fetch data for the collection's
+children in one go. The goal is to avoid N+1 database queries by
+preloading what your property handlers will need before per-node property
+handling starts. In practice this means your plugin can fill a cache up
+front and then read from it in the usual ``propFind`` handlers for a faster
+and more efficient response.
+
+When is the event emitted
+-------------------------
+
+The event is emitted during PROPFIND requests, before the ``propFind`` event
+is emitted, against nodes implementing ``Sabre\DAV\ICollection`` with Depth > 0.
+
+The event may be emitted multiple times for a single request path; plugins should
+check their cache to avoid duplicate work.
+
+Subscribing to the event in a plugin
+------------------------------------
+
+Register a listener in your implementation of Sabre's ``ServerPlugin::initialize()`` method:
+
+.. code-block:: php
+
+    use Sabre\DAV\ICollection;
+    use Sabre\DAV\PropFind;
+
+    class MyDavPlugin extends ServerPlugin {
+
+        public function initialize(\Sabre\DAV\Server $server): void {
+            // Called before per-node property handlers
+            $server->on('preloadCollection', $this->preloadCollection(...));
+
+            // Your usual property handlers
+            $server->on('propFind', $this->handleGetProperties(...));
+        }
+
+        private function preloadCollection(PropFind $propFind, ICollection $collection): void {
+            // Only preload when your properties have been requested to avoid unnecessary queries
+            $requested = [
+                '{http://appdomain.example/ns}your-prop',
+                '{http://appdomain.example/ns}another-prop',
+            ];
+            $anyRequested = array_reduce(
+                $requested,
+                fn($result, $property) => $result || $propFind->getStatus($property) !== null,
+                false
+            );
+            if (!$anyRequested) {
+                return;
+            }
+
+            // Fetch data for the collection and its children in bulk
+            // and cache results for use in your propFind handler
+            $this->cache = $this->bulkLoadDataForCollection($collection); // implement your own caching
+        }
+
+        private function handleGetProperties(PropFind $propFind, \Sabre\DAV\INode $node): void {
+            // Read and return values from $this->cache here to avoid per-node queries
+
+            // Handle per-node property loading here, to handle Depth = 0
+            // and cases where the `preloadCollection` event is not emitted.
+        }
+
+    }
+
+
+Built-in examples
+-----------------
+
+- Tags: ``OCA\DAV\Connector\Sabre\TagsPlugin`` preloads tags and favorite
+  info for a folder and its children.
+- Shares: ``OCA\DAV\Connector\Sabre\SharesPlugin`` preloads share types and
+  sharees for items within a folder.
+- Comments: ``OCA\DAV\Connector\Sabre\CommentPropertiesPlugin`` preloads unread
+  comment counts for items within a folder.
+
+Best practices
+--------------
+
+- Check requested properties: Use ``$propFind->getStatus('{ns}property')`` to
+  confirm that your properties were actually requested before querying.
+- Cache results: The event can fire multiple times; cache by file id or path
+  to avoid redundant work during the same request.
+- Scope your preload: Only fetch data for the current collection and (at most)
+  its direct children; avoid fetching across the whole tree.
+- Depth awareness: The event fires for Depth > 0; design your preload logic so
+  that sibling PROPFIND calls don’t repeat heavy queries or perform one query
+  per node for too many nodes.
+
+Compatibility
+-------------
+
+- The ``preloadCollection`` event is available starting with Nextcloud 32.
+  Plugins listening for the event will simply not be invoked on earlier
+  versions (no extra guards required).