README

This PHP package is a lightweight wrapper for OVH APIs. That's the easiest way to use OVH.com APIs in your PHP applications.

<?php
/**
 * # Instantiate. Visit https://api.ovh.com/createToken/index.cgi?GET=/me
 * to get your credentials
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

$ovh = new Api( $applicationKey,
                $applicationSecret,
                $endpoint,
                $consumer_key);
echo "Welcome " . $ovh->get('/me')['firstname'];
?>

Quickstart

To download this wrapper and integrate it inside your PHP application, you can use Composer.

Quick integration with the following command:

composer require ovh/ovh

Or add the repository in your composer.json file or, if you don't already have this file, create it at the root of your project with this content:

{
    "name": "Example Application",
    "description": "This is an example of OVH APIs wrapper usage",
    "require": {
        "ovh/ovh": "dev-master"
    }
}

Then, you can install OVH APIs wrapper and dependencies with:

php composer.phar install

This will install ovh/ovh to ./vendor, along with other dependencies including autoload.php.

OVH cookbook

Do you want to use OVH APIs? Maybe the script you want is already written in the example part of this repository!

How to login as a user?

To communicate with APIs, the SDK uses a token on each request to identify the user. This token is called Consumer Key. To have a validated Consumer Key, you need to redirect your user on specific authentication page. Once the user has logged in, the token is validated and user will be redirected on $redirection url.

<?php
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

session_start();

// Informations about your application
$applicationKey = "your_app_key";
$applicationSecret = "your_app_secret";
$redirection = "http://your_url.ovh";

// Information about API and rights asked
$endpoint = 'ovh-eu';
$rights = array( (object) [
    'method'    => 'GET',
    'path'      => '/me*'
]);

// Get credentials
$conn = new Api($applicationKey, $applicationSecret, $endpoint);
$credentials = $conn->requestCredentials($rights, $redirection);

// Save consumer key and redirect to authentication page
$_SESSION['consumer_key'] = $credentials["consumerKey"];
header('location: '. $credentials["validationUrl"]);
...
?>

How to use OVH API to enable network burst on SBG1 servers?

<?php
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

// Informations about your application
$applicationKey = "your_app_key";
$applicationSecret = "your_app_secret";
$consumer_key = "your_consumer_key";

// Information about API and rights asked
$endpoint = 'ovh-eu';

// Get servers list
$conn = new Api(    $applicationKey,
                    $applicationSecret,
                    $endpoint,
                    $consumer_key);
$servers = $conn->get('/dedicated/server/');

foreach ($servers as $server) {

    // Search servers inside SBG1
    $details = $conn->get('/dedicated/server/'. $server);
    if ($details['datacenter'] == 'sbg1') {

        // Activate burst on server
        $content = (object) array('status' => "active");
        $conn->put('/dedicated/server/'. $server . '/burst', $content);
        echo "We burst " . $server;
    }
}

?>

How to customize HTTP client configuration?

You can inject your own HTTP client with your specific configuration. For instance, you can edit user-agent and timeout for all your requests

<?php
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;
use GuzzleHttp\Client;

// Informations about your application
$applicationKey = "your_app_key";
$applicationSecret = "your_app_secret";
$consumer_key = "your_consumer_key";

// Information about API and rights asked
$endpoint = 'ovh-eu';

$client = new Client();
$client->setDefaultOption('timeout', 1);
$client->setDefaultOption('headers', array('User-Agent' => 'api_client') );

// Get servers list
$conn = new Api(    $applicationKey,
                    $applicationSecret,
                    $endpoint,
                    $consumer_key,
                    $client);
$webHosting = $conn->get('/hosting/web/');

foreach ($webHosting as $webHosting) {
        echo "One of our web hosting: " . $webHosting . "\n";
}
?>

How to print API error details?

Under the hood, php-ovh uses GuzzlePHP 6 by default to issue API requests. If everything goes well, it will return the response directly as shown in the examples above. If there is an error like a missing endpoint or object (404), an authentication or authorization error (401 or 403) or a parameter error, the Guzzle will raise a GuzzleHttp\Exception\ClientException exception. For server-side errors (5xx), it will raise a GuzzleHttp\Exception\ServerException exception.

You can get the error details with a code like:

<?php
/**
 * # Instantiate. Visit https://api.ovh.com/createToken/index.cgi?GET=/me
 * to get your credentials
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

$ovh = new Api( $applicationKey,
                $applicationSecret,
                $endpoint,
                $consumer_key);

try {
    echo "Welcome " . $ovh->get('/me')['firstname'];
} catch (GuzzleHttp\Exception\ClientException $e) {
    $response = $e->getResponse();
    $responseBodyAsString = $response->getBody()->getContents();
    echo $responseBodyAsString;
}
?>

How to build the documentation?

Documentation is based on phpdocumentor. To install it with other quality tools, you can install local npm project in a clone a project

git clone https://github.com/ovh/php-ovh.git
cd php-ovh
php composer.phar install

To generate documentation, it's possible to use directly:

vendor/bin/phing phpdocs

Documentation is available in docs/ directory.

How to run tests?

Tests are based on phpunit. To install it with other quality tools, you can install local npm project in a clone a project

git https://github.com/ovh/php-ovh.git
cd php-ovh
php composer.phar install

Edit phpunit.xml file with your credentials to pass functionals tests. Then, you can run directly unit and functionals tests with phing.

vendor/bin/phing test

To skip functionals and run unit tests only, you can use the only.units option :

vendor/bin/phing test -Donly.units=true

Supported APIs

OVH Europe

• $endpoint = 'ovh-eu';
• Documentation: https://eu.api.ovh.com/
• Community support: api-subscribe@ml.ovh.net
• Console: https://eu.api.ovh.com/console
• Create application credentials: https://eu.api.ovh.com/createApp/
• Create script credentials (all keys at once): https://eu.api.ovh.com/createToken/

OVH US

• $endpoint = 'ovh-us';
• Documentation: https://api.us.ovhcloud.com/
• Console: https://api.us.ovhcloud.com/console
• Create application credentials: https://api.us.ovhcloud.com/createApp/
• Create script credentials (all keys at once): https://api.us.ovhcloud.com/createToken/

OVH North America

• $endpoint = 'ovh-ca';
• Documentation: https://ca.api.ovh.com/
• Community support: api-subscribe@ml.ovh.net
• Console: https://ca.api.ovh.com/console
• Create application credentials: https://ca.api.ovh.com/createApp/
• Create script credentials (all keys at once): https://ca.api.ovh.com/createToken/

So you Start Europe

• $endpoint = 'soyoustart-eu';
• Documentation: https://eu.api.soyoustart.com/
• Community support: api-subscribe@ml.ovh.net
• Console: https://eu.api.soyoustart.com/console/
• Create application credentials: https://eu.api.soyoustart.com/createApp/
• Create script credentials (all keys at once): https://eu.api.soyoustart.com/createToken/

So you Start North America

• $endpoint = 'soyoustart-ca';
• Documentation: https://ca.api.soyoustart.com/
• Community support: api-subscribe@ml.ovh.net
• Console: https://ca.api.soyoustart.com/console/
• Create application credentials: https://ca.api.soyoustart.com/createApp/
• Create script credentials (all keys at once): https://ca.api.soyoustart.com/createToken/

Kimsufi Europe

• $endpoint = 'kimsufi-eu';
• Documentation: https://eu.api.kimsufi.com/
• Community support: api-subscribe@ml.ovh.net
• Console: https://eu.api.kimsufi.com/console/
• Create application credentials: https://eu.api.kimsufi.com/createApp/
• Create script credentials (all keys at once): https://eu.api.kimsufi.com/createToken/

Kimsufi North America

• $endpoint = 'kimsufi-ca';
• Documentation: https://ca.api.kimsufi.com/
• Community support: api-subscribe@ml.ovh.net
• Console: https://ca.api.kimsufi.com/console/
• Create application credentials: https://ca.api.kimsufi.com/createApp/
• Create script credentials (all keys at once): https://ca.api.kimsufi.com/createToken/

Runabove

• $endpoint = 'runabove-ca';
• Documentation: https://community.runabove.com/kb/en/instances/how-to-use-runabove-api.html
• Community support: https://community.runabove.com
• Console: https://api.runabove.com/console/
• Create application credentials: https://api.runabove.com/createApp/

Related links

• Contribute: https://github.com/ovh/php-ovh
• Report bugs: https://github.com/ovh/php-ovh/issues