# CloudObjects PHP SDK

[![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 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).

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();
```

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.

```php
use CloudObjects\SDK\ObjectRetriever;
use ML\IRI\IRI;

$retriever = new ObjectRetriever([
    'auth_ns' => 'example.com',
    'auth_secret' => 'YOUR_SHARED_SECRET',
]);

$object = $retriever->getCloudObject(new IRI('coid://example.com/PrivateObject'));

// Retrieve the object describing the authenticating namespace itself
$namespace = $retriever->getAuthenticatingNamespaceCloudObject();
echo $namespace->getLabel();
```

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).

### 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).