Merge pull request #1519 from phil-davis/issue-1041-alternate-a

feat: return PROPFIND properties indexed by status

Author: phil-davis

lib/DAV/Client.php

@@ -174,27 +174,98 @@ public function __construct(array $settings)
     }
 
     /**
-     * Does a PROPFIND request.
+     * Does a PROPFIND request with filtered response returning only available properties.
      *
      * The list of requested properties must be specified as an array, in clark
      * notation.
      *
-     * The returned array will contain a list of filenames as keys, and
-     * properties as values.
+     * Depth should be either 0 or 1. A depth of 1 will cause a request to be
+     * made to the server to also return all child resources.
+     *
+     * For depth 0, just the array of properties for the resource is returned.
+     *
+     * For depth 1, the returned array will contain a list of resource names as keys,
+     * and an array of properties as values.
      *
-     * The properties array will contain the list of properties. Only properties
-     * that are actually returned from the server (without error) will be
+     * The array of properties will contain the properties as keys with their values as the value.
+     * Only properties that are actually returned from the server without error will be
      * returned, anything else is discarded.
      *
+     * @param 1|0 $depth
+     */
+    public function propFind(string $url, array $properties, int $depth = 0): array
+    {
+        $result = $this->doPropFind($url, $properties, $depth);
+
+        // If depth was 0, we only return the top item
+        if (0 === $depth) {
+            reset($result);
+            $result = current($result);
+
+            return isset($result[200]) ? $result[200] : [];
+        }
+
+        $newResult = [];
+        foreach ($result as $href => $statusList) {
+            $newResult[$href] = isset($statusList[200]) ? $statusList[200] : [];
+        }
+
+        return $newResult;
+    }
+
+    /**
+     * Does a PROPFIND request with unfiltered response.
+     *
+     * The list of requested properties must be specified as an array, in clark
+     * notation.
+     *
      * Depth should be either 0 or 1. A depth of 1 will cause a request to be
      * made to the server to also return all child resources.
      *
-     * @param string $url
-     * @param int    $depth
+     * For depth 0, just the multi-level array of status and properties for the resource is returned.
      *
-     * @return array
+     * For depth 1, the returned array will contain a list of resources as keys and
+     * a multi-level array containing status and properties as value.
+     *
+     * The multi-level array of status and properties is formatted the same as what is
+     * documented for parseMultiStatus.
+     *
+     * All properties that are actually returned from the server are returned by this method.
+     *
+     * @param 1|0 $depth
+     */
+    public function propFindUnfiltered(string $url, array $properties, int $depth = 0): array
+    {
+        $result = $this->doPropFind($url, $properties, $depth);
+
+        // If depth was 0, we only return the top item
+        if (0 === $depth) {
+            reset($result);
+
+            return current($result);
+        } else {
+            return $result;
+        }
+    }
+
+    /**
+     * Does a PROPFIND request.
+     *
+     * The list of requested properties must be specified as an array, in clark
+     * notation.
+     *
+     * Depth should be either 0 or 1. A depth of 1 will cause a request to be
+     * made to the server to also return all child resources.
+     *
+     * The returned array will contain a list of resources as keys and
+     * a multi-level array containing status and properties as value.
+     *
+     * The multi-level array of status and properties is formatted the same as what is
+     * documented for parseMultiStatus.
+     *
+     * @param 1|0 $depth
      */
-    public function propFind($url, array $properties, $depth = 0)
+    private function doPropFind(string $url, array $properties, int $depth = 0): array
     {
         $dom = new \DOMDocument('1.0', 'UTF-8');
         $dom->formatOutput = true;
@@ -232,22 +303,7 @@ public function propFind($url, array $properties, $depth = 0)
             throw new HTTP\ClientHttpException($response);
         }
 
-        $result = $this->parseMultiStatus($response->getBodyAsString());
-
-        // If depth was 0, we only return the top item
-        if (0 === $depth) {
-            reset($result);
-            $result = current($result);
-
-            return isset($result[200]) ? $result[200] : [];
-        }
-
-        $newResult = [];
-        foreach ($result as $href => $statusList) {
-            $newResult[$href] = isset($statusList[200]) ? $statusList[200] : [];
-        }
-
-        return $newResult;
+        return $this->parseMultiStatus($response->getBodyAsString());
     }
 
     /**