Commit e8599f3f authored by Keven's avatar Keven
Browse files

Reworked API and doc

parent fa5189d5
......@@ -10,8 +10,7 @@ and be easy to use:
Example:
```php
$folder = $client->createFolder('test');
$file = $client->sendFile('MyVideo.mp4', '/path/to/file', $folder);
$file = $client->createFolder('test')->upload('/path/to/file');
$file->publishTo('http://console.libcast.com/services/stream/test-stream');
```
......@@ -19,7 +18,18 @@ $file->publishTo('http://console.libcast.com/services/stream/test-stream');
Install
-------
```bash
### Installing via Composer (recommended)
Install [Composer](https://getcomposer.org/download/) and run the following command
to get the latest version:
```shell
composer require libcast/client ~2.0
```
### Installing the development version
```shell
git clone https://code.libcast.net/libcast/Client.git
cd Client
composer install
......@@ -27,13 +37,12 @@ composer install
To generate API doc:
```php
```shell
php vendor/bin/sami.php update sami.php
```
API doc is also available online: https://developers.libcast.com/php-client/
Usage
-----
......@@ -44,17 +53,243 @@ use Libcast\Client\LibcastClient;
$client = new LibcastClient('https://console.libcast.com/services/', $username, $password);
```
On entities, properties can be accessed directly:
```php
$media->name = 'Assets for Q2 meeting'
echo $media->name;
```
or using accessors/mutators if you prefer:
```php
$media->setName('Assets for Q2 meeting');
echo $media->getName();
```
Related entities can only be accessed via an accessor:
```php
foreach ($media->streams() as $stream) {
// ...
}
```
Each entity has a `href` property which is its unique identifier, in a restful way:
```php
echo $media->href;
```
A helper method `push` on the client allows to execute both creation and modification
requests:
```php
$platform = new Platform('My platform');
// Creation
$platform = $client->push($platform);
// Modification
$platform->name = 'My modified platform';
$platform = $client->push($platform);
```
When creating or updating an entity, you must assign the result of the command to
a platform in order to hydrate the variable with the URL of the platform and its
default values given by the server.
Complete API
------------
// Platfoms
array of Platform $client->platforms()
Platform $client->createPlatform(Platform $platform)
Platform $client->updatePlatform(Platform $platform)
$client->updatePlatform(Platform $platform)
Due to access control rules, you may not be able to use all the following features.
### Briefcase
```php
// Retrieve the content (files and folders) of the root of the briefcase
$rootFolder = $client->files()
// Retrieve a file or folder by its URL
$client->file($url)
$client->folder($url)
// Create a folder
$client->createFolder('My new folder') // Folder is created in the root
$client->createFolder('My new folder', $parentFolder)
// or:
$folder = new Folder('My new folder')
$folder = $client->push($folder) // Folder is created in the root
$folder = $client->push($folder, $parentFolder)
// Modify a folder
$folder->name = 'My temporary folder';
$client->push($folder)
// Upload a file
$file = $folder->upload('/path/to/the/file');
// or:
$file = $folder->upload('/path/to/the/file', 'My Awesome Movie');
// Modify a file
$file->name = 'Q2 meeting';
$client->push($file);
// Folder properties
$folder->name // Name of the folder
// Folder relations
$folder->subfolders() // List of subfolders
$folder->parent() // The parent folder, if any
$folder->files() // List the files in the folder
// File properties
$file->name // Name of the file
$file->size // Size in bytes (immutable)
$file->embed // Embed code to view the file (immutable)
$file->encodingStatus // Whether or not the file encoding is done (immutable)
$file->thumbnail // URL to the file thumbnail (immutable)
```
int $platform->getName()
### Platform
```php
// Retrieve all the platforms from the instance
$client->platforms()
// Retrieve one platform by its URL
$platform = $client->platform($url)
// Create a platform
$platform = $client->push(new Platform('My platform'))
// Modify a platform
$platform->name = 'My newest platform'
$client->push($platform)
// Platform properties
$platform->name // Name of the platform. It does not have to be unique
$platform->maxUsers // Maximum number of users available in the platform
$platform->createdUsers // Actual number of users in the platform (immutable)
$platform->maxSpace // Maximum disk space available in the platform (in bytes)
$platform->usedSpace // Actual space used in the platform (immutable)
// Platform relations
$platform->users() // Retrieve the user list
$platform->addUser($user) // Add a user to the platform (the user is pushed to the server)
$platform->medias() // Retrieve the media list
$platform->addMedia($media) // Add a media to the platform (the media is pushed to the server)
$platform->roles() // Retrieve the role list
$platform->addRole($role) // Add a role to the platform (the role is pushed to the server)
$platform->profiles() // Retrieve the profile list
$platform->addProfile($profile) // Add a profile to the platform (the profile is pushed to the server)
```
### Media
```php
// Retrieve all the medias of a platform
$platform->medias()
// Retrieve one media by its URL
$media = $client->media($url)
// Create a media
$media = new Media('My media', 'mymedia.example.com', 'This is my media, 'contact@example.com')
$media = $client->push($media, $platform)
// or:
$media = $platform->addMedia($media)
// Modify a media
$media->name = 'My even better media'
$client->push($media)
// Media properties
$media->name // Name of the media. It does not have to be unique
$media->domainName // Unique domain name for the media
$media->description // Optional description
$media->contactEmail // Required email address to contact the admin of the media
$media->maxStreams // Optional maximum streams the media can contain (0 means unlimited)
// Media relations
$media->platform() // Retrieve the platform of the media
$media->streams() // Retrieve the stream list
$media->addStream($stream) // Add a stream to the media (the stream is pushed to the server)
$media->channels() // Retrieve the publication channel list
$media->addChannel($role) // Add a publication channel to the media (the channel is pushed to the server)
```
### Stream
```php
// Retrieve all the streams of a media
$media->streams()
// Retrieve one stream by its URL
$stream = $client->stream($url)
// Create a stream
$stream = new Stream('2015 conference')
$stream = $client->push($stream, $media)
// or:
$stream = $media->addStream($stream)
// Modify a stream
$stream->description = 'All the talks from the 2015 conference'
$client->push($stream)
// Stream properties
$stream->title // Title of the stream
$stream->subTitle // Optional subtitle for the stream
$stream->description // Optional description
$stream->visibility // Visibility of the stream (public, hidden, protected)
// Stream relations
$stream->resources() // List the resources in the stream
```
### Resource
```php
// Retrieve all the resources of a stream
$stream->resources()
// Retrieve one resource by its URL
$resource = $client->resource($url)
// Publish
$resource = new Resource($file)
$resource = $client->push($resource, $stream)
// or:
$resource = $file->publishTo($stream)
// Modify a resource
$resource->subTitle = 'Edited by T. Abrams'
$client->push($stream)
// Resource properties
$resource->title // Title of the stream
$resource->subtitle // Optional subtitle for the stream
$resource->publishedAt // Publication date (may be in the future to schedule a publication)
$resource->visibility // Visibility of the stream (public, hidden, protected)
$resource->embed // Embed of the resource (immutable)
$resource->metadata // Array of metadata
$resource->usages // Collection of usages
$resource->widgets // Collection of widgets
// Usage of widgets
foreach ($resource->widgets as $embed) echo urldecode($embed);
// Resource relations
$media->file() // Retrieve the file of the resource (only if the file belongs to you)
$media->stream() // Retrieve the stream of the resource
```
License
......
......@@ -19,10 +19,10 @@ class CreateFolder extends FolderCommand
* name. If not submitted, the folder is created
* under the root folder.
*/
public function __construct(FolderInterface $folder, $parent = null)
public function __construct($folder, $parent = null)
{
$this->setFolder($parent);
$this->setPayload(['name' => $folder->getName()]);
$this->setPayload(['name' => $folder instanceof FolderInterface ? $folder->getName() : $folder]);
}
}
<?php
namespace Libcast\Client\Command;
/**
* Alias for folder command
*/
class Files extends Folder
{
}
......@@ -10,6 +10,12 @@ class Profiles extends ProfileCommand
*/
protected $path = '/platform/{name}/profiles';
/**
*
* @var string
*/
protected $objectClass = 'Libcast\Client\Entity\Profile';
/**
*
* @var boolean
......@@ -22,6 +28,16 @@ class Profiles extends ProfileCommand
*/
public function __construct($platform = null)
{
$this->setPlatform($platform);
if (is_null($platform)) {
return;
}
if ($platform instanceof \Libcast\Client\Entity\Platform) {
$this->setVar('name', $platform->slug);
} elseif ('http' == substr($platform, 0, 4)) {
$this->fullPath = $platform;
} else {
$this->setVar('name', $platform);
}
}
}
\ No newline at end of file
}
......@@ -23,7 +23,7 @@ class Roles extends Command
protected $collectionResponse = true;
/**
*
*
* @param string $platform
*/
public function __construct($platform = null)
......@@ -32,10 +32,12 @@ class Roles extends Command
return;
}
if ('http' == substr($platform, 0, 4)) {
if ($platform instanceof \Libcast\Client\Entity\Platform) {
$this->setVar('name', $platform->slug);
} elseif ('http' == substr($platform, 0, 4)) {
$this->fullPath = $platform;
} else {
$this->setVar('name', $platform);
}
}
}
\ No newline at end of file
}
......@@ -23,7 +23,7 @@ class Users extends Command
protected $collectionResponse = true;
/**
*
*
* @param string $platform
*/
public function __construct($platform = null, $filters = array())
......@@ -36,7 +36,9 @@ class Users extends Command
return;
}
if ('http' == substr($platform, 0, 4)) {
if ($platform instanceof \Libcast\Client\Entity\Platform) {
$this->fullPath = $platform->href;
} elseif ('http' == substr($platform, 0, 4)) {
$this->fullPath = $platform;
} else {
$this->setVar('name', $platform);
......@@ -44,7 +46,7 @@ class Users extends Command
}
/**
*
*
* @todo This should use a real URI Template resolver
* @param string $path
* @param array $vars
......
<?php
namespace Libcast\Client\Entity;
class Builder
{
/**
*
* @param array $properties
*
* @return mixed
*/
public static function create($properties = [])
{
}
}
......@@ -33,17 +33,6 @@ abstract class Entity implements ClientAwareInterface, WarmableInterface
*/
protected $changes = array();
/**
*
* @param array $properties
*/
public function __construct($properties = [])
{
foreach ($properties as $property => $value) {
$this->setProperty($property, $value);
}
}
/**
*
* @return string
......@@ -201,17 +190,32 @@ abstract class Entity implements ClientAwareInterface, WarmableInterface
}
// Collections
if (property_exists($this, $collProperty = 'href'.ucfirst($property))) {
if (0 === strpos($method, 'get') && property_exists($this, $collProperty.'_loaded')) {
return $this->{$collProperty.'_loaded'};
if (property_exists($this, 'href'.ucfirst($property)) or
property_exists($this, 'href'.ucfirst($method))) {
if (property_exists($this, 'href'.ucfirst($property))) {
$collProperty = 'href'.ucfirst($property);
$command = $property;
} else {
$collProperty = 'href'.ucfirst($method);
$command = $method;
}
if (0 === strpos($method, 'set') && property_exists($this, $collProperty)) {
$this->{$collProperty.'_loaded'} = $args[0];
return $this;
}
if (0 === strpos($method, 'get') && property_exists($this, $collProperty)) {
$this->{$collProperty.'_loaded'} = $this->client->$property($this->$collProperty);
if (!property_exists($this, $collProperty.'_loaded')) {
$this->{$collProperty.'_loaded'} = $this->client->$command($this->$collProperty);
return $this->{$collProperty.'_loaded'};
}
return $this->{$collProperty.'_loaded'};
}
$message = sprintf("Call to undefined method %s::%s()", get_class($this), $method);
throw new \RuntimeException($message);
}
}
\ No newline at end of file
}
......@@ -3,6 +3,8 @@
namespace Libcast\Client\Entity;
use Libcast\Client\Model\FileInterface;
use Libcast\Client\Model\ResourceInterface;
use Libcast\Client\Model\StreamInterface;
use JMS\Serializer\Annotation\Type;
use JMS\Serializer\Annotation\XmlRoot;
......@@ -49,6 +51,51 @@ class File extends Entity implements FileInterface
protected $thumbnail;
/**
* URL of the thumbnail
*
* You can change the size of pointed thumbnail py providing width and height parameters
*
* @param int $width The width of the thumbnail
* @param int $height The height of the thumbnail
*
* @return string
*/
protected function getThumbnail($height = null, $width = null)
{
if ($height)
{
$this->thumbnail = substr($this->thumbnail, 0, strrpos($this->thumbnail, "/")).'/height/'.$height.substr($this->thumbnail, strrpos($this->thumbnail, "/"));
}
if ($width)
{
$this->thumbnail = substr($this->thumbnail, 0, strrpos($this->thumbnail, "/")).'/width/'.$width.substr($this->thumbnail, strrpos($this->thumbnail, "/"));
}
return $this->thumbnail;
}
/**
*
* @param \Libcast\Client\Model\StreamInterface $stream
* @param array $properties Array of Resource properties
*
* @return \Libcast\Client\Model\ResourceInterface
*/
public function publishTo($stream, $properties = [])
{
$resource = new Resource($this);
foreach ($properties as $property => $value) {
$resource->$property = $value;
}
return $this->client->createResource($resource, $stream);
}
// Deprecated API
/**
*
* @deprecated since 2.1.16
* @see File->name
*
* @return string
*/
......@@ -60,6 +107,9 @@ class File extends Entity implements FileInterface
/**
* Size in bytes
*
* @deprecated since 2.1.16
* @see File->size
*
* @return int
*/
public function getSize()
......@@ -68,6 +118,9 @@ class File extends Entity implements FileInterface
}
/**
*
* @deprecated since 2.1.16
* @see File->encodingStatus
*
* @return ???
*/
......@@ -76,37 +129,16 @@ class File extends Entity implements FileInterface
return $this->encodingStatus;
}
/**
* URL of the thumbnail
*
* You can change the size of pointed thumbnail py providing width and height parameters
*
* @param int $width The width of the thumbnail
* @param int $height The height of the thumbnail
*
* @return string
*/
public function getThumbnail($height = null, $width = null)
{
if ($height)
{
$this->thumbnail = substr($this->thumbnail, 0, strrpos($this->thumbnail, "/")).'/height/'.$height.substr($this->thumbnail, strrpos($this->thumbnail, "/"));
}
if ($width)
{
$this->thumbnail = substr($this->thumbnail, 0, strrpos($this->thumbnail, "/")).'/width/'.$width.substr($this->thumbnail, strrpos($this->thumbnail, "/"));
}
return $this->thumbnail;
}
/**
* Code of the embed (URL encoded)
*
* @deprecated since 2.1.16
* @see File->embed
*
* @return string
*/
public function getEmbed()
{
return $this->embed;
}
}
\ No newline at end of file
}
......@@ -44,7 +44,7 @@ class Folder extends Entity implements FolderInterface
*
* @return array
*/
public function getSubfolders()
public function subfolders()
{
$subfolders = array();
foreach ($this->subfolders as $folder) {
......@@ -60,12 +60,53 @@ class Folder extends Entity implements FolderInterface
*
* @return array
*/
public function getFiles()
public function parent()
{
if (!isset($this->_parent)) {
foreach ($this->subfolders as $folder) {
if ($folder->getRelation() == "parent") {
$this->_parent = $this->client->folder($folder->getHref());
}
}
}
return $this->_parent;
}