This SDK allows you to interact with ownCloud Infinite Scale (oCIS) storage using PHP.
You can find a rendered version of the API documentation in our dev docs.
To render the documentation locally, use the phpDocumentor to run it in the local repo. E.g.:
docker run --rm -v ${PWD}:/data phpdoc/phpdoc:3
After that you will find the documentation inside the docs folder.
Add "owncloud/ocis-php-sdk" to the require block in your composer.json and then run composer install.
Warning
The ocis-php-sdk currently relies on a development version of the "owncloud/libre-graph-api-php" package. To ensure proper dependency resolution, it is necessary to set "minimum-stability": "dev" and "prefer-stable": true in your composer.json file.
{
"minimum-stability": "dev",
"prefer-stable": true,
"require": {
"owncloud/ocis-php-sdk": "^1.0"
}
}Alternatively, you can simply run the following from the command line:
composer config minimum-stability dev
composer config prefer-stable true
composer require owncloud/ocis-php-sdkCreate an Ocis object using the service Url and an access token:
$ocis = new Ocis('https://example.ocis.com', $accessToken);Acquiring an access token is out of scope of this SDK, but you can find examples for that below.
Also refreshing tokens is not part of the SDK, but after you got a new token, you can update the Ocis object:
$ocis->setAccessToken($newAccessToken);Drives can be listed using the getAllDrives or the getMyDrives method.
The Drive class is responsible for most file/folder related actions, like listing files, creating folders, uploading files, etc.
// get the personal drive of the authorized user
// `getMyDrives` returns all drives that the user is a member of
// but in this example the result is filtered to only return
// the personal drive (parameter 3 = DriveType::PERSONAL)
$drives = $ocis->getMyDrives(
DriveOrder::NAME,
OrderDirection::ASC,
DriveType::PERSONAL
);
// get the drive id
$id = $drives[0]->getId();
// get the name of the drive
$name = $drives[0]->getName();
// get a link to the drive that can be opened in a browser and will lead the user to the web interface
$webUrl = $drives[0]->getWebUrl();
// create a folder inside the drive
$drives[0]->createFolder("/documents");
// upload a file to the drive
$drives[0]->uploadFile("/documents/myfile.txt", "Hello World!");
// get an array of all resources of the "/documents" folder inside the drive
$resources = $drives[0]->getResources("/documents");Notifications can be listed using the getNotifications method, which will return an array of Notification objects representing all active notifications.
The Notification object can retrieve details of the corresponding notification and mark it as read (delete).
Given the correct permissions, an OcisResource can be shared with a group or a user. To define the access permissions of the receiver every share has to set SharingRole(s).
// get the resources of a subfolder inside a drive
$resources = $drive->getResources("/documents");
// get all roles that are possible for that particular resource
$roles = $resources[0]->getRoles();
// find the role that is allowed to read and write the shared file or folder
for ($roles as $role) {
if ($role->getDisplayName() === 'Can edit') {
$editorRole = $role;
break;
}
}
// find all users with a specific surname
$users = $ocis->getUsers("einstein")[0];
// share the resource with the users
$resources[0]->invite($users, $editorRole);- PHP 8.1 or higher
- oCIS 5.0.0 or higher
For an easier experience in acquiring an access token, several PHP OIDC client libraries are available. The following code snippet showcases how to retrieve an access token with the facile-it/php-openid-client library.
You can install the facile-it/php-openid-client library using composer:
composer require facile-it/php-openid-client
composer require nyholm/psr7
- php-bcmath
- php-gmp
<?php
require __DIR__ . '/path/to/vendor/autoload.php';
use Facile\OpenIDClient\Client\ClientBuilder;
use Facile\OpenIDClient\Issuer\IssuerBuilder;
use Facile\OpenIDClient\Client\Metadata\ClientMetadata;
use Facile\OpenIDClient\Service\Builder\AuthorizationServiceBuilder;
use Nyholm\Psr7\ServerRequest;
$issuer = (new IssuerBuilder())
->build('https://example.ocis.com');
$clientMetadata = ClientMetadata::fromArray([
'client_id' => 'client_id',
'client_secret' => 'client_secret',
'redirect_uris' => [
'http://url-of-this-file',
],
]);
$client = (new ClientBuilder())
->setIssuer($issuer)
->setClientMetadata($clientMetadata)
->build();
$authorizationService = (new AuthorizationServiceBuilder())->build();
$redirectAuthorizationUri = $authorizationService->getAuthorizationUri(
$client,
['scope'=>'openid profile email offline_access']
);
if(!isset($_REQUEST["code"])) {
header('Location: ' . $redirectAuthorizationUri);
} else {
$serverRequest = new ServerRequest('GET', $_SERVER['REQUEST_URI']);
$callbackParams = $authorizationService->getCallbackParams($serverRequest, $client);
$tokenSet = $authorizationService->callback($client, $callbackParams);
// store access and refresh token in database
$accessToken = $tokenSet->getAccessToken();
echo 'AccessToken : ' . $accessToken;
echo '<hr>';
$refreshToken = $tokenSet->getRefreshToken();
echo 'RefreshToken : ' . $refreshToken;
echo '<hr>';
// use this code to get new access token when expired
$tokenSet = $authorizationService->refresh($client, $refreshToken);
$accessToken = $tokenSet->getAccessToken();
echo 'NewAccessToken : ' . $accessToken;
}If you're working in a development environment where you might need to bypass SSL verification (though this is not advised for production environments), here's how:
<?php
...
use Facile\OpenIDClient\Issuer\Metadata\Provider\MetadataProviderBuilder;
use Facile\JoseVerifier\JWK\JwksProviderBuilder;
use Symfony\Component\HttpClient\Psr18Client;
use Symfony\Component\HttpClient\CurlHttpClient;
$symHttpClient = new CurlHttpClient([
'verify_peer' => false,
'verify_host' => false
]);
$httpClient = new Psr18Client($symHttpClient);
$metadataProviderBuilder = (new MetadataProviderBuilder())
->setHttpClient($httpClient);
$jwksProviderBuilder = (new JwksProviderBuilder())
->setHttpClient($httpClient);
$issuer = (new IssuerBuilder())
->setMetadataProviderBuilder($metadataProviderBuilder)
->setJwksProviderBuilder($jwksProviderBuilder)
->build('https://example.ocis.com');
...
$client = (new ClientBuilder())
->setHttpClient($httpClient)
->setIssuer($issuer)
->setClientMetadata($clientMetadata)
->build();
$authorizationService = (new AuthorizationServiceBuilder())
->setHttpClient($httpClient)
->build();
...To test, simply open a browser and head to http://url-of-this-file.
To run the tests locally
-
Install and setup
docker(min version 24) anddocker compose(min version 2.21). -
Ensure that the following php dependencies are installed for executing the integration tests:
- php-curl - php-dom - php-phpdbg - php-mbstring - php-ast -
add these lines to your
/etc/hostsfile:127.0.0.1 ocis.owncloud.test 127.0.0.1 keycloak.owncloud.test -
run whole tests
make test-php-integration // start a full oCIS server with keycloak and other services using docker before running tests -
run single test
make test-php-integration testGetResources // start a full oCIS server with keycloak and other services using docker before running single testIf something goes wrong, use
make cleanto clean the created containers and volumes.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent