vientodigital / vimeo-api
Official PHP library for the Vimeo API.
Requires
- php: >=7.1.0
- ext-curl: *
- ext-json: *
- ankitpokhrel/tus-php: ^v1.0.0
Requires (Dev)
- php-coveralls/php-coveralls: ^1.0
- phpunit/phpunit: ^7.4
- vimeo/psalm: ^2.0
README
This is a fork of the official PHP library for the Vimeo API modified to work with @composer.
This is a simple PHP library for interacting with the Vimeo API.
- Get started with the Vimeo API
- Direct Help
- Installation
- Usage
- Troubleshooting
- Framework integrations
- Contributors
Get started with the Vimeo API
There is a lot of information about the Vimeo API at https://developer.vimeo.com/api/start. Most of your questions are answered there!
Direct Help
NOTE: How to use the PHP library with Vimeo dot notation documentation.
The API docs often uses dot notation to represent a hierarchy of data, like this: privacy.view
. Because this library sends all data using JSON, you must use nested associative arrays, not dot notation.
// The documentation refers to the following as `privacy.view` $params = ['privacy' => ['view' => 'disable']];
Installation
- Require this package, with Composer, in the root directory of your project.
composer require vimeo/vimeo-api
Please note that this library requires at least PHP 7.1 installed. If you are on PHP 5.6, or PHP 7.0, please use install the package with the following:
composer require vimeo/vimeo-api ^2.0
- Use the library
$lib = new \Vimeo\Vimeo($client_id, $client_secret)
.
Usage
Generate your access token
All requests require access tokens. There are two types of access tokens:
- Unauthenticated - Access tokens without a user. These tokens can view only public data.
- Authenticated - Access tokens with a user. These tokens interact on behalf of the authenticated user.
Unauthenticated
Unauthenticated API requests must generate an access token. You should not generate a new access token for each request. Instead, request an access token once and use it forever.
// `scope` is an array of permissions your token needs to access. // You can read more at https://developer.vimeo.com/api/authentication#supported-scopes $token = $lib->clientCredentials(scope); // usable access token var_dump($token['body']['access_token']); // accepted scopes var_dump($token['body']['scope']); // use the token $lib->setToken($token['body']['access_token']);
Authenticated
- Build a link to Vimeo so your users can authorize your app.
$url = $lib->buildAuthorizationEndpoint($redirect_uri, $scopes, $state)
-
Your user needs to access the authorization endpoint (either by clicking the link or through a redirect). On the authorization endpoint, the user will have the option to deny your app any scopes you have requested. If they deny your app, they are redirected back to your
redirect_url
with anerror
parameter. -
If the user accepts your app, they are redirected back to your
redirect_uri
with acode
andstate
query parameter (eg. http://yourredirect.com?code=abc&state=xyz).- You must validate that the
state
matches your state from Step 1. - If the state is valid, you can exchange your code and
redirect_uri
for an access token.
- You must validate that the
// `redirect_uri` must be provided, and must match your configured URI $token = $lib->accessToken(code, redirect_uri); // Usable access token var_dump($token['body']['access_token']); // Accepted scopes var_dump($token['body']['scope']); // Set the token $lib->setToken($token['body']['access_token']);
For additional information, check out the example.
Make requests
The API library has a request
method that takes three parameters. It returns an associative array containing all of the relevant request information.
Usage
$response = $lib->request('/me/videos', ['per_page' => 2], 'GET');
Response
The response array contains three keys.
$response = $lib->request('/me/videos', ['per_page' => 2], 'GET'); var_dump($response['body']);
Uploading videos
Upload videos from the server
To upload videos, you must call the upload
method. It accepts two parameters. It returns the URI of the new video.
Internally, this library executes a tus
upload approach and sends a file to the server with the tus upload protocol.
For more information, check out the example
$response = $lib->upload('/home/aaron/Downloads/ada.mp4') // With parameters. $response = $lib->upload('/home/aaron/Downloads/ada.mp4', [ 'name' => 'Ada', 'privacy' => [ 'view' => 'anybody' ] ])
Replace videos from the server
To replace the source file of a video, you must call the replace
method. It accepts two parameters. It returns the URI of the replaced video.
$response = $lib->replace('/videos/12345', '/home/aaron/Downloads/ada-v2.mp4')
Upload or replace videos from the client
To upload from the client, you must mix some server-side and client-side API requests. We support two workflows, the first of which is much easier than the second.
Simple POST uploads
This workflow is well documented on Vimeo's developer site. You can read more here: https://developer.vimeo.com/api/upload/videos#simple-upload.
Streaming uploads
Streaming uploads support progress bars and resumable uploading. If you want to perform these uploads client-side, you need to start with some server-side requests.
Read through the Vimeo documentation first. Steps 1 and 4 should be performed on the server, while Steps 2 and 3 can be performed on the client. With this workflow, the video is never transferred to your servers.
Upload videos from a URL
Uploading videos from a public URL (also called "pull uploads") uses a single, simple API call.
$video_response = $lib->request( '/me/videos', [ 'upload' => [ 'approach' => 'pull', 'link' => $url ], ], 'POST' );
Upload images
To upload an image, call the uploadImage
method. It takes three parameters.
For more information check out the example.
$response = $lib->uploadImage('/videos/12345/pictures', '/home/aaron/Downloads/ada.png', true)
Troubleshooting
If you have any questions or problems, create a ticket or contact us.
Framework integrations
- WordPress - http://vimeography.com/
- Laravel - https://github.com/vimeo/laravel
If you have integrated Vimeo into a popular PHP framework, let us know!
Contributors
To see the contributors, please visit the contributors graph.