Documented usage

CloudObjects/SDK/Exceptions/CoreAPIException.php

@@ -11,4 +11,12 @@ namespace CloudObjects\SDK\Exceptions;
  */
 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/ObjectRetriever.php

@@ -283,11 +283,24 @@ class ObjectRetriever implements CustomCacheAndLogInterface {
 				$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);
-				return null;
+				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);
 			}
 		}
 
@@ -337,7 +350,7 @@ class ObjectRetriever implements CustomCacheAndLogInterface {
 
 			$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;
@@ -379,7 +392,7 @@ class ObjectRetriever implements CustomCacheAndLogInterface {
 			$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;
@@ -413,7 +426,7 @@ class ObjectRetriever implements CustomCacheAndLogInterface {
 			$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;
@@ -452,7 +465,7 @@ class ObjectRetriever implements CustomCacheAndLogInterface {
 			$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;

README.md

@@ -14,6 +14,62 @@ Install with the following command:
 composer require cloudobjects/sdk
 ``` 
 
+## Usage
+
+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.
+
+### 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();
+```
+
+### Using the static facade
+
+```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
 
 The PHP SDK is licensed under Mozilla Public License (see LICENSE file).

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

run-docker.sh

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

tests/OfflineTests/ObjectRetrieverMockTest.php

@@ -9,6 +9,7 @@ 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 {
 
@@ -50,4 +51,23 @@ class ObjectRetrieverMockTest extends \PHPUnit\Framework\TestCase {
         $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);
+    }
+
 }