Documentation / Library Reference
The Echove Library Reference provides information on all available methods and all possible error responses.
The Echove PHP library contains four primary sections for helping you build your application. Core methods directly interact with the Echove class, Read methods correspond to Brightcove API read methods, Write methods correspond to Brightcove API write methods, and Convenience methods are available to help you convert returned data into a useful type for PHP.
__construct
Summary
The constructor for the Echove class.
Arguments
| Name | Default | Type | Description |
| token_read | NULL | String | The read API token for the Brightcove account |
| token_write | NULL | String | The write API token for the Brightcove account |
Properties
| Name | Access | Type | Description |
| page_number | Public | Integer | The value of the last 'page_number' return |
| page_size | Public | Integer | The value of the last 'page_size' return |
| total_count | Public | Integer | The value of the last 'total_count' return |
| api_calls | Private | Integer | The total number of API calls that have been processed |
| bit32 | Private | Boolean | Whether Echove is operating in 32-bit compatibility mode |
| media_delivery | Private | String | What type of URL to return for UDS assets |
| secure | Private | Boolean | Whether Echove is operating over HTTPS |
| show_notices | Private | Boolean | Whether Echove will send error notices |
| timeout_attempts | Private | Integer | The number of times to retry a call in case of API timeout |
| timeout_current | Private | Integer | The current API timeout retry attempt |
| timeout_delay | Private | Integer | Number of seconds to delay retry attempts |
| timeout_retry | Private | Boolean | Whether to automatically retry calls that fail due to API timeout |
| token_read | Private | String | The read Brightcove token to use |
| token_write | Private | String | The write Brightcove token to use |
| url_read | Private | String | The Brightcove Read API URL |
| url_write | Private | String | The Brightcove Write API URL |
| valid_types | Private | Array | An array of valid object / media asset types |
__set
Summary
Sets a property of the Echove class.
Arguments
| Name | Type | Description |
| key | String | The property to set |
| value | Mixed | The new value for the property |
Return
| Type | Description |
| Mixed | The new value of the property |
__get
Summary
Retrieves a property of the Echove class.
Arguments
| Name | Type | Description |
| key | String | The property to retrieve |
Return
| Type | Description |
| Mixed | The value of the property |
find
Summary
Formats the request for any API "Find" methods and retrieves the data.
The requested call may be written in a shortened version (e.g. "allVideos" or "all_videos" instead of "find_all_videos").
If the call supports get_item_count, it is defaulted to TRUE.
Arguments
| Name | Default | Type | Description |
| call | | String | The requested API method |
| params | NULL | Mixed | A key-value array of API parameters, or a single value that matches the default |
Return
| Type | Description |
| Object | An object containing all API return data |
findAll
Summary
Finds all media assets in account, ignoring pagination.
This method should be used with extreme care as accounts with a large library of assets will require a high number of API calls. This could significantly affect performance and may result in additional charges from Brightcove.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of object to retrieve |
| params | NULL | Array | A key-value array of API parameters |
Return
| Type | Description |
| Object | An object containing all API return data |
search
Summary
Performs a search of video meta data
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of objects to retrieve |
| terms | NULL | Array | The terms to use for the search |
| params | NULL | Mixed | A key-value array of API parameters |
Return
| Type | Description |
| Object | An object containing all API return data |
createMedia
Summary
Uploads a media asset file to Brightcove.
When creating an asset from an upload it is suggested that you first move the file out of the temporary directory where PHP placed it and rename the file to it's original name.
An asset name and short description are both required; leaving these values blank will cause them to be populated with the current UNIX timestamp.
Certain upload settings are not allowed depending upon what default have already been set, and depending on the type of file being uploaded. Setting the incorrect values for these parameters will trigger a notice.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of object to upload |
| file | NULL | String | The location of the temporary file |
| meta | | Array | The media asset information |
| options | NULL | Array | Optional upload values |
Return
| Type | Description |
| Integer | The media asset ID |
createPlaylist
Summary
Creates a playlist.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of playlist to create |
| meta | | Array | The playlist information |
Return
| Type | Description |
| Mixed | The playlist ID |
update
Summary
Updates a media asset.
Only the meta data that has changed needs to be passed along. Be sure to include the asset ID, though.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of object to update |
| meta | | Array | The information for the media asset |
Return
| Type | Description |
| DTO | The new DTO |
createImage
Summary
Uploads a media image file to Brightcove.
When creating an image it is suggested that you first move the file out of the temporary directory where PHP placed it and rename the file to it's original name.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of object to upload image for |
| file | NULL | String | The location of the temporary file |
| meta | | Array | The image information |
| id | NULL | Integer | The ID of the media asset to assign the image to |
| ref_id | NULL | String | The reference ID of the media asset to assign the image to |
| resize | TRUE | Boolean | Whether or not to resize the image on upload |
Return
| Type | Description |
| Mixed | The image asset |
createOverlay
Summary
Uploads a logo overlay file to Brightcove.
When creating a logo overlay it is suggested that you first move the file out of the temporary directory where PHP placed it and rename the file to it's original name.
Arguments
| Name | Default | Type | Description |
| file | NULL | String | The location of the temporary file |
| meta | | Array | The logo overlay information |
| id | NULL | Integer | The ID of the media asset to assign the logo overlay to |
| ref_id | NULL | String | The reference ID of the media asset to assign the logo overlay to |
Return
| Type | Description |
| Mixed | The logo overlay asset |
deleteOverlay
Summary
Deletes a logo overlay.
Arguments
| Name | Default | Type | Description |
| id | NULL | Integer | The ID of the media asset |
| ref_id | NULL | String | The reference ID of the media asset |
| options | NULL | Array | Optional values |
delete
Summary
Deletes a media asset.
Either an ID or Reference ID must be passed.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of item to delete |
| id | NULL | Integer | The ID of the media asset |
| ref_id | NULL | String | The reference ID of the media asset |
| options | NULL | Array | Optional values |
getStatus
Summary
Retrieves the status of a media asset upload.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of object to check |
| id | NULL | String | The ID of the media asset |
| ref_id | TRUE | String | The reference ID of the media asset |
Return
| Type | Description |
| String | The upload status |
shareMedia
Summary
Shares a media asset with the selected accounts.
Sharing must be enabled between the two accounts.
Arguments
| Name | Default | Type | Description |
| type | video | String | The type of object to share |
| id | | Integer | The ID of the media asset |
| account_ids | | Array | An array of account IDs |
| accept | FALSE | Boolean | Whether the share should be auto accepted |
| force | FALSE | Boolean | Whether the share should overwrite existing copies of the media |
Return
| Type | Description |
| Array | The new media asset IDs |
removeFromPlaylist
Summary
Removes assets from a playlist.
Arguments
| Name | Type | Description |
| playlist_id | Integer | The ID of the playlist to modify |
| video_ids | Array | An array of video IDs to delete from the playlist |
Return
| Type | Description |
| Array | The new playlist DTO |
addToPlaylist
Summary
Adds assets to a playlist.
Arguments
| Name | Type | Description |
| playlist_id | Integer | The ID of the playlist to modify |
| video_ids | Array | An array of video IDs to add to the playlist |
Return
| Type | Description |
| Array | The new playlist DTO |
time
Summary
Converts milliseconds to formatted time or seconds.
Arguments
| Name | Default | Type | Description |
| ms | | Integer | The length of the media asset in milliseconds |
| seconds | FALSE | Boolean | Whether to return only seconds |
Return
| Type | Description |
| Mixed | The formatted length or total seconds of the media asset |
tags
Summary
Parses media asset tags array into a key-value array.
Arguments
| Name | Default | Type | Description |
| tags | | Array | The tags array from a media asset DTO |
| implode | FALSE | Boolean | Return array to Brightcove format |
Return
| Type | Description |
| Mixed | A key-value array of tags, or a comma-separated string |
filter
Summary
Removes assets that don't contain the appropriate tags.
Arguments
| Name | Default | Type | Description |
| videos | | Array | All the assets you wish to filter |
| tag | | String | A comma-separated list of tags to filter on |
Return
| Type | Description |
| Array | The filtered list of assets |
sef
Summary
Formats a media asset name to be search-engine friendly.
Arguments
| Name | Default | Type | Description |
| name | | String | The asset name |
Return
| Type | Description |
| String | The search-engine friendly asset name |
EchoveApiError
Summary
This is the most generic error returned from Echove as it is thrown whenever the API returns unexpected data, or an error. The API return data will be included in the error to help you diagnose the problem.
EchoveDeprecated
Summary
The requested item is no longer supported by Brightcove and/or Echove. Stop using this method as early as possible, as the item could be removed in any future release.
EchoveDtoDoesNotExist
Summary
The specified asset does not exist in the Brightcove system. Ensure you're using the correct ID.
EchoveIdNotProvided
Summary
An ID has not been passed to the method (usually a "delete" or "share" function). Include the ID parameter to resolve the error.
EchoveInvalidFileType
Summary
The file being passed to the function is not supported. Try another file type to resolve the error.
EchoveInvalidMethod
Summary
The "find" method being requested is not supported by Echove, or does not exist in the Brightcove API. Remove the method call and check both the Echove and Brightcove API documentation.
EchoveInvalidProperty
Summary
The Echove property you are trying to set or retrieve does not exist. Check the Echove documentation.
EchoveInvalidType
Summary
The DTO type (video, playlist, image, etc) you specified is not allowed for the method. Check both the Echove and Brightcove API documentation.
EchoveSearchTermsNotProvided
Summary
Please specify one or more search parameters. Verify you are passing the parameters in an array.
EchoveTokenError
Summary
The read or write token you provided is not recognized by Brightcove. Verify you are using the correct token.
EchoveTransactionError
Summary
The API could not be accessed, or the API did not return any data. Verify the server has cURL installed, enabled, and able to retrieve remote data. Verify the Brightcove API is currently available.
