Extended documentation

.gitignore

@@ -5,3 +5,6 @@ cache
 .config
 .local
 *.phar
+.composer
+.phpunit*
+.bash_history

CloudObjects/SDK/AccountGateway/AccountContext.php

@@ -13,6 +13,7 @@ use Nyholm\Psr7\Factory\Psr17Factory;
 use Symfony\Bridge\PsrHttpMessage\Factory\PsrHttpFactory;
 use GuzzleHttp\Client, GuzzleHttp\HandlerStack, GuzzleHttp\Middleware;
 use Psr\Http\Message\RequestInterface, Psr\Http\Message\ResponseInterface;
+use CloudObjects\SDK\Exceptions\SDKException;
 
 /**
  * The context of an request for an account.
@@ -40,9 +41,9 @@ class AccountContext {
 	/**
 	 * Create a new context using an AAUID and an OAuth 2.0 bearer access token.
 	 */
-	public function __construct(IRI $aauid, $accessToken, DataLoader $dataLoader = null) {
+	public function __construct(IRI $aauid, $accessToken, ?DataLoader $dataLoader = null) {
 		if (AAUIDParser::getType($aauid) != AAUIDParser::AAUID_ACCOUNT)
-			throw new \Exception("Not a valid AAUID");
+			throw new SDKException("Not a valid AAUID");
 
 		$this->aauid = $aauid;
 		$this->accessToken = $accessToken;
@@ -324,7 +325,7 @@ class AccountContext {
 	 */
 	public function setLogCode($logCode) {
 		if (!$this->request) {
-			throw new \Exception('Not in a request context.');
+			throw new SDKException('Not in a request context.');
 		}
 		$this->logCode = $logCode;
 	}

CloudObjects/SDK/COIDParser.php

@@ -20,7 +20,7 @@ class COIDParser {
     const COID_VERSIONED = 3;
     const COID_VERSION_WILDCARD = 4;
 
-  const REGEX_HOSTNAME = "/^([a-z0-9-]+\.)?[a-z0-9-]+\.[a-z]+$/";
+    const REGEX_HOSTNAME = "/^([a-z0-9-]+\.)*[a-z0-9-]+\.[a-z]+$/";
     const REGEX_SEGMENT = "/^[A-Za-z-_0-9\.]+$/";
     const REGEX_VERSION_WILDCARD = "/^((\^|~)(\d+\.)?\d|(\d+\.){1,2}\*)$/";
 
@@ -31,9 +31,9 @@ class COIDParser {
      * @param string $coidString A COID string.
      * @return IRI
      */
-  public static function fromString($coidString) {
+    public static function fromString($coidString) : IRI {
         $coidPre = new IRI(
-      (strtolower(substr($coidString, 0, 7))=='coid://') ? $coidString : 'coid://'.$coidString
+            (strtolower(substr($coidString, 0, 7)) == 'coid://') ? $coidString : 'coid://'.$coidString
         );
         // Normalize scheme and host segments to lower case
         return new IRI('coid://'.strtolower($coidPre->getHost()).$coidPre->getPath());
@@ -45,7 +45,7 @@ class COIDParser {
      * @param IRI $coid
      * @return int|null
      */
-  public static function getType(IRI $coid) {
+    public static function getType(IRI $coid) : ?int {
         if ($coid->getScheme()!='coid' || $coid->getHost()==''
                 || preg_match(self::REGEX_HOSTNAME, $coid->getHost()) != 1)
             return self::COID_INVALID;
@@ -79,9 +79,9 @@ class COIDParser {
      * Checks whether the given IRI object is a valid COID.
      *
      * @param IRI $coid
-   * @return boolean
+     * @return bool
      */
-  public static function isValidCOID(IRI $coid) {
+    public static function isValidCOID(IRI $coid) : bool {
         return (self::getType($coid)!=self::COID_INVALID);
     }
 
@@ -91,7 +91,7 @@ class COIDParser {
      * @param IRI $coid
      * @return string|null
      */
-  public static function getName(IRI $coid) {
+    public static function getName(IRI $coid) : ?string {
         if (self::getType($coid)!=self::COID_INVALID
                 && self::getType($coid)!=self::COID_ROOT) {
             $segments = explode('/', $coid->getPath());
@@ -106,7 +106,7 @@ class COIDParser {
      * @param IRI $coid
      * @return string|null
      */
-  public static function getVersion(IRI $coid) {
+    public static function getVersion(IRI $coid) : ?string {
         if (self::getType($coid)==self::COID_VERSIONED) {
             $segments = explode('/', $coid->getPath());
             return $segments[2];
@@ -121,7 +121,7 @@ class COIDParser {
      * @param IRI $coid
      * @return string|null
      */
-  public static function getVersionWildcard(IRI $coid) {
+    public static function getVersionWildcard(IRI $coid) : ?string {
         if (self::getType($coid)==self::COID_VERSION_WILDCARD) {
             $segments = explode('/', $coid->getPath());
             return $segments[2];
@@ -136,7 +136,7 @@ class COIDParser {
      * @param IRI $coid
      * @return IRI|null
      */
-  public static function getNamespaceCOID(IRI $coid) {
+    public static function getNamespaceCOID(IRI $coid) : ?IRI {
         switch (self::getType($coid)) {
             case self::COID_ROOT:
                 return $coid;

CloudObjects/SDK/CloudObject.php

@@ -0,0 +1,176 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+ 
+namespace CloudObjects\SDK;
+
+use ML\IRI\IRI;
+use ML\JsonLD\Node;
+use CloudObjects\SDK\NodeReader;
+use Webmozart\Assert\Assert;
+
+/**
+ * A CloudObject encapsulates an object node for an object stored in CloudObjects Core
+ * with convenience methods to access properties.
+ */
+class CloudObject {
+
+    private $coid;
+    private $node;
+    private $reader = null;
+    private $retriever = null;
+
+    public function __construct(IRI $coid, Node $node) {
+        Assert::eq((string)$coid, $node->getId(), "COID and Node ID must match.");
+
+        $this->coid = $coid;
+        $this->node = $node;
+    }
+
+    /**
+     * Specify a custom NodeReader to use for this CloudObject.
+     * If not set, a default NodeReader will be used.
+     */
+    public function setReader(NodeReader $reader) : self {
+        $this->reader = $reader;
+
+        return $this;
+    }
+
+    /**
+     * Get the NodeReader used for this CloudObject.
+     * Returns a default NodeReader if non has been set.
+     */
+    protected function getReader() : NodeReader {
+        if (!$this->reader) {
+            $this->reader = new NodeReader;
+        }
+        return $this->reader;
+    }
+
+    /**
+     * Specify an ObjectRetriever to use for retrieval
+     * of related objects.
+     */
+    public function setObjectRetriever(ObjectRetriever $retriever) : self {
+        $this->retriever = $retriever;
+
+        return $this;
+    }
+
+    /**
+     * Get the COID of this object.
+     */
+    public function getCOID() : IRI {
+        return $this->coid;
+    }
+
+    /**
+     * Get the object node encapsulated in this CloudObject.
+     */
+    public function getAsNode() : Node {
+        return $this->node;
+    }
+
+    /**
+     * Checks if a property exists on this object.
+     */
+    public function has($property) : bool {
+        return $this->getReader()->hasProperty($this->node, $property);
+    }
+
+    /**
+     * Get the value of a property as a string.
+     * If the property has multiple values, only the first is returned.
+     */
+    public function getString($property, ?string $default = null) : ?string {
+        return $this->getReader()->getFirstValueString($this->node, $property, $default);
+    }
+
+    /**
+     * Get the value of a property as an integer.
+     * If the property has multiple values, only the first is returned.
+     */
+    public function getInt($property, ?int $default = null) : ?int {
+        return $this->getReader()->getFirstValueInt($this->node, $property, $default);
+    }
+
+    /**
+     * Get the value of a property as a float.
+     * If the property has multiple values, only the first is returned.
+     */
+    public function getFloat($property, ?float $default = null) : ?float {
+        return $this->getReader()->getFirstValueFloat($this->node, $property, $default);
+    }
+
+    /**
+     * Get the value of a property as a boolean.
+     * If the property has multiple values, only the first is returned.
+     */
+    public function getBool($property, ?bool $default = null) : ?bool {
+        return $this->getReader()->getFirstValueBool($this->node, $property, $default);
+    }
+
+    /**
+     * Get the value of a property as an IRI.
+     * If the property has multiple values, only the first is returned.
+     */
+    public function getIRI($property, ?IRI $default = null) : ?IRI {
+        return $this->getReader()->getFirstValueIRI($this->node, $property, $default);
+    }
+
+    /**
+     * Get the value of a property as a Node.
+     * If the property has multiple values, only the first is returned.
+     */
+    public function getNode($property, ?Node $default = null) : ?Node {
+        return $this->getReader()->getFirstValueNode($this->node, $property, $default);
+    }
+
+    /**
+     * Get the value of a property and, if it's a COID, retrieve the corresponding CloudObject.
+     */
+    public function getCloudObject($property) : ?CloudObject {
+        Assert::notNull($this->retriever, "No ObjectRetriever set for CloudObject. Cannot retrieve related object.");
+
+        $coid = $this->getReader()->getFirstValueIRI($this->node, $property);
+
+        if (!($coid instanceof IRI)) {
+            return null;
+        }
+
+        return $this->retriever->getCloudObject($coid);
+    }
+
+    /**
+     * Get the value of a property and, if it's a COID, retrieve the corresponding object node.
+     */
+    public function getObjectNode($property) : ?Node {
+        Assert::notNull($this->retriever, "No ObjectRetriever set for CloudObject. Cannot retrieve related object.");
+
+        $coid = $this->getReader()->getFirstValueIRI($this->node, $property);
+
+        if (!($coid instanceof IRI)) {
+            return null;
+        }
+
+        return $this->retriever->getObjectNode($coid);
+    }
+    
+    /**
+     * Get the revision of the object.
+     */
+    public function getRevision() : string {
+        return $this->getString(Constants::PROPERTY_REVISION);
+    }
+
+    /**
+     * Get the label of the object.
+     */
+    public function getLabel() : ?string {
+        return $this->getString(Constants::RDFS_LABEL);
+    }
+
+}

CloudObjects/SDK/Common/CryptoHelper.php

@@ -6,7 +6,7 @@
 
 namespace CloudObjects\SDK\Common;
 
-use Exception;
+use CloudObjects\SDK\Exceptions\SDKException;
 use ML\IRI\IRI;
 use CloudObjects\SDK\NodeReader;
 use Defuse\Crypto\Key, Defuse\Crypto\Crypto;
@@ -53,14 +53,14 @@ class CryptoHelper {
      * @param ObjectRetriever $objectRetriever An initialized and authenticated object retriever.
      * @param IRI|null $namespaceCoid The namespace used to retrieve keys. If this parameter is not provided, the namespace provided with the "auth_ns" configuration option from the object retriever is used.
      */
-    public function __construct(ObjectRetriever $objectRetriever, IRI $namespaceCoid = null) {
+    public function __construct(ObjectRetriever $objectRetriever, ?IRI $namespaceCoid = null) {
         if (!class_exists('Defuse\Crypto\Crypto'))
-            throw new Exception("Run composer require defuse/php-encryption before using CryptoHelper.");
+            throw new SDKException("Run composer require defuse/php-encryption before using CryptoHelper.");
 
         $this->objectRetriever = $objectRetriever;
         $this->namespace = isset($namespaceCoid)
-            ? $objectRetriever->getObject($namespaceCoid)
-            : $objectRetriever->getAuthenticatingNamespaceObject();
+            ? $objectRetriever->getObjectNode($namespaceCoid)
+            : $objectRetriever->getAuthenticatingNamespaceObjectNode();
         
         $this->reader = new NodeReader([
             'prefixes' => [

CloudObjects/SDK/Constants.php

@@ -0,0 +1,14 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+ 
+namespace CloudObjects\SDK;
+
+class Constants {
+
+    const PROPERTY_REVISION = 'coid://cloudobjects.io/isAtRevision';
+    const RDFS_LABEL = 'http://www.w3.org/2000/01/rdf-schema#label';
+
+}

CloudObjects/SDK/CustomCacheAndLogInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+ 
+namespace CloudObjects\SDK;
+
+interface CustomCacheAndLogInterface {
+
+    public function logInfoWithTime($message, $ts);
+    
+    public function getFromCacheCustom($id);
+
+	public function putIntoCacheCustom($id, $data, $ttl);
+
+}

CloudObjects/SDK/Exceptions/CoreAPIException.php

@@ -9,6 +9,14 @@ namespace CloudObjects\SDK\Exceptions;
 /**
  * An Exception that is thrown when the Core API returned an error.
  */
-class CoreAPIException extends \Exception {
+class CoreAPIException extends SDKException {
+
+	/**
+	 * @param string $message The error message.
+	 * @param \Throwable|null $previous The original exception that caused this error, if any.
+	 */
+	public function __construct(string $message = "", ?\Throwable $previous = null) {
+		parent::__construct($message, 0, $previous);
+	}
 
 }

CloudObjects/SDK/Exceptions/InvalidObjectConfigurationException.php

@@ -10,6 +10,6 @@ namespace CloudObjects\SDK\Exceptions;
  * An Exception that is thrown when an object's configuration
  * doesn't match the client's expectations.
  */
-class InvalidObjectConfigurationException extends \Exception {
+class InvalidObjectConfigurationException extends SDKException {
 
 }

CloudObjects/SDK/Exceptions/InvalidSDKConfigurationException.php

@@ -0,0 +1,14 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+ 
+namespace CloudObjects\SDK\Exceptions;
+
+/**
+ * An Exception that is thrown when the SDK's configuration isn't valid.
+ */
+class InvalidSDKConfigurationException extends SDKException {
+
+}

CloudObjects/SDK/Exceptions/SDKException.php

@@ -0,0 +1,15 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+ 
+namespace CloudObjects\SDK\Exceptions;
+
+/**
+ * The common superclass for all Exceptions thrown by the SDK.
+ * It is also thrown directly for errors that have no more specific Exception.
+ */
+class SDKException extends \Exception {
+
+}

CloudObjects/SDK/Helpers/SDKLoader.php

@@ -6,7 +6,8 @@
 
 namespace CloudObjects\SDK\Helpers;
 
-use Exception;
+use CloudObjects\SDK\Exceptions\SDKException;
+use CloudObjects\SDK\Exceptions\InvalidSDKConfigurationException;
 use CloudObjects\SDK\NodeReader, CloudObjects\SDK\ObjectRetriever;
 
 /**
@@ -28,19 +29,52 @@ class SDKLoader {
     }
 
     /**
-     * Initialize and return the SDK with the given classname.
-     * Throws Exception if the SDK is not supported.
+     * Initialize the SDK with the given name and options; used for
+     * SDKs that are initialized with a function and not a class name.
      *
-     * @param $classname Classname for the SDK's main class
-     * @param array $options Additional options for the SDK (if necessary)
+     * @param string $sdkName The name of the SDK to initialize.
+     * @param array $options Additional options for the SDK (if necessary).
+     * @return mixed The return value of the SDK initialization, which may vary depending on the SDK.
+     * @throws SDKException If the SDK is not supported or cannot be initialized.
      */
-    public function get($classname, array $options) {
+    public function init(string $sdkName, array $options = []) : mixed {
+        $namespace = $this->objectRetriever->getAuthenticatingNamespaceCloudObject();
+
+        if (!$namespace)
+            throw new InvalidSDKConfigurationException("The authenticating namespace object could not be retrieved.");
+
+        switch (strtolower($sdkName)) {
+            case "sentry":
+                // --- Sentry (https://sentry.io/) ---
+                $initFunction = '\Sentry\init';
+                return $initFunction(array_merge([
+                    'dsn' => $namespace->getString('coid://sentry.io.3rd-party.co/DSN')
+                ], $options));
+
+            default:
+                throw new SDKException("No rules defined to initialize SDK with name <".$sdkName.">.");
+        }
+    }
+
+    /**
+     * Initialize and return the SDK with the given classname.
+     * Throws SDKException if the SDK is not supported.
+     * 
+     * @param string $classname Classname for the SDK's main class.
+     * @param array $options Additional options for the SDK (if necessary).
+     * @return mixed The initialized SDK instance.
+     * @throws SDKException If the SDK is not supported or cannot be initialized.
+     */
+    public function get(string $classname, array $options) : mixed {
         if (!class_exists($classname))
-            throw new Exception("<".$classname."> is not a valid classname.");
+            throw new SDKException("<".$classname."> is not a valid classname.");
 
         $hashkey = md5($classname.serialize($options));
         if (!isset($this->classes[$hashkey])) {
-            $nsNode = $this->objectRetriever->getAuthenticatingNamespaceObject();
+            $nsNode = $this->objectRetriever->getAuthenticatingNamespaceObjectNode();
+
+            if (!$nsNode)
+                throw new InvalidSDKConfigurationException("The authenticating namespace object could not be retrieved.");
 
             // --- Amazon Web Services (https://aws.amazon.com/) ---
             // has multiple classnames, so check for common superclass
@@ -76,7 +110,7 @@ class SDKLoader {
         }
 
         if (!isset($class))
-            throw new Exception("No rules defined to initialize <".$classname.">.");
+            throw new SDKException("No rules defined to initialize <".$classname.">.");
 
         $this->classes[$hashkey] = $class;
         return $this->classes[$hashkey];

CloudObjects/SDK/Helpers/SharedSecretAuthentication.php

@@ -50,7 +50,7 @@ class SharedSecretAuthentication {
             return self::RESULT_INVALID_PASSWORD;
 
         // Retrieve namespace
-        $namespace = $retriever->getObject($namespaceCoid);
+        $namespace = $retriever->getObjectNode($namespaceCoid);
         if (!isset($namespace))
             return self::RESULT_NAMESPACE_NOT_FOUND;
 
@@ -87,7 +87,7 @@ class SharedSecretAuthentication {
             return self::RESULT_INVALID_PASSWORD;
 
         // Retrieve namespace
-        $namespace = $this->objectRetriever->getObject($namespaceCoid);
+        $namespace = $this->objectRetriever->getObjectNode($namespaceCoid);
         if (!isset($namespace))
             return self::RESULT_NAMESPACE_NOT_FOUND;
 

CloudObjects/SDK/JSON/SchemaValidator.php

@@ -68,7 +68,7 @@ class SchemaValidator {
      * @param Node $node The COID of the specification.
      */
     public function validateAgainstCOID($data, IRI $coid) {
-        $object = $this->objectRetriever->getObject($coid);
+        $object = $this->objectRetriever->getObjectNode($coid);
         Assert::true($this->reader->hasType($object, 'json:Element'),
             "You can only validate data against JSON elements!");
         $this->validateAgainstNode($data, $object);

CloudObjects/SDK/NodeReader.php

@@ -38,7 +38,7 @@ class NodeReader {
      * @param string|object $type The type to check for.
      * @return boolean
      */
-    public function hasType(Node $node = null, $type) {
+    public function hasType(?Node $node, $type) {
         if (!isset($node))
             return false;
         $type = $this->expand($type);
@@ -60,7 +60,7 @@ class NodeReader {
         return false;
     }
 
-    private function getFirstValue(Node $node = null, $property, $default = null) {
+    private function getFirstValue(?Node $node, $property, $default = null) {
         if (!isset($node))
             return $default;
         $valueFromNode = $node->getProperty($this->expand($property));
@@ -82,7 +82,7 @@ class NodeReader {
      * @param $default The default that is returned if no value for the property exists on the node.
      * @return string|null
      */
-    public function getFirstValueString(Node $node = null, $property, $default = null) {
+    public function getFirstValueString(?Node $node, $property, $default = null) {
         $valueFromNode = $this->getFirstValue($node, $property, $default);
         if ($valueFromNode == $default)
             return $default;
@@ -103,7 +103,7 @@ class NodeReader {
      * @param $default The default that is returned if no value for the property exists on the node.
      * @return bool|null
      */
-    public function getFirstValueBool(Node $node = null, $property, $default = null) {
+    public function getFirstValueBool(?Node $node, $property, $default = null) {
         return (in_array(
             $this->getFirstValueString($node, $property, $default),
             [ '1', 'true' ]
@@ -120,7 +120,7 @@ class NodeReader {
      * @param $default The default that is returned if no value for the property exists on the node.
      * @return int|null
      */
-    public function getFirstValueInt(Node $node = null, $property, $default = null) {
+    public function getFirstValueInt(?Node $node, $property, $default = null) {
         $value = $this->getFirstValueString($node, $property);
         if (is_numeric($value))
             return (int)($value);
@@ -138,7 +138,7 @@ class NodeReader {
      * @param $default The default that is returned if no value for the property exists on the node.
      * @return float|null
      */
-    public function getFirstValueFloat(Node $node = null, $property, $default = null) {
+    public function getFirstValueFloat(?Node $node, $property, $default = null) {
         $value = $this->getFirstValueString($node, $property);
         if (is_numeric($value))
             return (float)($value);
@@ -156,7 +156,7 @@ class NodeReader {
      * @param $default The default that is returned if no value for the property exists on the node.
      * @return string|null
      */
-    public function getFirstValueIRI(Node $node = null, $property, IRI $default = null) {
+    public function getFirstValueIRI(?Node $node, $property, ?IRI $default = null) {
         $valueFromNode = $this->getFirstValue($node, $property, $default);
         if ($valueFromNode == $default)
             return $default;
@@ -177,7 +177,7 @@ class NodeReader {
      * @param $default The default that is returned if no value for the property exists on the node.
      * @return string|null
      */
-    public function getFirstValueNode(Node $node = null, $property, Node $default = null) {
+    public function getFirstValueNode(?Node $node, $property, ?Node $default = null) {
         $valueFromNode = $this->getFirstValue($node, $property, $default);
         if ($valueFromNode == $default)
             return $default;
@@ -196,7 +196,7 @@ class NodeReader {
      * @param string|object $value The expected value.
      * @return boolean
      */
-    public function hasPropertyValue(Node $node = null, $property, $value) {
+    public function hasPropertyValue(?Node $node, $property, $value) {
         if (!isset($node))
             return false;
         $valuesFromNode = $node->getProperty($this->expand($property));
@@ -225,14 +225,14 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return boolean
      */
-    public function hasProperty(Node $node = null, $property) {
+    public function hasProperty(?Node $node, $property) {
         if (!isset($node))
             return false;
         
         return ($node->getProperty($this->expand($property)) != null);
     }
 
-    private function getAllValues(Node $node = null, $property) {
+    private function getAllValues(?Node $node, $property) {
         if (!isset($node))
             return [];
 
@@ -248,7 +248,7 @@ class NodeReader {
      * Get the language-tagged-string for the property in the specified language.
      * If no value is found for the specified language, the default is returned.
      */
-    public function getLocalizedString(Node $node = null, $property, $language, $default = null) {
+    public function getLocalizedString(?Node $node, $property, $language, $default = null) {
         $values = $this->getAllValues($node, $property);
         foreach ($values as $v) {
             if (is_a($v, 'ML\JsonLD\LanguageTaggedString') && $v->getLanguage() == $language)
@@ -265,7 +265,7 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return array<string>
      */
-    public function getAllValuesString(Node $node = null, $property) {
+    public function getAllValuesString(?Node $node, $property) {
         $allValues = $this->getAllValues($node, $property);
         $output = [];
         foreach ($allValues as $a)
@@ -284,7 +284,7 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return array<bool>
      */
-    public function getAllValuesBool(Node $node = null, $property) {
+    public function getAllValuesBool(?Node $node, $property) {
         $allValues = $this->getAllValuesString($node, $property);
         $output = [];
         foreach ($allValues as $a)
@@ -300,7 +300,7 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return array<bool>
      */
-    public function getAllValuesInt(Node $node = null, $property) {
+    public function getAllValuesInt(?Node $node, $property) {
         $allValues = $this->getAllValuesString($node, $property);
         $output = [];
         foreach ($allValues as $a)
@@ -316,7 +316,7 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return array<bool>
      */
-    public function getAllValuesFloat(Node $node = null, $property) {
+    public function getAllValuesFloat(?Node $node, $property) {
         $allValues = $this->getAllValuesString($node, $property);
         $output = [];
         foreach ($allValues as $a)
@@ -333,7 +333,7 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return array<IRI>
      */
-    public function getAllValuesIRI(Node $node = null, $property) {
+    public function getAllValuesIRI(?Node $node, $property) {
         $allValues = $this->getAllValues($node, $property);
         $output = [];
         foreach ($allValues as $a)
@@ -351,7 +351,7 @@ class NodeReader {
      * @param string|object $property The property to read.
      * @return array<Node>
      */
-    public function getAllValuesNode(Node $node = null, $property) {
+    public function getAllValuesNode(?Node $node, $property) {
         $allValues = $this->getAllValues($node, $property);
         $output = [];
         foreach ($allValues as $a)

CloudObjects/SDK/ObjectRetriever.php

@@ -6,38 +6,48 @@
  
 namespace CloudObjects\SDK;
 
-use Exception;
-use ML\IRI\IRI, ML\JsonLD\JsonLD;
-use Doctrine\Common\Cache\RedisCache;
+use DateTime, Exception;
+use ML\IRI\IRI;
+use ML\JsonLD\JsonLD, ML\JsonLD\Node;
 use Psr\Log\LoggerInterface, Psr\Log\LoggerAwareTrait;
 use GuzzleHttp\ClientInterface, GuzzleHttp\Client, GuzzleHttp\HandlerStack;
 use GuzzleHttp\Exception\RequestException;
-use Kevinrob\GuzzleCache\CacheMiddleware, Kevinrob\GuzzleCache\Storage\DoctrineCacheStorage;
+use GuzzleHttp\Psr7\Request,
+	GuzzleHttp\Psr7\Response;
+use Kevinrob\GuzzleCache\CacheMiddleware;
 use Kevinrob\GuzzleCache\Strategy\PrivateCacheStrategy;
-use CloudObjects\SDK\Exceptions\CoreAPIException;
+use Kevinrob\GuzzleCache\Storage\CacheStorageInterface,
+	Kevinrob\GuzzleCache\Storage\Psr6CacheStorage,
+	Kevinrob\GuzzleCache\Storage\Psr16CacheStorage,
+	Kevinrob\GuzzleCache\CacheEntry;
+use Psr\Cache\CacheItemPoolInterface;
+use Psr\SimpleCache\CacheInterface;
+use CloudObjects\SDK\Exceptions\CoreAPIException,
+	CloudObjects\SDK\Exceptions\InvalidSDKConfigurationException,
+	CloudObjects\SDK\Exceptions\SDKException;
 use CloudObjects\SDK\AccountGateway\AccountContext;
 
 /**
  * The ObjectRetriever provides access to objects on CloudObjects.
  */
-class ObjectRetriever {
+class ObjectRetriever implements CustomCacheAndLogInterface {
 
 	use LoggerAwareTrait;
 
 	private $client;
 	private $prefix;
-	private $options;
+	private $options = [];
 	private $cache;
-	private $objects;
+	private $objects = [];
+	private $defaultReader;
+	private $customCacheDefaultRequest;
 
-	const CO_API_URL = 'https://api.cloudobjects.net/';
-	
-	const REVISION_PROPERTY = 'coid://cloudobjects.io/isAtRevision';
+	const CO_API_URL = 'https://od.coid.link/';
 		
 	public function __construct($options = []) {
 		// Merge options with defaults
 		$this->options = array_merge([
-			'cache_provider' => 'none',
+			'cache_storage' => null,
 			'cache_prefix' => 'clobj:',
 			'cache_ttl' => 60,
 			'static_config_path' => null,
@@ -49,35 +59,27 @@ class ObjectRetriever {
 			'connect_timeout' => 5
 		], $options);
 
-		// Set up object cache
-		switch ($this->options['cache_provider']) {
-			case 'none':
-				// no caching
-				$this->cache = null;
-				break;
-			case 'redis':
-				// caching with Redis
-				$redis = new \Redis();
-				$redis->pconnect(
-						isset($this->options['cache_provider.redis.host']) ? $this->options['cache_provider.redis.host'] : '127.0.0.1',
-						isset($this->options['cache_provider.redis.port']) ? $this->options['cache_provider.redis.port'] : 6379);
+		// Check object cache configuration
+		if (isset($this->options['cache_storage'])
+				&& !($this->options['cache_storage'] instanceof CacheStorageInterface)
+				&& !($this->options['cache_storage'] instanceof CacheItemPoolInterface)
+				&& !($this->options['cache_storage'] instanceof CacheInterface)
+			) {
+			throw new InvalidSDKConfigurationException('Invalid cache_storage specified; must be an instance of Kevinrob\GuzzleCache\CacheStorageInterface, Psr\Cache\CacheItemPoolInterface or Psr\SimpleCache\CacheInterface.');
+		}
 
-				$this->cache = new RedisCache();
-				$this->cache->setRedis($redis);
-				break;
-			case 'file':
-				// caching on the filesystem
-				$this->cache = new \Doctrine\Common\Cache\FilesystemCache(
-					isset($this->options['cache_provider.file.directory']) ? $this->options['cache_provider.file.directory'] : sys_get_temp_dir()
-				);
-				break;
-			default:
-				throw new Exception('Valid values for cache_provider are: none, redis, file');
+		if ($this->options['cache_storage'] instanceof CacheStorageInterface) {
+			$this->cache = $this->options['cache_storage'];
+		} elseif ($this->options['cache_storage'] instanceof CacheItemPoolInterface) {
+			$this->cache = new Psr6CacheStorage($this->options['cache_storage']);
+		} elseif ($this->options['cache_storage'] instanceof CacheInterface) {
+			$this->cache = new Psr16CacheStorage($this->options['cache_storage']);
 		}
 
 		// Set up logger
-		if (is_a($this->options['logger'], LoggerInterface::class))
+		if (is_a($this->options['logger'], LoggerInterface::class)) {
 			$this->setLogger($this->options['logger']);
+		}
 
 		// Set up handler stack
 		$stack = HandlerStack::create();
@@ -86,11 +88,14 @@ class ObjectRetriever {
 		if (isset($this->cache)) {
 			$stack->push(
 				new CacheMiddleware(
-					new PrivateCacheStrategy(
-						new DoctrineCacheStorage($this->cache)
-					)
+					new PrivateCacheStrategy($this->cache)
 				)
 			);
+
+			// We also use the cache for storing object descriptions and attachments
+			// without the HTTP request, so we create a dummy request; this way
+			// we can reuse GuzzleCache for maximum compatibility
+			$this->customCacheDefaultRequest = new Request('GET', '/');
 		}		
 
 		// Initialize client
@@ -107,19 +112,61 @@ class ObjectRetriever {
 		$this->client = new Client($options);
 	}
 
-	private function logInfoWithTime($message, $ts) {
+	/**
+	 * Set a default reader for CloudObject instances.
+	 */
+	public function setDefaultReader(NodeReader $reader) : self {
+		$this->defaultReader = $reader;
+
+		return $this;
+	}
+
+	/**
+	 * Get the default reader for CloudObject instances.
+	 */
+	public function getDefaultReader() : NodeReader {
+		return $this->defaultReader;
+	}
+
+	public function logInfoWithTime($message, $ts) {
 		if (isset($this->logger))
 			$this->logger->info($message, [ 'elapsed_ms' => round((microtime(true) - $ts) * 1000) ]);
 	}
 
+	public function getCacheKey($id) {
+		return $this->options['cache_prefix'] . $this->options['auth_ns'] . '/' . $id;		
+	}
+
 	private function getFromCache($id) {
-		return (isset($this->cache) && $this->cache->contains($this->options['cache_prefix'].$id))
-			? $this->cache->fetch($this->options['cache_prefix'].$id) : null;
+		if (!$this->cache) {
+			return null;
+		}
+		
+		$cachedData = $this->cache->fetch($this->getCacheKey($id));
+
+		if (!$cachedData) {
+			return null;
+		}
+
+		return (string)$cachedData->getResponse()->getBody(true);
 	}
 
 	private function putIntoCache($id, $data, $ttl) {
-		if (isset($this->cache))
-			$this->cache->save($this->options['cache_prefix'].$id, $data, $ttl);
+		if ($this->cache) {
+			$entry = new CacheEntry($this->customCacheDefaultRequest,
+				new Response(200, [], $data),
+				((new DateTime)->modify('+'.$ttl.' seconds')));
+
+			$this->cache->save($this->getCacheKey($id), $entry, $ttl);
+		}
+	}
+
+	public function getFromCacheCustom($id) {
+		return $this->getFromCache('custom/'.$id);
+	}
+
+	public function putIntoCacheCustom($id, $data, $ttl) {
+		$this->putIntoCache('custom/'.$id, $data, $ttl);
 	}
 
 	/**
@@ -158,26 +205,57 @@ class ObjectRetriever {
 	}
 
 	/**
-	 * Get an object description from CloudObjects. Attempts to get object
-	 * from in-memory cache first, stored static configurations next,
-	 * configured external cache third, and finally calls the Object API
-	 * on CloudObjects Core. Returns null if the object was not found.
+	 * Get an object description and return a CloudObject.
+	 */
+	public function getCloudObject(IRI $coid) : ?CloudObject {
+		$node = $this->getObjectNode($coid);
+		if (!$node) {
+			// Object not found
+			return null;
+		}
+
+		$object = (new CloudObject($coid, $node))
+			->setObjectRetriever($this);
+
+		if ($this->defaultReader) {
+			// Initialize CloudObject with default reader if it is set
+			$object->setReader($this->defaultReader);
+		}
+
+		return $object;
+	}
+
+	/**
+	 * Get an object description and return a node.
+	 * 
+	 * @deprecated Use getObjectNode() instead
+	 */
+	public function getObject(IRI $coid) {
+		return $this->getObjectNode($coid);
+	}
+
+	/**
+	 * Get an object description from CloudObjects and return a node.
 	 *
 	 * @param IRI $coid COID of the object
 	 * @return Node|null
 	 */
-	public function getObject(IRI $coid) {
+	public function getObjectNode(IRI $coid) : ?Node {
 		if (!COIDParser::isValidCOID($coid))
-			throw new Exception("Not a valid COID.");
+			throw new SDKException("Not a valid COID.");
 
 		$uriString = (string)$coid;
 
-		if (isset($this->objects[$uriString]))
-			// Return from in-memory cache if it exists
-			return $this->objects[$uriString];
+		$this->removeExpiredFromInMemoryCache();
 
 		$ts = microtime(true);
 
+		if (isset($this->objects[$uriString])) {
+			// Return from in-memory cache if it exists
+			$this->logInfoWithTime('Returning previous node for <'.$uriString.'>.', $ts);
+			return $this->objects[$uriString][1];
+		}
+
 		if (isset($this->options['static_config_path'])) {
 			$location = realpath($this->options['static_config_path'].DIRECTORY_SEPARATOR.
 				$coid->getHost().str_replace('/', DIRECTORY_SEPARATOR, $coid->getPath())
@@ -205,17 +283,30 @@ class ObjectRetriever {
 				$this->putIntoCache($uriString, $object, $this->options['cache_ttl']);
 				$this->logInfoWithTime('Fetched <'.$uriString.'> from Core API ['.$response->getStatusCode().'].', $ts);
 			} catch (RequestException $e) {
-				if ($e->hasResponse())
-					$this->logInfoWithTime('Object <'.$uriString.'> not found in Core API ['.$e->getResponse()->getStatusCode().'].', $ts);
-				else
-					$this->logInfoWithTime('Object <'.$uriString.'> could not be retrieved from Core API.', $ts);
+				if ($e->hasResponse() && $e->getResponse()->getStatusCode() == 404) {
+					// not found
+					$this->logInfoWithTime('Object <'.$uriString.'> not found in Core API.', $ts);
 					return null;
+				} else
+				if ($e->hasResponse()) {
+					// other API error
+					$this->logInfoWithTime('Object <'.$uriString.'> could not be retrieved from Core API ['.$e->getResponse()->getStatusCode().'].', $ts);
+					throw new CoreAPIException($e->getMessage(), $e);
+				} else {
+					// API error without response					
+					$this->logInfoWithTime('Object <'.$uriString.'> could not be retrieved from Core API (no status code).', $ts);
+					throw new CoreAPIException($e->getMessage(), $e);
+				}					
+			} catch (Exception $e) {
+				// other exceptions
+				$this->logInfoWithTime('Object <'.$uriString.'> could not be retrieved from Core API (unexpected exception).', $ts);
+				throw new CoreAPIException($e->getMessage(), $e);
 			}
 		}
 
 		$document = JsonLD::getDocument($object);
-		$this->objects[$uriString] = $document->getGraph()->getNode($uriString);
-		return $this->objects[$uriString];
+		$this->objects[$uriString] = [ time(), $document->getGraph()->getNode($uriString) ];
+		return $this->objects[$uriString][1];
 	}
 
 	/**
@@ -231,7 +322,7 @@ class ObjectRetriever {
 	 */
 	public function fetchObjectsInNamespaceWithType(IRI $namespaceCoid, $type) {
 		if (COIDParser::getType($namespaceCoid) != COIDParser::COID_ROOT)
-			throw new Exception("Not a valid namespace COID.");
+			throw new SDKException("Not a valid namespace COID.");
 
 		$ts = microtime(true);
 		$type = (string)$type;
@@ -252,14 +343,14 @@ class ObjectRetriever {
 				if (!COIDParser::isValidCOID($iri)) continue;
 				if ($iri->getHost() != $namespaceCoid->getHost()) continue;
 
-				$this->objects[$object->getId()] = $object;
+				$this->objects[$object->getId()] = [ time(), $object ];
 				$this->putIntoCache($object->getId(), $object, $this->options['cache_ttl']);
 				$allIris[] = $iri;
 			}
 
 			$this->logInfoWithTime('Fetched all objects with <'.$type.'> for <'.$namespaceCoid->getHost().'> from Core API ['.$response->getStatusCode().'].', $ts);
 		} catch (Exception $e) {
-			throw new CoreAPIException;
+			throw new CoreAPIException($e->getMessage(), $e);
 		}
 	
 		return $allIris;
@@ -276,7 +367,7 @@ class ObjectRetriever {
 	 */
 	public function fetchAllObjectsInNamespace(IRI $namespaceCoid) {
 		if (COIDParser::getType($namespaceCoid) != COIDParser::COID_ROOT)
-			throw new Exception("Not a valid namespace COID.");
+			throw new SDKException("Not a valid namespace COID.");
 
 		$ts = microtime(true);
 
@@ -293,7 +384,7 @@ class ObjectRetriever {
 				if (!COIDParser::isValidCOID($iri)) continue;
 					if ($iri->getHost() != $namespaceCoid->getHost()) continue;
 
-				$this->objects[$object->getId()] = $object;
+				$this->objects[$object->getId()] = [ time(), $object ];
 				$this->putIntoCache($object->getId(), $object, $this->options['cache_ttl']);
 				$allIris[] = $iri;
 			}
@@ -301,7 +392,7 @@ class ObjectRetriever {
 			$this->logInfoWithTime('Fetched all objects for <'.$namespaceCoid->getHost().'> from Core API ['.$response->getStatusCode().'].', $ts);
 
 		} catch (Exception $e) {
-			throw new CoreAPIException;
+			throw new CoreAPIException($e->getMessage(), $e);
 		}
 	
 		return $allIris;
@@ -317,7 +408,7 @@ class ObjectRetriever {
 	 */
 	public function getCOIDListForNamespace(IRI $namespaceCoid) {
 		if (COIDParser::getType($namespaceCoid) != COIDParser::COID_ROOT)
-			throw new Exception("Not a valid namespace COID.");
+			throw new SDKException("Not a valid namespace COID.");
 
 		$ts = microtime(true);
 
@@ -335,7 +426,7 @@ class ObjectRetriever {
 			$this->logInfoWithTime('Fetched object list for <'.$namespaceCoid->getHost().'> from Core API ['.$response->getStatusCode().'].', $ts);
 
 		} catch (Exception $e) {
-			throw new CoreAPIException;
+			throw new CoreAPIException($e->getMessage(), $e);
 		}
 
 		return $allIris;
@@ -352,7 +443,7 @@ class ObjectRetriever {
 	 */
 	public function getCOIDListForNamespaceWithType(IRI $namespaceCoid, $type) {		
 		if (COIDParser::getType($namespaceCoid) != COIDParser::COID_ROOT)
-			throw new Exception("Not a valid namespace COID.");
+			throw new SDKException("Not a valid namespace COID.");
 
 		$ts = microtime(true);
 		$type = (string)$type;
@@ -374,7 +465,7 @@ class ObjectRetriever {
 			$this->logInfoWithTime('Fetched object list with <'.$type.'> for <'.$namespaceCoid->getHost().'> from Core API ['.$response->getStatusCode().'].', $ts);
 
 		} catch (Exception $e) {
-			throw new CoreAPIException;
+			throw new CoreAPIException($e->getMessage(), $e);
 		}
 
 		return $allIris;
@@ -382,10 +473,11 @@ class ObjectRetriever {
 
 	/**
 	 * Get an object description from CloudObjects. Shorthand method for
-	 * "getObject" which allows passing the COID as string instead of IRI.
+	 * "getObjectNode" which allows passing the COID as string instead of IRI.
 	 *
 	 * @param any $coid
 	 * @return Node|null
+	 * @deprecated Interface may change
 	 */
 	public function get($coid) {
 		if (is_string($coid))
@@ -394,7 +486,7 @@ class ObjectRetriever {
 		if (is_object($coid) && get_class($coid)=='ML\IRI\IRI')
 			return $this->getObject($coid);
 
-		throw new Exception('COID must be passed as a string or an IRI object.');
+		throw new SDKException('COID must be passed as a string or an IRI object.');
 	}
 
 	/**
@@ -422,7 +514,7 @@ class ObjectRetriever {
 		}
 
 		if (!isset($fileData)
-				|| $fileRevision!=$object->getProperty(self::REVISION_PROPERTY)->getValue()) {
+				|| $fileRevision !== $object->getProperty(Constants::PROPERTY_REVISION)->getValue()) {
 
 			// Does not exist in cache or is outdated, fetch from CloudObjects
 			try {
@@ -430,7 +522,7 @@ class ObjectRetriever {
 					.'/'.basename($filename));
 
 				$fileContent = $response->getBody()->getContents();
-				$fileData = $object->getProperty(self::REVISION_PROPERTY)->getValue().'#'.$fileContent;
+				$fileData = $object->getProperty(Constants::PROPERTY_REVISION)->getValue().'#'.$fileContent;
 				$this->putIntoCache($cacheId, $fileData, 0);
 
 				$this->logInfoWithTime('Fetched attachment <'.$filename.'> for <'.$object->getId().'> from Core API ['.$response->getStatusCode().'].', $ts);
@@ -444,21 +536,69 @@ class ObjectRetriever {
 		return $fileContent;
 	}
 
-	/**
-	 * Retrieve the object that describes the namespace provided with the "auth_ns"
-	 * configuration option.
-	 * 
-	 * @return Node
-	 */
-	public function getAuthenticatingNamespaceObject() {
+	private function assertAuthenticatingNamespaceAndGetId() : IRI {
 		if (!isset($this->options['auth_ns']))
-			throw new Exception("Missing 'auth_ns' configuration option.");
+			throw new InvalidSDKConfigurationException("Missing 'auth_ns' configuration option.");
 
 		$namespaceCoid = COIDParser::fromString($this->options['auth_ns']);
 		if (COIDParser::getType($namespaceCoid) != COIDParser::COID_ROOT)
-			throw new Exception("The 'auth_ns' configuration option is not a valid namespace/root COID.");
+			throw new InvalidSDKConfigurationException("The 'auth_ns' configuration option is not a valid namespace/root COID.");
 
-		return $this->getObject($namespaceCoid);
+		return $namespaceCoid;
+	}
+
+	/**
+	 * Retrieve the object node that describes the namespace
+	 * provided with the "auth_ns" configuration option.
+	 * 
+	 * @deprecated Use getAuthenticatingNamespaceObjectNode() instead
+	 * @return Node
+	 */
+	public function getAuthenticatingNamespaceObject() : ?Node {
+		return $this->getObject($this->assertAuthenticatingNamespaceAndGetId());
+	}
+
+	/**
+	 * Retrieve the object node that describes the namespace
+	 * provided with the "auth_ns" configuration option.
+	 * 
+	 * @return Node
+	 */
+	public function getAuthenticatingNamespaceObjectNode() : ?Node {
+		return $this->getObject($this->assertAuthenticatingNamespaceAndGetId());
+	}
+
+	/**
+	 * Retrieve the CloudObject that describes the namespace
+	 * provided with the "auth_ns" configuration option.
+	 * 
+	 * @return CloudObject
+	 */
+	public function getAuthenticatingNamespaceCloudObject() : ?CloudObject {
+		return $this->getCloudObject($this->assertAuthenticatingNamespaceAndGetId());
+	}
+
+	/**
+	 * Remove expired objects from the in-memory cache. Does not affect external cache.
+	 */
+	public function removeExpiredFromInMemoryCache() {
+		$expiryThreshold = time() - $this->options['cache_ttl'];
+
+		foreach ($this->objects as $uriString => $entry) {
+			if ($entry[0] < $expiryThreshold) {
+				unset($this->objects[$uriString]);
+			}
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Remove all entries from the in-memory cache. Does not affect external cache.
+	 */
+	public function clearInMemoryCache() {
+		$this->objects = [];
+		return $this;
 	}
 
 }

CloudObjects/SDK/ObjectRetrieverFacade.php

@@ -0,0 +1,80 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+namespace CloudObjects\SDK;
+
+use CloudObjects\SDK\Exceptions\SDKException;
+use ML\IRI\IRI;
+use ML\JsonLD\Node;
+
+/**
+ * Static facade for ObjectRetriever. Call setObjectRetriever() once to
+ * initialize; all subsequent static calls are forwarded to that instance.
+ */
+class ObjectRetrieverFacade {
+
+	private static ?ObjectRetriever $instance = null;
+
+	public static function setObjectRetriever(ObjectRetriever $retriever) : void {
+		self::$instance = $retriever;
+	}
+
+	private static function getInstance() : ObjectRetriever {
+		if (self::$instance === null)
+			throw new SDKException('ObjectRetrieverFacade has not been initialized. Call setObjectRetriever() first.');
+
+		return self::$instance;
+	}
+
+	public static function setDefaultReader(NodeReader $reader) : ObjectRetriever {
+		return self::getInstance()->setDefaultReader($reader);
+	}
+
+	public static function getDefaultReader() : NodeReader {
+		return self::getInstance()->getDefaultReader();
+	}
+
+	public static function getClient() {
+		return self::getInstance()->getClient();
+	}
+
+	public static function getCloudObject(IRI $coid) : ?CloudObject {
+		return self::getInstance()->getCloudObject($coid);
+	}
+
+	public static function getObjectNode(IRI $coid) : ?Node {
+		return self::getInstance()->getObjectNode($coid);
+	}
+
+	public static function fetchObjectsInNamespaceWithType(IRI $namespaceCoid, $type) : array {
+		return self::getInstance()->fetchObjectsInNamespaceWithType($namespaceCoid, $type);
+	}
+
+	public static function fetchAllObjectsInNamespace(IRI $namespaceCoid) : array {
+		return self::getInstance()->fetchAllObjectsInNamespace($namespaceCoid);
+	}
+
+	public static function getCOIDListForNamespace(IRI $namespaceCoid) : array {
+		return self::getInstance()->getCOIDListForNamespace($namespaceCoid);
+	}
+
+	public static function getCOIDListForNamespaceWithType(IRI $namespaceCoid, $type) : array {
+		return self::getInstance()->getCOIDListForNamespaceWithType($namespaceCoid, $type);
+	}
+
+	public static function getAttachment(IRI $coid, $filename) {
+		return self::getInstance()->getAttachment($coid, $filename);
+	}
+
+	public static function getAuthenticatingNamespaceObjectNode() : ?Node {
+		return self::getInstance()->getAuthenticatingNamespaceObjectNode();
+	}
+
+	public static function getAuthenticatingNamespaceCloudObject() : ?CloudObject {
+		return self::getInstance()->getAuthenticatingNamespaceCloudObject();
+	}
+
+}

CloudObjects/SDK/TestHelpers/InMemoryLogger.php

@@ -0,0 +1,63 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+namespace CloudObjects\SDK\TestHelpers;
+
+use Psr\Log\LoggerInterface;
+
+class InMemoryLogger implements LoggerInterface {
+
+    private $logs = [];
+
+    public function getLogs() : array {
+        return $this->logs;
+    }
+
+    public function getLastLogMessage() : string {
+        if (empty($this->logs)) {
+            return '';
+        }
+
+        return end($this->logs)['message'];
+    }
+
+    public function emergency(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'emergency', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function alert(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'alert', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function critical(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'critical', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function error(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'error', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function warning(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'warning', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function notice(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'notice', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function info(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'info', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function debug(string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => 'debug', 'message' => (string)$message, 'context' => $context ];
+    }
+
+    public function log($level, string|\Stringable $message, array $context = []): void {
+        $this->logs[] = [ 'level' => $level, 'message' => (string)$message, 'context' => $context ];
+    }
+
+}

CloudObjects/SDK/WebAPI/APIClientFactory.php

@@ -14,7 +14,8 @@ use GuzzleHttp\Client, GuzzleHttp\HandlerStack, GuzzleHttp\Middleware;
 use Psr\Http\Message\RequestInterface;
 use CloudObjects\SDK\COIDParser, CloudObjects\SDK\ObjectRetriever;
 use CloudObjects\SDK\Exceptions\InvalidObjectConfigurationException,
-    CloudObjects\SDK\Exceptions\CoreAPIException;
+    CloudObjects\SDK\Exceptions\CoreAPIException,
+    CloudObjects\SDK\Exceptions\SDKException;
 
 /**
  * The APIClientFactory can be used to create a preconfigured Guzzle HTTP API client
@@ -154,16 +155,19 @@ class APIClientFactory {
             'timeout' => self::DEFAULT_TIMEOUT
         ];
 
-        if ($this->reader->hasProperty($api, 'wa:hasAuthorizationServer')) {
+        if ($this->reader->hasProperty($api, 'oauth2:hasAuthorizationServer')) {
             // We have an authorization server for this endpoint/API
-            $authServerCoid = $this->reader->getFirstValueIRI($api, 'wa:hasAuthorizationServer');
-            $authServerObject = $this->objectRetriever->getObject($authServerCoid);
-            if (!isset($authServer))
+            $authServerCoid = $this->reader->getFirstValueIRI($api, 'oauth2:hasAuthorizationServer');
+            $authServerObject = $this->objectRetriever->getObjectNode($authServerCoid);
+            if (!isset($authServerObject))
                 throw new InvalidObjectConfigurationException("Authorization server object <"
                     . (string)$authServerCoid . "> not available.");
 
             try {
-                $authServer = new OAuth2AuthServer($authServerObject);
+                $authServer = new OAuth2AuthServer($authServerObject, $this->objectRetriever);
+            } catch (InvalidObjectConfigurationException $e) {
+                throw new InvalidObjectConfigurationException("Authorization server object <"
+                    . (string)$authServerCoid . "> could not be loaded; error: " . $e->getMessage());
             } catch (Exception $e) {
                 throw new InvalidObjectConfigurationException("Authorization server object <"
                     . (string)$authServerCoid . "> could not be loaded. Its definition may be invalid.");
@@ -202,7 +206,7 @@ class APIClientFactory {
 
         if ($this->reader->hasType($api, 'wa:GraphQLEndpoint')) {
             if (!class_exists('GraphQL\Client'))
-                throw new Exception("Install the gmostafa/php-graphql-client package to retrieve a specific client for wa:GraphQLEndpoint objects.");
+                throw new SDKException("Install the gmostafa/php-graphql-client package to retrieve a specific client for wa:GraphQLEndpoint objects.");
             
             return new \GraphQL\Client($clientConfig['base_uri'],
                 isset($clientConfig['headers']) ? $clientConfig['headers'] : []);
@@ -214,11 +218,11 @@ class APIClientFactory {
      * @param ObjectRetriever $objectRetriever An initialized and authenticated object retriever.
      * @param IRI|null $namespaceCoid The namespace of the API client. Used to retrieve credentials. If this parameter is not provided, the namespace provided with the "auth_ns" configuration option from the object retriever is used.
      */
-    public function __construct(ObjectRetriever $objectRetriever, IRI $namespaceCoid = null) {
+    public function __construct(ObjectRetriever $objectRetriever, ?IRI $namespaceCoid = null) {
         $this->objectRetriever = $objectRetriever;
         $this->namespace = isset($namespaceCoid)
-            ? $objectRetriever->getObject($namespaceCoid)
-            : $objectRetriever->getAuthenticatingNamespaceObject();
+            ? $objectRetriever->getObjectNode($namespaceCoid)
+            : $objectRetriever->getAuthenticatingNamespaceObjectNode();
         
         $this->reader = new NodeReader([
             'prefixes' => [
@@ -239,7 +243,7 @@ class APIClientFactory {
     public function getClientWithCOID(IRI $apiCoid, bool $specificClient = false) {
         $idString = (string)$apiCoid.(string)$specificClient;
         if (!isset($this->apiClients[$idString])) {
-            $object = $this->objectRetriever->getObject($apiCoid);
+            $object = $this->objectRetriever->getObjectNode($apiCoid);
             if (!isset($object))
                 throw new CoreAPIException("Could not retrieve API <".(string)$apiCoid.">.");
             $this->apiClients[$idString] = $this->createClient($object, $specificClient);

CloudObjects/SDK/WebAPI/Exceptions/OAuthFlowException.php

@@ -6,9 +6,11 @@
  
 namespace CloudObjects\SDK\WebAPI\Exceptions;
 
+use CloudObjects\SDK\Exceptions\SDKException;
+
 /**
  * An Exception that is thrown when an an OAuth flow failed.
  */
-class OAuthFlowException extends \Exception {
+class OAuthFlowException extends SDKException {
 
 }

CloudObjects/SDK/WebAPI/OAuth2AuthServer.php

@@ -6,29 +6,34 @@
 
 namespace CloudObjects\SDK\WebAPI;
 
-use Exception;
+use CloudObjects\SDK\Exceptions\SDKException;
 use ML\JsonLD\Node;
 use GuzzleHttp\Client;
-use Webmozart\Assert\Assert;
-use CloudObjects\SDK\NodeReader;
+use Webmozart\Assert\Assert,
+    Webmozart\Assert\InvalidArgumentException;
+use CloudObjects\SDK\NodeReader,
+    CloudObjects\SDK\CustomCacheAndLogInterface;
+use CloudObjects\SDK\Exceptions\InvalidObjectConfigurationException;
 
 class OAuth2AuthServer {
 
     private $reader;
     private $authServer;
     private $consumer;
+    private $cacheAndLog;
     
     private $grantType;
     private $clientId;
     private $clientSecret;
 
-    public function __construct(Node $authServer) {
+    public function __construct(Node $authServer, CustomCacheAndLogInterface $cacheAndLog) {
         $this->reader = new NodeReader([
             'prefixes' => [
                 'oauth2' => 'coid://oauth2.co-n.net/'
             ]
         ]);
 
+        try {
             Assert::true($this->reader->hasProperty($authServer, 'oauth2:hasTokenEndpoint'),
                 "Authorization Server must have a token endpoint.");
             Assert::startsWith($this->reader->getFirstValueString($authServer, 'oauth2:hasTokenEndpoint'),
@@ -36,20 +41,24 @@ class OAuth2AuthServer {
                 "Token endpoint must be an https:// URL.");
             Assert::true($this->reader->hasProperty($authServer, 'oauth2:supportsGrantType'),
                 "Authorization Server must support at least one grant type.");
-        Assert::true($this->reader->hasProperty($this->authServer, 'oauth2:usesClientIDFrom'),
+            Assert::true($this->reader->hasProperty($authServer, 'oauth2:usesClientIDFrom'),
                 "Authorization Server must define client ID property.");
-        Assert::true($this->reader->hasProperty($this->authServer, 'oauth2:usesClientSecretFrom'),
+            Assert::true($this->reader->hasProperty($authServer, 'oauth2:usesClientSecretFrom'),
                 "Authorization Server must define client secret property.");
 
-        $this->authServer = $authServer;
+        } catch (InvalidArgumentException $e) {
+            throw new InvalidObjectConfigurationException($e->getMessage());
         }
 
-    private function assertClientCredentialPropertiesExist() : void {
-        
+        $this->authServer = $authServer;
+        $this->cacheAndLog = $cacheAndLog;
     }
 
     public function configureConsumer(Node $consumer) : void {
-        $this->assertClientCredentialPropertiesExist();
+        try {
+            Assert::notNull($this->authServer, "Object wasn't initialized correctly.");
+            Assert::notNull($this->cacheAndLog, "Object wasn't initialized correctly.");
+
             $clientIDProperty = $this->reader->getFirstValueString($this->authServer,
                 'oauth2:usesClientIDFrom');
             $clientSecretProperty = $this->reader->getFirstValueString($this->authServer,
@@ -60,12 +69,17 @@ class OAuth2AuthServer {
             Assert::true($this->reader->hasProperty($consumer, $clientSecretProperty),
                 "Namespace must have Client Secret");
 
+        } catch (InvalidArgumentException $e) {
+            throw new InvalidObjectConfigurationException($e->getMessage());
+        }
+
         if ($this->reader->hasPropertyValue($this->authServer,
-                'oauth2:supportsGrantType', 'oauth2:ClientCredentials')) {
+            'oauth2:supportsGrantType', 'oauth2:ClientCredentials'))
+        {
             // No additional conditions for "client_credentials" flow
             $this->grantType = 'client_credentials';
         } else {
-            throw new Exception("No flow/grant_type found.");
+            throw new InvalidObjectConfigurationException("No flow/grant_type found.");
         }
 
         $this->consumer = $consumer;
@@ -74,11 +88,19 @@ class OAuth2AuthServer {
     }
 
     public function getAccessToken() {
+        try {
+            Assert::notNull($this->authServer, "Object wasn't initialized correctly.");
+            Assert::notNull($this->cacheAndLog, "Object wasn't initialized correctly.");
+
             Assert::notNull($this->consumer, "Missing consumer.");
             Assert::notNull($this->grantType, "Missing grant_type.");
             Assert::notNull($this->clientId, "Missing client_id.");
             Assert::notNull($this->clientSecret, "Missing client_secret.");
     
+        } catch (InvalidArgumentException $e) {
+            throw new InvalidObjectConfigurationException($e->getMessage());
+        }
+
         $client = new Client;
         $tokenEndpointUrl = $this->reader->getFirstValueString($this->authServer, 'oauth2:hasTokenEndpoint');
         $params = [
@@ -90,16 +112,32 @@ class OAuth2AuthServer {
         switch ($this->grantType) {
             case "client_credentials":
                 // no additional params needed
+                break;
             default:
-                throw new Exception("No flow/grant_type found.");
+                throw new SDKException("No flow/grant_type found.");
         }
 
+        $grantCacheKey = sha1(json_encode($params));
+
+        $ts = microtime(true);
+        $tokenResponse = json_decode($this->cacheAndLog->getFromCacheCustom($grantCacheKey), true);
+
+        if (isset($tokenResponse)) {
+            $this->cacheAndLog->logInfoWithTime("Reused access token for <".$this->authServer->getId()."> from cache.", $ts);
+        } else {
+            // Nothing cached, fetch from server
             $tokenResponse = json_decode($client->post($tokenEndpointUrl, [
                 'form_params' => $params
-        ])->getBody(true));
+            ])->getBody(true), true);
 
             Assert::keyExists($tokenResponse, 'access_token');
 
+            $expiry = isset($tokenResponse['expires_in']) ? $tokenResponse['expires_in'] : 84600;
+
+            $this->cacheAndLog->logInfoWithTime("Retrieved access token for <".$this->authServer->getId()."> from token endpoint and will cache for ".$expiry." seconds.", $ts);
+            $this->cacheAndLog->putIntoCacheCustom($grantCacheKey, json_encode($tokenResponse), $expiry);
+        }
+
         return $tokenResponse['access_token'];
     }
 }

README.md

@@ -2,66 +2,93 @@
 
 [![Latest Stable Version](https://poser.pugx.org/cloudobjects/sdk/v/stable)](https://packagist.org/packages/cloudobjects/sdk) [![Total Downloads](https://poser.pugx.org/cloudobjects/sdk/downloads)](https://packagist.org/packages/cloudobjects/sdk)
 
-[![buddy branch](https://app.buddy.works/cloudobjects/php-sdk/repository/branch/main/badge.svg?token=52ae28bf71dbbd3dde018f3f3e7caafa04f95bdb451b3dfca547414ec7a01739 "buddy branch")](https://app.buddy.works/cloudobjects/php-sdk/repository/branch/main)
-
-The CloudObjects PHP SDK provides simple access to [CloudObjects](https://cloudobjects.io/) from PHP-based applications. It wraps the [Object API](https://coid.link/cloudobjects.io/ObjectAPI/1.0) to fetch objects from the CloudObjects Core database and provides object-based access to their RDF description. A two-tiered caching mechanism (in-memory and Doctrine cache drivers) is included. The SDK also contains a helper class to validate COIDs.
+[![buddy pipeline](https://eu.buddy.works/cloudobjects/php-sdk/pipelines/pipeline/213082/badge.svg?token=4899fb24460ff689fc1971e7c46fd9a2c1d00781b2ff19bf1c00f814123b93e2 "buddy pipeline")](https://eu.buddy.works/cloudobjects/php-sdk/pipelines/pipeline/213082)
 
 ## Installation
 
-The SDK is [distributed through packagist](https://packagist.org/packages/cloudobjects/sdk). Add `cloudobjects/sdk` to the `require` section of your `composer.json`, like this:
+The SDK is [distributed through packagist](https://packagist.org/packages/cloudobjects/sdk).
 
-````json
-{
-  "require": {
-    "cloudobjects/sdk" : ">=0.7"
-  }
-}
-````
+Install with the following command:
 
-## Retrieving Objects
+```
+composer require cloudobjects/sdk
+``` 
 
-In order to retrieve objects from the CloudObjects Core database you need to create an instance of `CloudObjects\SDK\ObjectRetriever`. Then you can call `getObject()`. This method returns an `ML\JsonLD\Node` instance or `null` if the object is not found. You can use the object interface of the [JsonLD library](https://github.com/lanthaler/JsonLD/) to read the information from the object.
+## Usage
 
-Here's a simple example:
+The primary purpose of the SDK is the retrieval of object descriptions from the CloudObjects Core Object API. To do so, you create an instance of the `CloudObjects\SDK\ObjectRetriever` class. You can use this class directy, but you can also use the static facade (`CloudObjects\SDK\ObjectRetrieverFacade`) or the global function `cloudobjects_get_object()`, depending on the architecture of your PHP application and your preferred coding style. You can use the high-level `CloudObjects\SDK\CloudObject` interface or the lower-level `ML\JsonLD\Node` interface to work with the parsed JSON-LD representation of the object.
 
-````php
-use ML\IRI\IRI;
+### Using the ObjectRetriever directly
+
+```php
 use CloudObjects\SDK\ObjectRetriever;
+use ML\IRI\IRI;
 
-/* ... */
+$retriever = new ObjectRetriever;
+$object = $retriever->getCloudObject(new IRI('coid://cloudobjects.io'));
+echo $object->getLabel();
+```
 
-$retriever = new ObjectRetriever();
-$object = $this->retriever->getObject(new IRI('coid://cloudobjects.io'));
-if (isset($object))
-    echo $object->getProperty('http://www.w3.org/2000/01/rdf-schema#label')->getValue();
-else
-    echo "Object not found.";
-````
+When no options are passed to the `ObjectRetriever`, it will initialize with default settings and no authentication, which means that it can only retrieve public triples from public objects. You can authenticate with a CloudObjects namespace (domain name) and the shared secret between this namespace and CloudObjects.
 
-### Configuration
+```php
+use CloudObjects\SDK\ObjectRetriever;
+use ML\IRI\IRI;
 
-You can pass an array of configuration options to the ObjectRetriever's constructor:
+$retriever = new ObjectRetriever([
+    'auth_ns' => 'example.com',
+    'auth_secret' => 'YOUR_SHARED_SECRET',
+]);
 
-| Option | Description | Default |
-|---|---|---|
-| `cache_provider` | The type of cache used. Currently supports `redis`, `file` and `none`. | `none` |
-| `cache_prefix` | A prefix used for cache IDs. Normally this should not be set but might be necessary on shared caches. | `clobj:` |
-| `cache_ttl` | Determines how long objects can remain cached. | `60` |
-| `auth_ns` | The namespace of the service that this retriever acts for. If not set the API is accessed anonymously. | `null` |
-| `auth_secret` | The shared secret between the namespace in `auth_ns` and `cloudobjects.io` for authenticated. If not set the API is accessed anonymously. | `null` |
+$object = $retriever->getCloudObject(new IRI('coid://example.com/PrivateObject'));
 
-#### For `redis` cache:
+// Retrieve the object describing the authenticating namespace itself
+$namespace = $retriever->getAuthenticatingNamespaceCloudObject();
+echo $namespace->getLabel();
+```
 
-| Option | Description | Default |
-|---|---|---|
-| `cache_provider.redis.host` | The hostname or IP of the Redis instance. | `127.0.0.1` |
-| `cache_provider.redis.port` | The port number of the Redis instance. | `6379` |
+Any production usage should configure a cache; [all the caching options are documented here](docs/caching.md). Other [options are documented here](docs/options.md).
 
-#### For `file` cache:
+### Using the static facade
 
-| Option | Description | Default |
-|---|---|---|
-| `cache_provider.file.directory` | The directory to store cache data in. | The system's temporary directory. |
+```php
+use CloudObjects\SDK\ObjectRetriever;
+use CloudObjects\SDK\ObjectRetrieverFacade;
+use ML\IRI\IRI;
+
+ObjectRetrieverFacade::setObjectRetriever(new ObjectRetriever);
+
+$object = ObjectRetrieverFacade::getCloudObject(new IRI('coid://cloudobjects.io'));
+echo $object->getLabel();
+```
+
+### Using the global function
+
+The global function uses the static facade, so the facade must be initialized first.
+
+```php
+use CloudObjects\SDK\ObjectRetriever;
+use CloudObjects\SDK\ObjectRetrieverFacade;
+
+ObjectRetrieverFacade::setObjectRetriever(new ObjectRetriever);
+
+$object = cloudobjects_get_object('coid://cloudobjects.io');
+echo $object->getLabel();
+```
+
+### Working with the `CloudObject` interface
+
+```php
+$object = $retriever->getCloudObject(new IRI('coid://cloudobjects.io'));
+echo $object->getString('http://www.w3.org/2000/01/rdf-schema#comment');
+```
+
+### Working with the `Node` interface
+
+```php
+$node = $retriever->getObjectNode(new IRI('coid://cloudobjects.io'));
+echo $node->getProperty('http://www.w3.org/2000/01/rdf-schema#comment')->getValue();
+```
 
 ## License
 

composer.json

@@ -2,16 +2,16 @@
 	"name": "cloudobjects/sdk",
 	"description": "CloudObjects SDK for PHP for working with COIDs and object descriptions from CloudObjects.",
 	"keywords": ["cloudobjects", "sdk"],
-	"homepage": "https://github.com/CloudObjects/CloudObjects-PHP-SDK",
+	"homepage": "https://codeberg.org/CloudObjects/CloudObjects-PHP-SDK",
 	"license": "MPL-2.0",
 	"require" : {
-		"ml/json-ld": ">=1.0.7",
-		"doctrine/common" : ">=2.6.1",
-		"doctrine/cache" : "1.*",
+		"sweetrdf/json-ld": ">=1.3",
 		"guzzlehttp/guzzle" : ">=6.0",
+		"psr/cache": ">=1.0",
 		"psr/log": ">=1.1",
-		"kevinrob/guzzle-cache-middleware": "^3.2",
-		"webmozart/assert": "^1.6"		
+		"kevinrob/guzzle-cache-middleware": "^7.0.0",
+		"webmozart/assert": "^1.6",
+		"psr/simple-cache": "^3.0"		
 	},
 	"authors": [
 		{
@@ -19,21 +19,24 @@
 		}
 	],
 	"autoload": {
-		"psr-0": {
-			"CloudObjects\\SDK" : ""
-		}
+		"psr-4": {
+			"CloudObjects\\SDK\\" : "CloudObjects/SDK/"
+		},
+		"files": [
+			"functions.php"
+		]
 	},
 	"require-dev" : {
-		"phpunit/phpunit": ">=4.8.0,<5.0",
+		"phpunit/phpunit": "^10",
 		"symfony/http-foundation" : ">=4.0",
 		"symfony/psr-http-message-bridge" : ">=1.1.0",
-		"nyholm/psr7" : "~1.5.1",
+		"nyholm/psr7" : "^1.5",
 		"defuse/php-encryption" : "^2.2"
 	},
 	"suggest" : {
-		"symfony/http-foundation" : "Required to use parseSymfonyRequest() in AccountContext.",
-		"symfony/psr-http-message-bridge" : "Required to use parseSymfonyRequest() in AccountContext.",
-		"nyholm/psr7" : "Required to use parseSymfonyRequest() in AccountContext.",
+		"symfony/http-foundation" : "Required to use fromSymfonyRequest() in AccountContext.",
+		"symfony/psr-http-message-bridge" : "Required to use fromSymfonyRequest() in AccountContext.",
+		"nyholm/psr7" : "Required to use fromSymfonyRequest() in AccountContext.",
 		"defuse/php-encryption": "Required to use CryptoHelper"
 	}
 }

docs/caching.md

@@ -0,0 +1,18 @@
+## Caching
+
+# Standard Caching
+
+Object descriptions that are requested through the ObjectRetriever are fetched through the CloudObjects Core Object API. They are cached in-memory inside the class for a default of 60 seconds. This can be changed using the `cache_ttl` option, which takes a number of seconds.
+
+This in-class memory obviously only works as long as the class is alive and prevents subsequent requests for the same object hitting the API, but the cache will not exist between multiple requests handled in different processes. For this purpose, an external cache should be added.
+
+To add an external cache, provide a storage using the `cache_storage` interface. The storage must be a class that implements either of the following interfaces:
+
+- `Kevinrob\GuzzleCache\Storage\CacheStorageInterface`
+- `Psr\Cache\CacheItemPoolInterface`
+- `Psr\SimpleCache\CacheInterface`
+
+External storage is used twice:
+
+- Storing the HTTP request according to the APIs caching headers.
+- Storing the object data according to `cache_ttl`.

docs/options.md

@@ -0,0 +1,16 @@
+## Options
+
+The `ObjectRetriever` constructor accepts an associative array of options. All options are optional; any option not specified uses its default value.
+
+| Key | Description | Default value |
+| --- | --- | --- |
+| `cache_storage` | External cache storage; must implement `Kevinrob\GuzzleCache\Storage\CacheStorageInterface`, `Psr\Cache\CacheItemPoolInterface` or `Psr\SimpleCache\CacheInterface`. See [caching](caching.md). | `null` |
+| `cache_prefix` | Prefix for all keys written to the external cache. | `'clobj:'` |
+| `cache_ttl` | Number of seconds that object descriptions are cached, both in memory and in the external cache. | `60` |
+| `static_config_path` | Path to a directory with static object descriptions, which are used instead of the API. Objects are read from `<path>/<namespace>/<path of COID>/object.jsonld`. | `null` |
+| `auth_ns` | Hostname of the namespace to authenticate as, e.g. `example.com`. | `null` |
+| `auth_secret` | Shared secret between the authenticating namespace and CloudObjects. | `null` |
+| `api_base_url` | Base URL of the CloudObjects Core Object API. If not set, `https://od.coid.link/` is used. | `null` |
+| `logger` | Logger implementing `Psr\Log\LoggerInterface`, which receives info messages about object retrieval. | `null` |
+| `timeout` | Total timeout for API requests, in seconds. | `20` |
+| `connect_timeout` | Timeout for establishing a connection to the API, in seconds. | `5` |

functions.php

@@ -0,0 +1,23 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+use ML\IRI\IRI;
+use CloudObjects\SDK\CloudObject,
+    CloudObjects\SDK\ObjectRetrieverFacade;
+
+if (!function_exists('cloudobjects_get_object')) {
+    /**
+     * Retrieve a CloudObject by COID. Accepts a COID as an IRI object or a string.
+     */
+    function cloudobjects_get_object($coid) : ?CloudObject {
+        if (is_string($coid))
+            $coid = new IRI($coid);
+        elseif (!($coid instanceof IRI))
+            throw new InvalidArgumentException('COID must be a string or an IRI object.');
+
+        return ObjectRetrieverFacade::getCloudObject($coid);
+    }
+}

phpunit.xml

@@ -1,13 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit backupGlobals="false"
-         backupStaticAttributes="false"
          colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
          processIsolation="false"
          stopOnFailure="false"
-         syntaxCheck="false"
          bootstrap="./tests/bootstrap.php">
     <testsuites>
         <testsuite name="OfflineTests">

run-docker-testsuite.sh

@@ -0,0 +1,5 @@
+docker run -d -v .:/root --name cloudobjects-sdk-test cloudobjects/php-build-base:8.4
+docker exec -t cloudobjects-sdk-test bash -c "cd /root && composer install"
+docker exec -t cloudobjects-sdk-test bash -c "cd /root && vendor/bin/phpunit"
+docker stop cloudobjects-sdk-test
+docker rm cloudobjects-sdk-test

tests/OfflineTests/AccountGateway/AAUIDParserTest.php

@@ -8,7 +8,7 @@ namespace CloudObjects\SDK\AccountGateway;
 
 use ML\IRI\IRI;
 
-class AAUIDParserTest extends \PHPUnit_Framework_TestCase {
+class AAUIDParserTest extends \PHPUnit\Framework\TestCase {
 
   public function testValidAccountAAUID() {
     $aauid = new IRI('aauid:abcd1234abcd1234');

tests/OfflineTests/AccountGateway/AccountContextParseTest.php

@@ -9,7 +9,7 @@ namespace CloudObjects\SDK\AccountGateway;
 use GuzzleHttp\Psr7\Request as GuzzlePsrRequest;
 use Symfony\Component\HttpFoundation\Request as SymfonyRequest;
 
-class AccountContextParseTest extends \PHPUnit_Framework_TestCase {
+class AccountContextParseTest extends \PHPUnit\Framework\TestCase {
 
     public function testParsePsrRequest() {
         $request = new GuzzlePsrRequest('GET', '/', [

tests/OfflineTests/AccountGateway/AccountContextTest.php

@@ -8,11 +8,11 @@ namespace CloudObjects\SDK\AccountGateway;
 
 use ML\IRI\IRI;
 
-class AccountContextTest extends \PHPUnit_Framework_TestCase {
+class AccountContextTest extends \PHPUnit\Framework\TestCase {
 
     private $context;
 
-    protected function setUp() {
+    protected function setUp(): void {
         $this->context = new AccountContext(new IRI('aauid:aaaabbbbccccdddd'), 'DUMMY');
     }
 

tests/OfflineTests/COIDParserTest.php

@@ -8,18 +8,26 @@ namespace CloudObjects\SDK;
 
 use ML\IRI\IRI;
 
-class COIDParserTest extends \PHPUnit_Framework_TestCase {
+class COIDParserTest extends \PHPUnit\Framework\TestCase {
 
     public function testRootCOID() {
         $coid = new IRI('coid://example.com');
         $this->assertEquals(COIDParser::COID_ROOT, COIDParser::getType($coid));
+
+        $coid = new IRI('coid://subdomain.example.com');
+        $this->assertEquals(COIDParser::COID_ROOT, COIDParser::getType($coid));
+
+        $coid = new IRI('coid://anotherlevel.subdomain.example.com');
+        $this->assertEquals(COIDParser::COID_ROOT, COIDParser::getType($coid));
     }
 
     public function testInvalidRootCOID() {
         $coid = new IRI('coid://example');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('coid://exämple.com');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('coid://ex&mple.com');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
     }
@@ -27,34 +35,41 @@ class COIDParserTest extends \PHPUnit_Framework_TestCase {
     public function testInvalidCOID() {
         $coid = new IRI('http://example.com');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('example.com');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('COID://example.com');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('Coid://example.com');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('coid://EXAMPLE.COM');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+    
         $coid = new IRI('coid://exAMPle.CoM');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
     }
 
     public function testUnversionedCOID() {
-    $coid = new IRI('coid://example.com/Example');
+        $coid = new IRI('coid://subdomain.example.com/Example');
         $this->assertEquals(COIDParser::COID_UNVERSIONED, COIDParser::getType($coid));
     }
 
     public function testInvalidUnversionedCOID() {
         $coid = new IRI('coid://example.com/Exümple');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('coid://example.com/Examp%e');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
     }
 
     public function testVersionedCOID() {
-    $coid = new IRI('coid://example.com/Example/1.0');
+        $coid = new IRI('coid://anotherlevel.subdomain.example.com/Example/1.0');
         $this->assertEquals(COIDParser::COID_VERSIONED, COIDParser::getType($coid));
-    $coid = new IRI('coid://example.com/Example/alpha');
+
+        $coid = new IRI('coid://subdomain.example.com/Example/alpha');
         $this->assertEquals(COIDParser::COID_VERSIONED, COIDParser::getType($coid));
     }
 
@@ -66,8 +81,10 @@ class COIDParserTest extends \PHPUnit_Framework_TestCase {
     public function testVersionWildcardCOID() {
         $coid = new IRI('coid://example.com/Example/^1.0');
         $this->assertEquals(COIDParser::COID_VERSION_WILDCARD, COIDParser::getType($coid));
+
         $coid = new IRI('coid://example.com/Example/~1.0');
         $this->assertEquals(COIDParser::COID_VERSION_WILDCARD, COIDParser::getType($coid));
+
         $coid = new IRI('coid://example.com/Example/1.*');
         $this->assertEquals(COIDParser::COID_VERSION_WILDCARD, COIDParser::getType($coid));
     }
@@ -75,6 +92,7 @@ class COIDParserTest extends \PHPUnit_Framework_TestCase {
     public function testInvalidVersionWildcardCOID() {
         $coid = new IRI('coid://example.com/Example/^1.*');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
+
         $coid = new IRI('coid://example.com/Example/1.a.*');
         $this->assertEquals(COIDParser::COID_INVALID, COIDParser::getType($coid));
     }

tests/OfflineTests/Common/CryptoHelperTest.php

@@ -11,7 +11,7 @@ use GuzzleHttp\Client, GuzzleHttp\Handler\MockHandler,
     GuzzleHttp\HandlerStack, GuzzleHttp\Psr7\Response;
 use CloudObjects\SDK\ObjectRetriever;
 
-class CryptoHelperTest extends \PHPUnit_Framework_TestCase {
+class CryptoHelperTest extends \PHPUnit\Framework\TestCase {
 
     private $retriever;
     private $graph;
@@ -22,7 +22,7 @@ class CryptoHelperTest extends \PHPUnit_Framework_TestCase {
         $this->retriever->setClient(new Client(['handler' => $handler]));
       }
 
-    public function setUp() {
+    protected function setUp(): void {
         $this->retriever = new ObjectRetriever([
             'auth_ns' => 'test.cloudobjects.io',
             'auth_secret' => 'TEST'

tests/OfflineTests/FunctionsTest.php

@@ -0,0 +1,63 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+namespace CloudObjects\SDK;
+
+use ML\IRI\IRI;
+use ReflectionProperty,
+    InvalidArgumentException;
+
+class FunctionsTest extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        $prop = new ReflectionProperty(ObjectRetrieverFacade::class, 'instance');
+        $prop->setAccessible(true);
+        $prop->setValue(null, null);
+    }
+
+    private function makeMockRetrieverReturning(?CloudObject $object) : ObjectRetriever {
+        $mock = $this->createMock(ObjectRetriever::class);
+        $mock->method('getCloudObject')->willReturn($object);
+        return $mock;
+    }
+
+    public function testAcceptsIRI(): void {
+        $coid = new IRI('coid://cloudobjects.io');
+        $mockObject = $this->createMock(CloudObject::class);
+
+        $mockRetriever = $this->createMock(ObjectRetriever::class);
+        $mockRetriever->expects($this->once())
+            ->method('getCloudObject')
+            ->with($coid)
+            ->willReturn($mockObject);
+
+        ObjectRetrieverFacade::setObjectRetriever($mockRetriever);
+
+        $this->assertSame($mockObject, cloudobjects_get_object($coid));
+    }
+
+    public function testConvertsStringToIRI(): void {
+        $mockObject = $this->createMock(CloudObject::class);
+
+        $mockRetriever = $this->createMock(ObjectRetriever::class);
+        $mockRetriever->expects($this->once())
+            ->method('getCloudObject')
+            ->with($this->callback(fn($arg) => $arg instanceof IRI && (string)$arg === 'coid://cloudobjects.io'))
+            ->willReturn($mockObject);
+
+        ObjectRetrieverFacade::setObjectRetriever($mockRetriever);
+
+        $this->assertSame($mockObject, cloudobjects_get_object('coid://cloudobjects.io'));
+    }
+
+    public function testThrowsOnInvalidArgumentType(): void {
+        ObjectRetrieverFacade::setObjectRetriever($this->makeMockRetrieverReturning(null));
+
+        $this->expectException(InvalidArgumentException::class);
+        cloudobjects_get_object(42);
+    }
+
+}

tests/OfflineTests/JSON/SchemaValidatorTest.php

@@ -10,12 +10,12 @@ use InvalidArgumentException;
 use ML\JsonLD\JsonLD;
 use CloudObjects\SDK\ObjectRetriever;
 
-class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
+class SchemaValidatorTest extends \PHPUnit\Framework\TestCase {
 
     private $schemaValidator;
     private $graph;
 
-    public function setUp() {
+    protected function setUp(): void {
         $this->schemaValidator = new SchemaValidator(new ObjectRetriever);
         $this->graph = JsonLD::getDocument('{}')->getGraph();
     }
@@ -24,10 +24,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/String'));
         $this->schemaValidator->validateAgainstNode("Test", $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testNotString() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/String'));
@@ -38,10 +39,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Number'));
         $this->schemaValidator->validateAgainstNode(3.5, $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testNotNumber() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Number'));
@@ -52,10 +54,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Integer'));
         $this->schemaValidator->validateAgainstNode(12, $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testNotInteger() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Integer'));
@@ -66,10 +69,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Array'));
         $this->schemaValidator->validateAgainstNode([ 1, 2, "foo" ], $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testNotArray() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Array'));
@@ -83,10 +87,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
             'a' => 'A',
             'b' => 'B'
         ], $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testNotObject() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $node = $this->graph->createNode();
         $node->setType($this->graph->createNode('coid://json.co-n.net/Object'));
@@ -105,10 +110,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
             'a' => 'A',
             'b' => 'B'
         ], $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testObjectWithPropertyTypeError() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $stringNode = $this->graph->createNode();
         $stringNode->setProperty('coid://json.co-n.net/hasKey', 'a');
@@ -136,10 +142,11 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
             'a' => 'A',
             'b' => 'B'
         ], $node);
+        $this->addToAssertionCount(1);
     }
 
     public function testObjectWithRequiredPropertyTypeError() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $stringNode = $this->graph->createNode();
         $stringNode->setProperty('coid://json.co-n.net/hasKey', 'a');
@@ -156,7 +163,7 @@ class SchemaValidatorTest extends \PHPUnit_Framework_TestCase {
     }
 
     public function testObjectWithRequiredPropertyMissing() {
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $stringNode = $this->graph->createNode();
         $stringNode->setProperty('coid://json.co-n.net/hasKey', 'a');

tests/OfflineTests/NodeReaderMockTest.php

@@ -7,10 +7,11 @@
 namespace CloudObjects\SDK;
 
 use ML\IRI\IRI;
+use ML\JsonLD\Node;
 use GuzzleHttp\Client, GuzzleHttp\Handler\MockHandler,
     GuzzleHttp\HandlerStack, GuzzleHttp\Psr7\Response;
 
-class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
+class NodeReaderMockTest extends \PHPUnit\Framework\TestCase {
 
     private $retriever;
     private $reader;
@@ -24,10 +25,11 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
     private function useRootResourceMock() {
         $this->setMockResponse(new Response(200,
             ['Content-Type' => 'application/ld+json'],
-      '{"@context":{"co":"coid:\/\/cloudobjects.io\/","rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#","agws":"coid:\/\/aauid.net\/","rdfs":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#"},"@id":"coid:\/\/cloudobjects.io","@type":["agws:Service","co:Namespace"],"co:isAtRevision":"6-fbea0c90b2c5e5300e4039ed99be9b2d","co:isVisibleTo":{"@id":"co:Public"},"co:recommendsPrefix":"co","co:wasUpdatedAt":{"@type":"http:\/\/www.w3.org\/2001\/XMLSchema#dateTime","@value":"2017-01-16T17:29:22+00:00"},"rdfs:comment":"The CloudObjects namespace defines the essential objects.","rdfs:label":"CloudObjects"}'));
+            '{"@context":{"co":"coid:\/\/cloudobjects.io\/","rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#","agws":"coid:\/\/aauid.net\/","rdfs":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#"},"@id":"coid:\/\/cloudobjects.io","@type":["agws:Service","co:Namespace"],"co:isAtRevision":"6-fbea0c90b2c5e5300e4039ed99be9b2d","co:isVisibleTo":{"@id":"co:Public"},"co:recommendsPrefix":"co","co:wasUpdatedAt":{"@type":"http:\/\/www.w3.org\/2001\/XMLSchema#dateTime","@value":"2017-01-16T17:29:22+00:00"},"rdfs:comment":"The CloudObjects namespace defines the essential objects.","rdfs:label":"CloudObjects"}'
+        ));
     }
 
-  protected function setUp() {
+    protected function setUp(): void {
         $this->retriever = new ObjectRetriever;
         $this->reader = new NodeReader([
             'prefixes' => [
@@ -35,12 +37,13 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
                 'rdfs' => 'http://www.w3.org/2000/01/rdf-schema#'
             ]
         ]);
+        $this->retriever->setDefaultReader($this->reader);
     }
 
     public function testHasType1() {    
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
     
         $this->assertTrue($this->reader->hasType($object, 'coid://cloudobjects.io/Namespace'));
         $this->assertTrue($this->reader->hasType($object, 'co:Namespace'));
@@ -51,7 +54,7 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
     public function testHasPropertyValue1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
 
         $this->assertTrue($this->reader->hasPropertyValue($object, 'http://www.w3.org/2000/01/rdf-schema#label', 'CloudObjects'));
         $this->assertTrue($this->reader->hasPropertyValue($object, 'rdfs:label', 'CloudObjects'));
@@ -60,7 +63,7 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
     public function testGetFirstValueString1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
     
         $this->assertEquals('CloudObjects', $this->reader->getFirstValueString($object, 'http://www.w3.org/2000/01/rdf-schema#label'));
         $this->assertEquals('CloudObjects', $this->reader->getFirstValueString($object, 'rdfs:label'));
@@ -70,36 +73,72 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
 
         $this->assertEquals('theDefaultValue', $this->reader->getFirstValueString($object, 'coid://cloudobjects.io/makesTriplesVisibleTo', 'theDefaultValue'));
         $this->assertEquals('theDefaultValue', $this->reader->getFirstValueString($object, 'co:makesTriplesVisibleTo', 'theDefaultValue'));
+
+        $object = $this->retriever->getCloudObject($coid);
+        
+        $this->assertEquals('CloudObjects', $object->getString('http://www.w3.org/2000/01/rdf-schema#label'));
+        $this->assertEquals('CloudObjects', $object->getString('rdfs:label'));
+
+        $this->assertNull($object->getString('coid://cloudobjects.io/makesTriplesVisibleTo'));
+        $this->assertNull($object->getString('co:makesTriplesVisibleTo'));
+
+        $this->assertEquals('theDefaultValue', $object->getString('coid://cloudobjects.io/makesTriplesVisibleTo', 'theDefaultValue'));
+        $this->assertEquals('theDefaultValue', $object->getString('co:makesTriplesVisibleTo', 'theDefaultValue'));
     }
 
     public function testGetFirstValueIRI1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
 
-    $this->assertInstanceOf('ML\IRI\IRI', $this->reader->getFirstValueIRI($object, 'coid://cloudobjects.io/isVisibleTo'));
-    $this->assertInstanceOf('ML\IRI\IRI', $this->reader->getFirstValueIRI($object, 'co:isVisibleTo'));
+        $this->assertInstanceOf(IRI::class, $this->reader->getFirstValueIRI($object, 'coid://cloudobjects.io/isVisibleTo'));
+        $this->assertInstanceOf(IRI::class, $this->reader->getFirstValueIRI($object, 'co:isVisibleTo'));
     
         $this->assertEquals(new IRI('coid://cloudobjects.io/Public'), $this->reader->getFirstValueIRI($object, 'coid://cloudobjects.io/isVisibleTo'));
         $this->assertEquals(new IRI('coid://cloudobjects.io/Public'), $this->reader->getFirstValueIRI($object, 'co:isVisibleTo'));
+
+        $object = $this->retriever->getCloudObject($coid);
+
+        $this->assertInstanceOf(IRI::class, $object->getIRI('coid://cloudobjects.io/isVisibleTo'));
+        $this->assertInstanceOf(IRI::class, $object->getIRI('co:isVisibleTo'));
+
+        $this->assertEquals(new IRI('coid://cloudobjects.io/Public'), $object->getIRI('coid://cloudobjects.io/isVisibleTo'));
+        $this->assertEquals(new IRI('coid://cloudobjects.io/Public'), $object->getIRI('co:isVisibleTo'));
     }
 
     public function testGetFirstValueNode1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
 
-    $this->assertInstanceOf('ML\JsonLD\Node', $this->reader->getFirstValueNode($object, 'coid://cloudobjects.io/isVisibleTo'));
-    $this->assertInstanceOf('ML\JsonLD\Node', $this->reader->getFirstValueNode($object, 'co:isVisibleTo'));
+        $this->assertInstanceOf(Node::class, $this->reader->getFirstValueNode($object, 'coid://cloudobjects.io/isVisibleTo'));
+        $this->assertInstanceOf(Node::class, $this->reader->getFirstValueNode($object, 'co:isVisibleTo'));
     
         $this->assertEquals('coid://cloudobjects.io/Public', $this->reader->getFirstValueNode($object, 'coid://cloudobjects.io/isVisibleTo')->getId());
         $this->assertEquals('coid://cloudobjects.io/Public', $this->reader->getFirstValueNode($object, 'co:isVisibleTo')->getId());
+
+        $object = $this->retriever->getCloudObject($coid);
+
+        $this->assertInstanceOf(Node::class, $object->getNode('coid://cloudobjects.io/isVisibleTo'));
+        $this->assertInstanceOf(Node::class, $object->getNode('co:isVisibleTo'));
+
+        $this->assertEquals('coid://cloudobjects.io/Public', $object->getNode('coid://cloudobjects.io/isVisibleTo')->getId());
+        $this->assertEquals('coid://cloudobjects.io/Public', $object->getNode('co:isVisibleTo')->getId());
+    }
+
+    public function testConstants() {
+        $coid = new IRI('coid://cloudobjects.io');
+        $this->useRootResourceMock();
+        $object = $this->retriever->getCloudObject($coid);
+
+        $this->assertEquals('6-fbea0c90b2c5e5300e4039ed99be9b2d', $object->getRevision());
+        $this->assertEquals('CloudObjects', $object->getLabel());
     }
 
     public function testGetAllValuesString1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
     
         $this->assertCount(1, $this->reader->getAllValuesString($object, 'http://www.w3.org/2000/01/rdf-schema#label'));
         $this->assertCount(1, $this->reader->getAllValuesString($object, 'rdfs:label'));
@@ -116,7 +155,7 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
     public function testGetAllValuesIRI1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
 
         $this->assertCount(0, $this->reader->getAllValuesIRI($object, 'http://www.w3.org/2000/01/rdf-schema#label'));
         $this->assertCount(0, $this->reader->getAllValuesIRI($object, 'rdfs:label'));
@@ -126,8 +165,8 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
 
         $this->assertCount(2, $this->reader->getAllValuesIRI($object, '@type'));
 
-    $this->assertInstanceOf('ML\IRI\IRI', $this->reader->getAllValuesIRI($object, 'coid://cloudobjects.io/isVisibleTo')[0]);
-    $this->assertInstanceOf('ML\IRI\IRI', $this->reader->getAllValuesIRI($object, 'co:isVisibleTo')[0]);
+        $this->assertInstanceOf(IRI::class, $this->reader->getAllValuesIRI($object, 'coid://cloudobjects.io/isVisibleTo')[0]);
+        $this->assertInstanceOf(IRI::class, $this->reader->getAllValuesIRI($object, 'co:isVisibleTo')[0]);
 
         $this->assertEquals(new IRI('coid://cloudobjects.io/Public'), $this->reader->getAllValuesIRI($object, 'coid://cloudobjects.io/isVisibleTo')[0]);
         $this->assertEquals(new IRI('coid://cloudobjects.io/Public'), $this->reader->getAllValuesIRI($object, 'co:isVisibleTo')[0]);
@@ -136,7 +175,7 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
     public function testGetAllValuesNode1() {
         $coid = new IRI('coid://cloudobjects.io');
         $this->useRootResourceMock();
-    $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
 
         $this->assertCount(0, $this->reader->getAllValuesNode($object, 'http://www.w3.org/2000/01/rdf-schema#label'));
         $this->assertCount(0, $this->reader->getAllValuesNode($object, 'rdfs:label'));
@@ -146,8 +185,8 @@ class NodeReaderMockTest extends \PHPUnit_Framework_TestCase {
 
         $this->assertCount(2, $this->reader->getAllValuesNode($object, '@type'));
 
-    $this->assertInstanceOf('ML\JsonLD\Node', $this->reader->getAllValuesNode($object, 'coid://cloudobjects.io/isVisibleTo')[0]);
-    $this->assertInstanceOf('ML\JsonLD\Node', $this->reader->getAllValuesNode($object, 'co:isVisibleTo')[0]);
+        $this->assertInstanceOf(Node::class, $this->reader->getAllValuesNode($object, 'coid://cloudobjects.io/isVisibleTo')[0]);
+        $this->assertInstanceOf(Node::class, $this->reader->getAllValuesNode($object, 'co:isVisibleTo')[0]);
 
         $this->assertEquals('coid://cloudobjects.io/Public', $this->reader->getAllValuesNode($object, 'coid://cloudobjects.io/isVisibleTo')[0]->getId());
         $this->assertEquals('coid://cloudobjects.io/Public', $this->reader->getAllValuesNode($object, 'co:isVisibleTo')[0]->getId());

tests/OfflineTests/ObjectRetrieverFacadeTest.php

@@ -0,0 +1,76 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+namespace CloudObjects\SDK;
+
+use Exception;
+use ML\IRI\IRI;
+use ML\JsonLD\Node;
+use ReflectionProperty;
+
+class ObjectRetrieverFacadeTest extends \PHPUnit\Framework\TestCase {
+
+    protected function setUp(): void {
+        $prop = new ReflectionProperty(ObjectRetrieverFacade::class, 'instance');
+        $prop->setAccessible(true);
+        $prop->setValue(null, null);
+    }
+
+    public function testThrowsExceptionBeforeInitialization(): void {
+        $this->expectException(Exception::class);
+        ObjectRetrieverFacade::getObjectNode(new IRI('coid://cloudobjects.io'));
+    }
+
+    public function testForwardsGetObjectNodeToInstance(): void {
+        $coid = new IRI('coid://cloudobjects.io');
+        $mockNode = $this->createMock(Node::class);
+
+        $mockRetriever = $this->createMock(ObjectRetriever::class);
+        $mockRetriever->expects($this->once())
+            ->method('getObjectNode')
+            ->with($coid)
+            ->willReturn($mockNode);
+
+        ObjectRetrieverFacade::setObjectRetriever($mockRetriever);
+
+        $this->assertSame($mockNode, ObjectRetrieverFacade::getObjectNode($coid));
+    }
+
+    public function testForwardsGetCloudObjectToInstance(): void {
+        $coid = new IRI('coid://cloudobjects.io');
+        $mockCloudObject = $this->createMock(CloudObject::class);
+
+        $mockRetriever = $this->createMock(ObjectRetriever::class);
+        $mockRetriever->expects($this->once())
+            ->method('getCloudObject')
+            ->with($coid)
+            ->willReturn($mockCloudObject);
+
+        ObjectRetrieverFacade::setObjectRetriever($mockRetriever);
+
+        $this->assertSame($mockCloudObject, ObjectRetrieverFacade::getCloudObject($coid));
+    }
+
+    public function testReplacingRetrieverUsesNewInstance(): void {
+        $coid = new IRI('coid://cloudobjects.io');
+        $mockNode = $this->createMock(Node::class);
+
+        $firstRetriever = $this->createMock(ObjectRetriever::class);
+        $firstRetriever->expects($this->never())->method('getObjectNode');
+
+        $secondRetriever = $this->createMock(ObjectRetriever::class);
+        $secondRetriever->expects($this->once())
+            ->method('getObjectNode')
+            ->with($coid)
+            ->willReturn($mockNode);
+
+        ObjectRetrieverFacade::setObjectRetriever($firstRetriever);
+        ObjectRetrieverFacade::setObjectRetriever($secondRetriever);
+
+        $this->assertSame($mockNode, ObjectRetrieverFacade::getObjectNode($coid));
+    }
+
+}

tests/OfflineTests/ObjectRetrieverMockTest.php

@@ -9,8 +9,9 @@ namespace CloudObjects\SDK;
 use ML\IRI\IRI;
 use GuzzleHttp\Client, GuzzleHttp\Handler\MockHandler,
     GuzzleHttp\HandlerStack, GuzzleHttp\Psr7\Response;
+use CloudObjects\SDK\Exceptions\CoreAPIException;
 
-class ObjectRetrieverMockTest extends \PHPUnit_Framework_TestCase {
+class ObjectRetrieverMockTest extends \PHPUnit\Framework\TestCase {
 
     private $retriever;
 
@@ -20,21 +21,53 @@ class ObjectRetrieverMockTest extends \PHPUnit_Framework_TestCase {
         $this->retriever->setClient(new Client(['handler' => $handler]));
     }
 
-  protected function setUp() {
+    protected function setUp(): void {
         $this->retriever = new ObjectRetriever;
     }
 
     public function testGetRootResource() {
         $this->setMockResponse(new Response(200,
             ['Content-Type' => 'application/ld+json'],
-      '{"@context":{"cloudobjects":"coid:\/\/cloudobjects.io\/","rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#","rdfs":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#"},"@id":"coid:\/\/cloudobjects.io","@type":"cloudobjects:Namespace","cloudobjects:hasPublicListing":"true","cloudobjects:revision":"1-325baa62b76105f56dc09386f5a2ec91","rdfs:comment":"The CloudObjects namespace defines the essential objects.","rdfs:label":"CloudObjects"}'));
+            '{"@context":{"cloudobjects":"coid:\/\/cloudobjects.io\/","rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#","rdfs":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#"},"@id":"coid:\/\/cloudobjects.io","@type":"cloudobjects:Namespace","cloudobjects:hasPublicListing":"true","cloudobjects:revision":"1-325baa62b76105f56dc09386f5a2ec91","rdfs:comment":"The CloudObjects namespace defines the essential objects.","rdfs:label":"CloudObjects"}'
+        ));
 
         $coid = new IRI('coid://cloudobjects.io');
-    $object = $this->retriever->getObject($coid);
+
+        // Test node interface first
+        $object = $this->retriever->getObjectNode($coid);
         $this->assertNotNull($object);
-    $this->assertEquals((string)$coid, $object->getID());
+        $this->assertEquals((string)$coid, $object->getId());
         $this->assertNotNull($object->getProperty('http://www.w3.org/2000/01/rdf-schema#label'));
         $this->assertEquals('CloudObjects', $object->getProperty('http://www.w3.org/2000/01/rdf-schema#label')->getValue());
+        $this->assertNull($object->getProperty('urn:example:nonexistingvalue'));
+
+        // Test CloudObject interface
+        $object = $this->retriever->getCloudObject($coid);
+        $this->assertNotNull($object);
+        $this->assertEquals((string)$coid, $object->getAsNode()->getId());
+        $this->assertEquals($coid, $object->getCOID());
+        $this->assertNotNull($object->getString('http://www.w3.org/2000/01/rdf-schema#label'));
+        $this->assertEquals('CloudObjects', $object->getString('http://www.w3.org/2000/01/rdf-schema#label'));
+        $this->assertNull($object->getString('urn:example:nonexistingvalue'));
+    }
+
+    public function testGetNonExistingResource() {
+        $this->setMockResponse(new Response(404));
+
+        // should return "null"        
+        $coid = new IRI('coid://nonexistingresource.example.com');
+
+        $object = $this->retriever->getObjectNode($coid);
+        $this->assertNull($object);
+    }
+
+    public function testWhenAPIThrowsError() {
+        $this->setMockResponse(new Response(500));
+
+        $coid = new IRI('coid://nonexistingresource.example.com');
+
+        $this->expectException(CoreAPIException::class);
+        $this->retriever->getObjectNode($coid);
     }
 
 }

tests/OnlineTests/JSON/SchemaValidatorPublicTest.php

@@ -10,11 +10,11 @@ use InvalidArgumentException;
 use ML\IRI\IRI;
 use CloudObjects\SDK\ObjectRetriever;
 
-class SchemaValidatorPublicTest extends \PHPUnit_Framework_TestCase {
+class SchemaValidatorPublicTest extends \PHPUnit\Framework\TestCase {
 
     private $schemaValidator;
 
-    public function setUp() {
+    protected function setUp(): void {
         $this->schemaValidator = new SchemaValidator(new ObjectRetriever);
     }
 
@@ -24,10 +24,11 @@ class SchemaValidatorPublicTest extends \PHPUnit_Framework_TestCase {
             'region' => 'Hessen',
             'country-name' => 'Germany'
         ], new IRI('coid://json.co-n.net/Address'));
+        $this->addToAssertionCount(1);
     }
 
     public function testNotAddress() {        
-        $this->setExpectedException(InvalidArgumentException::class);
+        $this->expectException(InvalidArgumentException::class);
 
         $this->schemaValidator->validateAgainstCOID([
             'region' => 'Hessen',

tests/OnlineTests/ObjectRetrieverCacheTest.php

@@ -0,0 +1,54 @@
+<?php
+
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+ 
+namespace CloudObjects\SDK;
+
+use ML\IRI\IRI;
+use Kevinrob\GuzzleCache\Storage\VolatileRuntimeStorage;
+use CloudObjects\SDK\TestHelpers\InMemoryLogger;
+
+class ObjectRetrieverCacheTest extends \PHPUnit\Framework\TestCase {
+
+    public function testCacheInRuntimeStorage() {
+        $cacheStorage = new VolatileRuntimeStorage;
+        $logger = new InMemoryLogger;
+
+        $coid = new IRI('coid://cloudobjects.io');
+
+        $retriever = new ObjectRetriever([
+            'cache_storage' => $cacheStorage,
+            'logger' => $logger
+        ]);
+
+        $object1 = $retriever->getCloudObject($coid);
+
+        $this->assertNotNull($object1);
+        $this->assertNotNull($cacheStorage->fetch($retriever->getCacheKey((string)$coid)));
+        $this->assertStringContainsString('from Core API', $logger->getLastLogMessage());
+
+        // Get from same retriever, assert in-memory-cache
+        $object2 = $retriever->getCloudObject($coid);
+
+        $this->assertNotNull($object1);
+        $this->assertStringContainsString('previous', $logger->getLastLogMessage());
+
+        // Reinitialize retriever with same cache storage to verify that cache is used
+        $retriever = new ObjectRetriever([
+            'cache_storage' => $cacheStorage,
+            'logger' => $logger
+        ]);
+
+        $object3 = $retriever->getCloudObject($coid);
+
+        $this->assertNotNull($object2);
+        $this->assertNotNull($cacheStorage->fetch($retriever->getCacheKey((string)$coid)));
+        $this->assertStringContainsString('from object cache', $logger->getLastLogMessage());
+
+        $this->assertEquals($object1->getRevision(), $object2->getRevision());
+        $this->assertEquals($object2->getRevision(), $object3->getRevision());
+    }
+
+}

tests/OnlineTests/ObjectRetrieverPublicTest.php

@@ -8,11 +8,11 @@ namespace CloudObjects\SDK;
 
 use ML\IRI\IRI;
 
-class ObjectRetrieverTest extends \PHPUnit_Framework_TestCase {
+class ObjectRetrieverPublicTest extends \PHPUnit\Framework\TestCase {
 
     private $retriever;
 
-    protected function setUp() {
+    protected function setUp(): void {
         $this->retriever = new ObjectRetriever;
     }
 
@@ -26,13 +26,25 @@ class ObjectRetrieverTest extends \PHPUnit_Framework_TestCase {
 
     public function testGetRootObject() {
         $coid = new IRI('coid://cloudobjects.io');
-        $object = $this->retriever->getObject($coid);
+        $object = $this->retriever->getObjectNode($coid);
         $this->assertNotNull($object);
-        $this->assertEquals((string)$coid, $object->getID());
+        $this->assertEquals((string)$coid, $object->getId());
         $this->assertNotNull($object->getProperty('http://www.w3.org/2000/01/rdf-schema#label'));
         $this->assertEquals('CloudObjects', $object->getProperty('http://www.w3.org/2000/01/rdf-schema#label')->getValue());        
     }
 
+    public function testGetRelatedObject() {
+        $coid = new IRI('coid://cloudobjects.io');
+        $object = $this->retriever->getCloudObject($coid);
+        $this->assertNotNull($object);
+        $this->assertNotNull($object->getIRI('coid://cloudobjects.io/isVisibleTo'));
+        $this->assertEquals('coid://cloudobjects.io/Public', $object->getString('coid://cloudobjects.io/isVisibleTo'));
+        
+        $relatedObject = $object->getCloudObject('coid://cloudobjects.io/isVisibleTo');
+        $this->assertNotNull($relatedObject);
+        $this->assertEquals('coid://cloudobjects.io/Public', (string)$relatedObject->getCOID());
+    }
+
     public function testGetCOIDList() {
         $coid = new IRI('coid://cloudobjects.io');
         $list = $this->stringifyItems(