Skip to content

Commit d3c49b7

Browse files
aaronm67aaronm67
authored
Merge pull request #315 from vimeo/readme-update
2 parents 79885b6 + af888f5 commit d3c49b7

1 file changed

Lines changed: 16 additions & 232 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 232 deletions
Original file line numberDiff line numberDiff line change
@@ -1,258 +1,42 @@
1-
# <img src="https://user-images.githubusercontent.com/33762/33720344-abc20bb8-db31-11e7-8362-59a4985aeff0.png" width="250" />
2-
3-
[![Packagist](https://img.shields.io/packagist/v/vimeo/vimeo-api.svg?style=flat-square)](https://packagist.org/packages/vimeo/vimeo-api)
4-
[![License](https://img.shields.io/packagist/l/vimeo/vimeo-api.svg?style=flat-square)](https://packagist.org/packages/vimeo/vimeo-api)
5-
[![Travis CI](https://img.shields.io/travis/vimeo/vimeo.php.svg?style=flat-square)](https://travis-ci.org/vimeo/vimeo.php)
6-
[![StyleCI](https://styleci.io/repos/9654006/shield?style=flat-square)](https://styleci.io/repos/9654006/)
1+
# Interacting with the Vimeo API using PHP
72

83
This is a simple PHP library for interacting with the [Vimeo API](https://developers.vimeo.com).
94

10-
- [Get Started](#get-started-with-the-vimeo-api)
11-
- [Help](#direct-help)
12-
- [Troubleshooting](#troubleshooting)
13-
- [Installation](#installation)
14-
- [Usage](#usage)
15-
- [Authentication and access tokens](#generate-your-access-token)
16-
- [Unauthenticated tokens](#unauthenticated)
17-
- [Authenticated tokens](#authenticated)
18-
- [Make requests](#make-requests)
19-
- [Uploading videos](#uploading-videos)
20-
- [Upload videos from a server](#upload-videos-from-the-server)
21-
- [Replace videos from a server](#replace-videos-from-the-server)
22-
- [Client side uploads](#upload-or-replace-videos-from-the-client)
23-
- [Upload videos from a URL](#upload-videos-from-a-url)
24-
- [Upload images](#upload-images)
25-
- [Framework integrations](#framework-integrations)
26-
27-
## Get started with the Vimeo API
28-
29-
There is a lot of information about the Vimeo API at <https://developer.vimeo.com/api/start>. Most of your questions are answered there!
5+
## Before you start
306

31-
## Direct Help
7+
### Get started with the Vimeo API
328

33-
* [Stack Overflow](http://stackoverflow.com/questions/tagged/vimeo-api)
34-
* [Vimeo Support](https://vimeo.com/help/contact)
9+
If you’re new to Vimeo APIs, check out [Getting Started: The Basics](https://developer.vimeo.com/api/start) before diving into the content on this page.
3510

36-
#### NOTE: How to use the PHP library with Vimeo dot notation documentation.
11+
### Understand the PHP hierarchy
3712

38-
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.
13+
The API docs often use dot notation to represent a hierarchy of data, such as `privacy.view`. Since the PHP library sends all data using JSON, you must use nested associative arrays instead of dot notation.
3914

4015
```php
4116
// The documentation refers to the following as `privacy.view`
4217
$params = ['privacy' => ['view' => 'disable']];
4318
```
4419

45-
## Installation
46-
1. Require this package, with [Composer](https://getcomposer.org/), in the root directory of your project.
20+
## Install and access the PHP library
4721

48-
```bash
49-
composer require vimeo/vimeo-api
50-
```
51-
52-
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:
22+
To install the PHP library, run the following command:
5323

5424
```bash
55-
composer require vimeo/vimeo-api ^2.0
56-
```
57-
58-
2. Use the library `$lib = new \Vimeo\Vimeo($client_id, $client_secret)`.
59-
60-
## Usage
61-
### Generate your access token
62-
63-
All requests require access tokens. There are two types of access tokens:
64-
65-
- [Unauthenticated](#unauthenticated) - Access tokens without a user. These tokens can view only public data.
66-
- [Authenticated](#authenticated) - Access tokens with a user. These tokens interact on behalf of the authenticated user.
67-
68-
#### Unauthenticated
69-
70-
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.
71-
72-
```php
73-
// `scope` is an array of permissions your token needs to access.
74-
// You can read more at https://developer.vimeo.com/api/authentication#supported-scopes
75-
$token = $lib->clientCredentials(scope);
76-
77-
// usable access token
78-
var_dump($token['body']['access_token']);
79-
80-
// accepted scopes
81-
var_dump($token['body']['scope']);
82-
83-
// use the token
84-
$lib->setToken($token['body']['access_token']);
85-
```
86-
87-
#### Authenticated
88-
89-
1. Build a link to Vimeo so your users can authorize your app.
90-
91-
```php
92-
$url = $lib->buildAuthorizationEndpoint($redirect_uri, $scopes, $state)
93-
```
94-
95-
Name | Type | Description
96-
---------------|----------|------------
97-
`redirect_uri` | string | The URI the user is redirected to in Step 3. This value must be provided to every step of the authorization process, including creating your app, building your authorization endpoint, and exchanging your authorization code for an access token.
98-
`scope` | array | An array of permissions your token needs to access. You can read more at https://developer.vimeo.com/api/authentication#supported-scopes.
99-
`state` | string | A value unique to this authorization request. You should generate it randomly and validate it in Step 3.
100-
101-
2. 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 an `error` parameter.
102-
103-
3. If the user accepts your app, they are redirected back to your `redirect_uri` with a `code` and `state` query parameter (eg. http://yourredirect.com?code=abc&state=xyz).
104-
1. You must validate that the `state` matches your state from Step 1.
105-
2. If the state is valid, you can exchange your code and `redirect_uri` for an access token.
106-
107-
```php
108-
// `redirect_uri` must be provided, and must match your configured URI
109-
$token = $lib->accessToken(code, redirect_uri);
110-
111-
// Usable access token
112-
var_dump($token['body']['access_token']);
113-
114-
// Accepted scopes
115-
var_dump($token['body']['scope']);
116-
117-
// Set the token
118-
$lib->setToken($token['body']['access_token']);
119-
```
120-
121-
For additional information, check out the [example](https://github.com/vimeo/vimeo.php/blob/master/example/auth.php).
122-
123-
### Make requests
124-
125-
The API library has a `request` method that takes three parameters. It returns an associative array containing all of the relevant request information.
126-
127-
#### Usage
128-
129-
Name | Type | Description
130-
----------|----------|------------
131-
`url` | string | The URL path (e.g.: `/users/dashron`).
132-
`params` | string | An object containing all of your parameters (e.g.: `{ "per_page": 5, "filter" : "featured"}` ).
133-
`method` | string | The HTTP method (e.g.: `GET`).
134-
135-
```php
136-
$response = $lib->request('/me/videos', ['per_page' => 2], 'GET');
137-
```
138-
139-
#### Response
140-
141-
The response array contains three keys.
142-
143-
Name | Type | Description
144-
-----------|--------|------------
145-
`body` | array | The parsed request body. All responses are JSON, so we parse this for you and give you the result.
146-
`status` | number | The HTTP status code of the response. This partially informs you about the success of your API request.
147-
`headers` | array | An associative array containing all of the response headers.
148-
149-
```php
150-
$response = $lib->request('/me/videos', ['per_page' => 2], 'GET');
151-
var_dump($response['body']);
152-
```
153-
154-
### Uploading videos
155-
#### Upload videos from the server
156-
157-
To upload videos, you must call the `upload` method. It accepts two parameters. It returns the URI of the new video.
158-
159-
Internally, this library executes a `tus` upload approach and sends a file to the server with the [tus](https://tus.io/) upload protocol.
160-
161-
For more information, check out the [example](https://github.com/vimeo/vimeo.php/blob/master/example/upload.php)
162-
163-
Name | Type | Description
164-
---------|---------|------------
165-
`file` | string | Full path to the upload file on the local system.
166-
`params` | array | Parameters to send when creating a new video (name, privacy restrictions, etc.). See the [`/me/videos` documentation](https://developer.vimeo.com/api/reference/videos#upload_video) for supported parameters.
167-
168-
```php
169-
$response = $lib->upload('/home/aaron/Downloads/ada.mp4')
170-
171-
// With parameters.
172-
$response = $lib->upload('/home/aaron/Downloads/ada.mp4', [
173-
'name' => 'Ada',
174-
'privacy' => [
175-
'view' => 'anybody'
176-
]
177-
])
178-
```
179-
180-
#### Replace videos from the server
181-
182-
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.
183-
184-
Name | Type | Description
185-
------------|----------|------------
186-
`video_uri` | string | The URI of the original video. Once uploaded and successfully transcoded, your source video file is swapped with this new video file.
187-
`file` | string | Full path to the upload file on the local system.
188-
189-
```php
190-
$response = $lib->replace('/videos/12345', '/home/aaron/Downloads/ada-v2.mp4')
191-
```
192-
193-
#### Upload or replace videos from the client
194-
195-
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.
196-
197-
##### Simple POST uploads
198-
199-
This workflow is well documented on Vimeo's developer site. You can read more here: <https://developer.vimeo.com/api/upload/videos#simple-upload>.
200-
201-
##### Streaming uploads
202-
203-
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.
204-
205-
Read through the [Vimeo documentation](https://developer.vimeo.com/api/upload/videos#resumable-upload) 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.
206-
207-
#### Upload videos from a URL
208-
209-
Uploading videos from a public URL (also called "pull uploads") uses a single, simple API call.
210-
211-
```php
212-
$video_response = $lib->request(
213-
'/me/videos',
214-
[
215-
'upload' => [
216-
'approach' => 'pull',
217-
'link' => $url
218-
],
219-
],
220-
'POST'
221-
);
25+
composer require vimeo/vimeo-api
22226
```
22327

224-
#### Using a custom TusClient
225-
226-
If the standard [TusPhp\Client](https://github.com/ankitpokhrel/tus-php/blob/main/src/Tus/Client.php) doesn't work for you,
227-
you can pass in a custom factory for a client that suits your needs. See the [custom_cache example](https://github.com/vimeo/vimeo.php/blob/master/example/upload_image.php).
228-
229-
### Upload images
230-
231-
To upload an image, call the `uploadImage` method. It takes three parameters.
232-
233-
For more information check out the [example](https://github.com/vimeo/vimeo.php/blob/master/example/upload_image.php).
234-
235-
Name | Type | Description
236-
---------------|----------|------------
237-
`pictures_uri` | string | The URI to the pictures collection for a single resource, such as `/videos/12345/pictures`. You can always find this in the resource representation.
238-
`file` | string | Full path to the upload file on the local system.
239-
`activate` | boolean | (Optional) Defaults to `false`. If true, this picture will become the default picture for the associated resource.
240-
241-
```php
242-
$response = $lib->uploadImage('/videos/12345/pictures', '/home/aaron/Downloads/ada.png', true)
243-
```
28+
After installation is complete, you can access the library by using `$lib = new \Vimeo\Vimeo($client_id, $client_secret)` in a Composer-enabled PHP script.
24429

245-
## Troubleshooting
30+
## Advanced examples
24631

247-
If you have any questions or problems, create a [ticket](https://github.com/vimeo/vimeo.php/issues) or [contact us](https://vimeo.com/help/contact).
32+
To see examples of the most common use cases of the PHP library, visit our [PHP Library Examples](https://developer.vimeo.com/api/libraries/examples) page.
24833

24934
## Framework integrations
25035

251-
- **WordPress** - <http://vimeography.com/>
252-
- **Laravel** - <https://github.com/vimeo/laravel>
36+
We have PHP framework integrations for [WordPress](http://vimeography.com/) and [Laravel](https://github.com/vimeo/laravel).
25337

254-
If you have integrated Vimeo into a popular PHP framework, let us know!
38+
If you've integrated Vimeo into a popular PHP framework, [let us know](https://vimeo.com/help/contact)!
25539

256-
## Contributors
40+
## Support
25741

258-
To see the contributors, please visit the [contributors graph](https://github.com/vimeo/vimeo.php/graphs/contributors).
42+
To troubleshoot an issue, reach out to [Vimeo Support](https://vimeo.com/help/contact).

0 commit comments

Comments
 (0)