Added global function cloudobjects_get_object()

CloudObjects/SDK/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);
+    }
+}

composer.json

@@ -21,7 +21,10 @@
 	"autoload": {
 		"psr-0": {
 			"CloudObjects\\SDK" : ""
-		}
+		},
+		"files": [
+			"CloudObjects/SDK/functions.php"
+		]
 	},
 	"require-dev" : {
 		"phpunit/phpunit": "^10",

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);
+    }
+
+}