README

The Libcast PHP client connects to a Libcast server and provide the same features as the Libcast backend.

It is designed to reflect our webservice API and be easy to use:

Example:

$file = $client->createFolder('test')->upload('/path/to/file');
$file->publishTo('https://api.libcast.com/stream/test-stream');

Install

Installing via Composer (recommended)

Install Composer and run the following command to get the latest version:

composer require libcast/client ~2.0

Installing the development version

git clone https://code.libcast.net/libcast/Client.git
cd Client
composer install

To generate API doc:

php vendor/bin/sami.php update sami.php

Usage

Instantiation:

use Libcast\Client\LibcastClient;
$client = new LibcastClient('https://api.libcast.com/', $username, $password);

On entities, properties can be accessed directly:

$media->name = 'Assets for Q2 meeting'
echo $media->name;

or using accessors/mutators if you prefer:

$media->setName('Assets for Q2 meeting');
echo $media->getName();

Related entities can only be accessed via an accessor:

foreach ($media->streams() as $stream) {
    // ...
}

Each entity has a href property which is its unique identifier, in a restful way:

echo $media->href;

A helper method push on the client allows to execute both creation and modification requests:

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

The client may be used to delete some elements. List of currently deletable elements: Folder, File, Stream, Resource

$client->deleteFile($file);

Complete API

Due to access control rules, you may not be able to use all the following features.

Briefcase

// 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');
// or:
$file = $client->sendFile('My Awesome Movie', '/path/to/the/file', $folder);

// When uploading a big file (by default > 64 MiB), the file is chunked and sent with several requests.
// You can also force this behavior or customize the chunk size:
$folder->upload('/path/to/the/file', 'My Awesome Movie', [
    'chunked'    => true, // Force the file to be chunked (default: FALSE)
    'chunk-size' => 1024*1024, // Chunks size in bytes (default: 64 MiB)
    'autochunk'  => true, // The file will be chunk if its size exceeds the chunk size (default: TRUE)
]);
// These options are also available on sendFile() command:
$file = $client->sendFile('My Awesome Movie', '/path/to/the/file', $folder, ['chunk-size' => 4*1024*1024]);



// Modify a file
$file->name = 'Q2 meeting';
$client->push($file);

// Add subtitles to the file
$file->addSubtitle('/path/to/subtitle/file', 'es');
foreach ($file->subtitles as $subtitle) {
  echo $subtitle->language.': '.$subtitle->href."\n";
}

// Remove subtitles
$file->removeSubtitle($subtitle); // You can also just use a URL
// or:
$client->removeSubtitle($subtitle); // You can also just use a URL

// 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)
$file->duration // Video/Audio duration in seconds

Example to retrieve files and folders

$rootFolder = $client->files();

retrieveFolders($rootFolder);

function retrieveFolders($folder)
{
  retrieveFiles($folder);
  foreach($folder->subfolders() as $subfolder)
  {
    echo '*   '.$subfolder->name.' is a subfolder of '.$folder->name."\n";
    echo '    Folder url: '.$subfolder->href."\n";
    retrieveFolders($subfolder);
  }
}

function retrieveFiles($folder)
{
  foreach($folder->files() as $file)
  {
    echo '  *   File :'.$file->name."\n";
    echo '      File url :' .$file->href."\n";
  }
}

Platform

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

Example to retrieve Platform's properties

$platforms = $client->platforms();

foreach($platforms as $platform)
{
  echo "Name : ". $platform->name . "\n";
  echo "maxUsers : ". $platform->maxUsers . "\n";
  echo "createdUsers : ". $platform->createUsers . "\n";
  echo "maxSpace : ". $platform->maxSpace . "\n";
  echo "usedSpace : ". $platform->usedSpace . "\n";
}
foreach($platform->users() as $platform_user)
{
  $platform_user = $client->user($user->href);
  echo "username : " . $platform_user->name . "\n";
}

Media

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

Example to retrieve Media properties

$medias = $client->medias($platform);

foreach($medias as $media)
{
   $media = $media->href;
   echo "Name : ". $media->name . "\n";
   echo "domainName : ". $media->domainName . "\n";
   echo "description : ". $media->description . "\n";
   echo "contactEmail : ". $media->contactEmail . "\n";
   echo "maxStreams : ". $media->maxStreams . "\n";

   // retrieve publication channels
   foreach($media->channels() as $channel)
   {
      echo "PublicationChannel: ". $channel->name . " - Type : ". $channel->type ."\n";
   }
}

Stream

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

// Create a nested stream
$stream->addChild($otherStream) // Create a sub stream in a stream
$media->addStream($stream, $parentStream)

// 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
$stream->hasParent() // Whether or not the Stream has a parent stream
$stream->parent() // Retrieve the parent stream, or NULL if no parent
$stream->media() // Retrieve the media of the stream

Resource

// Retrieve all the resources of a stream
$stream->resources()

// Retrieve one resource by its URL
$resource = $client->resource($url)

//If you need to retrieve resource properties such as flavors or widgets with a token (if resource is protected)
$resource = $client->resource($url,['with-token' => true])
//Then resource properties like widget iframe or flavor uri will contain a token

// 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->duration // Video/Audio duration in seconds
$resource->views // Overall views on this resource (immutable)
$resource->thumbnail // URL to the Resource thumbnail (immutable)
$resource->embed // Embed of the resource (immutable)
$resource->metadata // Array of metadata
$resource->usages  // Collection of usages
$resource->widgets // Collection of widgets
$resource->flavors // Collection of flavors
$resource->subtitles // Collection of subtitles

// 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

// Resource flavors (additional encodings not reachable from libcast Player)
$resources = $client->resources('stream-slug');
echo "Publications: \n";
foreach ($resources as $resource)
{
 $resource = $client->resource($resource->href);
 echo $resource->title ."\n";
 foreach ($resource->getFlavors() as $flavor)
 {
    echo "Flavor : ". $flavor->getName() ." - ". $flavor->getURI()."\n";
 }
}

License

See LICENSE file.