trms/carousel

A PHP package to access Tightrope Media Systems' Carousel Software API

v0.0.5 2018-01-30 17:14 UTC

Requires

• guzzlehttp/guzzle: ~6.0
• larapack/dd: 1.*
• nesbot/carbon: ^1.22
• tightenco/collect: ^5.4

Requires (Dev)

• mockery/mockery: ~0.9.4
• phpunit/phpunit: ~5.4

MIT

• Seth Phillips

README

PHP Package for the Carousel API

This package is designed to be a fluent interface for Tightrope Media Systems' Carousel API. For more information on TRMS and the Carousel software please visit www.trms.com.

Carousel API

This package requires ownership of Carousel software version 7 or greater. General information about the Carousel API can be found on your carousel server at your_carousel_server/carouselapi.

Package Installation

This package should be installed with composer and requires PHP 7+

composer install trms/carousel

Examples

Servers & Requests

The Server Instance

Model Requests

File Upload Requests

Bulletin Order Requests

Carousel Models

Templates

Bulletins

Bulletin & Template Blocks

Groups

Media

Zones

Tags

Bulletin Sorting

Thrown Exceptions

Basic Usage Examples

Creating a server instance

Server methods that return more than one object will return a collection, which can be treated like an array.

use TRMS\Carousel\Server\API;

$server = new Server();
$server->connect('http://my_carousel_server.com', 'username', 'password');

Requesting Carousel Resources

All of the requests for Carousel resources are created by instantiating a ModelRequest with the appropriate Model class name and passing that to the server's get method. Passing an array of parameters to the ModelRequest is also important so that your query is limited to the items you want to get.

For example, to get a set of bulletins in a given zone:

use TRMS\Carousel\Requests\ModelRequest;
use TRMS\Carousel\Models\Bulletin;

$request = new ModelRequest(Bulletin::class, ['ZoneID'=>'5','IsDeleted'=>false]);
$bulletins = $server->get($request);

Saving a Resource

New or existing resources can be saved by passing them to the save method on a server instance.

use TRMS\Carousel\Models\BulletinTag;

$new_tag = new BulletinTag(['TagName'=>'My New Tag']);
$server->save($new_tag);

Creating a Bulletin From A Template

Usually you will be creating new bulletins from existing templates. More information on Templates can be found below. Please note that all bulletins must belong to a group and this group must be created and related to the bulletin first when saving a newly created bulletin. More information on this can be found in the section on Bulletins below.

use TRMS\Carousel\Requests\ModelRequest;
use TRMS\Carousel\Models\Bulletin;
use TRMS\Carousel\Models\Group;
use TRMS\Carousel\Models\Template;


$templates = $server->get(new ModelRequest(Template::class, ['ZoneID'=>'5','IsDeleted'=>false]));
$template = $templates->first(); // the server returns a Laravel Collection.
$bulletin = Bulletin::fromTemplate($templates->first());
// here you would likely modify the bulletin's 'Blocks' to alter content
$group = new Group(['ZoneID'=>'5']);
$server->save($group);
$bulletin->setGroup($group);
$server->save($bulletin);

Creating Content from File Uploads

You can create new Media and Bulletins by uploading a file to the Carousel Server. This is done by instantiating a FileUploadRequest with the appropriate Model class name and an array of parameters passed to the request. ZoneID is required. You will then add the files you wish to upload by chaining addFile methods and then pass the request to the server's upload method. This will return an array of models, one for each file that was added.

use TRMS\Carousel\Request\FileUploadRequest;
use TRMS\Carousel\Model\Media;

$request = new FileUploadRequest(Media::class, ['ZoneID'=>'5']);
$request->addFile('/path/to/local/file.jpg')->addFile('http://path/to/remote/file');

$media = $server->upload($request);

Entities

Servers and Requests

API

TRMS\Carousel\Server\API

This represents the Carousel server itself

Methods

ModelRequest

TRMS\Carousel\Requests\ModelRequest

Model requests are used to get models from the server.

Methods

FileUploadRequest

TRMS\Carousel\Requests\FileUploadRequest

File upload requests are used to post images video or audio to the server in order to create content with it either as Media assets or as Bulletins.

Methods

BulletinOrderRequest

TRMS\Carousel\Requests\BulletinOrderRequest

Bulletin order requests are used to get the Group/Bulletin order for a given Zone. A ZoneID is required as a parameter when creating the request. For more information see the section on bulletin sorting below.

Methods

Models

Bulletin

TRMS\Carousel\Models\Bulletin

A Bulletin is a piece of content displayed in Carousel. The closest analogy would be a slide in a power point deck.

Methods

Properties

Template

TRMS\Carousel\Models\Template

A template is the starting point for a standard Bulletin and is comprised of a background image and a series of content Blocks.

Methods

Properties

BulletinBlock

TRMS\Carousel\Models\BulletinBlock

A BulletinBlock is an area of content within a Bulletin or a Template. Blocks can be Text, Picture, Video, or WebPicture. Text blocks are just that, blocks containing text. Picture and Video blocks will take a Media Object. WebPicture blocks take the URL of an image. There are many properties on a block some of which apply to only one of the four BlockTypes. Many have several properties that are used to make an effect, like a drop shadow or a text glow.

Methods

Properties

Group

TRMS\Carousel\Models\Group

A group is a container for Bulletins that allows for easier viewing sorting and ordering. Of important note is that every Bulletin is contained in a Group and must have a saved Group assigned before saving. (full support of editing groups is a work in progress for this package.)

Methods

Properties

Media

TRMS\Carousel\Models\Media

Media represents audio, video images and backgrounds to be used in Bulletins and Templates. This content is Zone specific for Carousel UI users. When uploading backgrounds the media type must be specified or the system will assume that it is an image. Backgrounds should also be sized for the Zone they are intended for to avoid distorting the image. Video content should be mp4.

Methods

Properties

Zone

TRMS\Carousel\Models\Zone

A Zone is an area of real estate on screen where bulletins are displayed. The screen (Channel) can be comprised of one or more Zones.

Methods

Properties

Tags

Tags are metadata that can be added to the associated model. They are used for searching and sorting content in Carousel.

BulletinTag

TRMS\Carousel\Models\BulletinTag

MediaTag

TRMS\Carousel\Models\MediaTag

ZoneTag

TRMS\Carousel\Models\ZoneTag

Methods

Properties

Bulletin Sorting

These objects are used for ordering the Bulletins in a Zone.

BulletinOrder

TRMS\Carousel\Models\BulletinOrder

This represents the order of the Groups in a Zone. Each BulletinOrderEntry represents a Group. The order of the OrderEntries array will be the order of the Groups in the Zone.

Properties

BulletinOrderEntry

TRMS\Carousel\Models\BulletinOrderEntry

This represents a Group and the order of its Bulletins. The order of the Bulletins array will be the order of the Bulletins in the Group.

Properties

Exceptions

You can expect the following exceptions to be thrown if things go off the rails with the server, or if you attempt to do things that are unsupported or not allowed.

TRMS\Carousel\Exceptions\CarouselAPIException TRMS\Carousel\Exceptions\CarouselModelException TRMS\Carousel\Exceptions\CarouselRequestException