This PHP package is a lightweight wrapper for OVHcloud APIs.
The easiest way to use OVHcloud APIs in your PHP applications.
Compatible with PHP 7.4, 8.0, 8.1, 8.2.
Install this wrapper and integrate it inside your PHP application with Composer:
composer require ovh/ovh
<?php
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;
// Api credentials can be retrieved from the urls specified in the "Supported endpoints" section below.
$ovh = new Api($applicationKey,
$applicationSecret,
$endpoint,
$consumerKey);
echo 'Welcome '.$ovh->get('/me')['firstname'];Under the hood, php-ovh uses Guzzle 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:
try {
echo "Welcome " . $ovh->get('/me')['firstname'];
} catch (GuzzleHttp\Exception\ClientException $e) {
$response = $e->getResponse();
$responseBodyAsString = $response->getBody()->getContents();
echo $responseBodyAsString;
}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;
// Instantiate a custom Guzzle HTTP client and tweak it
$client = new Client();
$client->setDefaultOption('timeout', 1);
$client->setDefaultOption('headers', ['User-Agent' => 'api_client']);
// Api credentials can be retrieved from the urls specified in the "Supported endpoints" section below.
// Inject the custom HTTP client as the 5th argument of the constructor
$ovh = new Api($applicationKey,
$applicationSecret,
$endpoint,
$consumerKey,
$client);
echo 'Welcome '.$ovh->get('/me')['firstname'];This flow will allow you to request consumerKey from an OVHcloud account owner. After allowing access to his account, he will be redirected to your application.
See "OVHcloud API authentication" section below for more information about the authorization flow.
use \Ovh\Api;
session_start();
// Api credentials can be retrieved from the urls specified in the "Supported endpoints" section below.
$ovh = new Api($applicationKey,
$applicationSecret,
$endpoint);
// Specify the list of API routes you want to request
$rights = [
[ 'method' => 'GET', 'path' => '/me*' ],
];
// After allowing your application access, the customer will be redirected to this URL.
$redirectUrl = 'https://your_application_redirect_url'
$credentials = $ovh->requestCredentials($rights, $redirectUrl);
// Save consumer key and redirect to authentication page
$_SESSION['consumerKey'] = $credentials['consumerKey'];
header('location: '. $credentials['validationUrl']);
// After successful redirect, the consumerKey in the session will be activated and you will be able to use it to make API requests like in the "Basic usage" section above.Here is a more complex example of how to use the wrapper to enable network burst on GRA1 dedicated servers.
<?php
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;
// Api credentials can be retrieved from the urls specified in the "Supported endpoints" section below.
$ovh = new Api($applicationKey,
$applicationSecret,
$endpoint,
$consumerKey);
// Load the list of dedicated servers
$servers = $ovh->get('/dedicated/server/');
foreach ($servers as $server) {
// Load the server details
$details = $ovh->get('/dedicated/server/'.$server);
// Filter servers only inside GRA1
if ($details['datacenter'] == 'gra1') {
// Activate burst on server
$content = ['status' => 'active'];
$ovh->put('/dedicated/server/'.$server.'/burst', $content);
echo 'Burst enabled on '.$server;
}
}Do you want to use OVHcloud APIs? Maybe the script you want is already written in the example part of this repository!
php-ovh supports two forms of authentication:
- OAuth2, using scopped service accounts, and compatible with OVHcloud IAM
- application key & application secret & consumer key (covered in the next chapter)
For OAuth2, first, you need to generate a pair of valid client_id and client_secret: you can proceed by
following this documentation.
Once you have retrieved your client_id and client_secret, you can instantiate an API client using:
use \Ovh\Api;
$ovh = Api::withOauth2($clientId, $clientSecret, $endpoint);Supported endpoints are only ovh-eu, ovh-ca and ovh-us.
To use the OVHcloud APIs you need three credentials:
- An application key
- An application secret
- A consumer key
The application key and secret are not granting access to a specific account and are unique to identify your application. The consumer key is used to grant access to a specific OVHcloud account to a specified application.
They can be created separately if your application is intended to be used by multiple accounts (your app will need to implement an authorization flow). In the authorization flow, the customer will be prompted to allow access to his account to your application, then he will be redirected to your application.
They can also be created together if your application is intended to use only your own OVHcloud account.
$endpoint = 'ovh-eu';- Documentation: https://eu.api.ovh.com/
- Console: https://eu.api.ovh.com/console
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://eu.api.ovh.com/createApp/
- Create account credentials (all keys at once for your own account only): https://eu.api.ovh.com/createToken/
- Community support: api-subscribe@ml.ovh.net
$endpoint = 'ovh-us';- Documentation: https://api.us.ovhcloud.com/
- Console: https://api.us.ovhcloud.com/console
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://api.us.ovhcloud.com/createApp/
- Create account credentials (all keys at once for your own account only): https://api.us.ovhcloud.com/createToken/
$endpoint = 'ovh-ca';- Documentation: https://ca.api.ovh.com/
- Console: https://ca.api.ovh.com/console
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://ca.api.ovh.com/createApp/
- Create account credentials (all keys at once for your own account only): https://ca.api.ovh.com/createToken/
- Community support: api-subscribe@ml.ovh.net
$endpoint = 'soyoustart-eu';- Documentation: https://eu.api.soyoustart.com/
- Console: https://eu.api.soyoustart.com/console/
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://eu.api.soyoustart.com/createApp/
- Create account credentials (all keys at once for your own account only): https://eu.api.soyoustart.com/createToken/
- Community support: api-subscribe@ml.ovh.net
$endpoint = 'soyoustart-ca';- Documentation: https://ca.api.soyoustart.com/
- Console: https://ca.api.soyoustart.com/console/
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://ca.api.soyoustart.com/createApp/
- Create account credentials (all keys at once for your own account only): https://ca.api.soyoustart.com/createToken/
- Community support: api-subscribe@ml.ovh.net
$endpoint = 'kimsufi-eu';- Documentation: https://eu.api.kimsufi.com/
- Console: https://eu.api.kimsufi.com/console/
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://eu.api.kimsufi.com/createApp/
- Create account credentials (all keys at once for your own account only): https://eu.api.kimsufi.com/createToken/
- Community support: api-subscribe@ml.ovh.net
$endpoint = 'kimsufi-ca';- Documentation: https://ca.api.kimsufi.com/
- Console: https://ca.api.kimsufi.com/console/
- Create application credentials (generate only application credentials, your app will need to implement an authorization flow): https://ca.api.kimsufi.com/createApp/
- Create account credentials (all keys at once for your own account only): https://ca.api.kimsufi.com/createToken/
- Community support: api-subscribe@ml.ovh.net
Documentation is based on phpdocumentor and inclued in the project. To generate documentation, it's possible to use directly:
composer phpdoc
Documentation is available in docs/ directory.
Code check is based on PHP CodeSniffer and inclued in the project. To check code, it's possible to use directly:
composer phpcs
Code linting is based on PHP Code Beautifier and Fixer and inclued in the project. To lint code, it's possible to use directly:
composer phpcbf
Tests are based on phpunit and inclued in the project. To run functionals tests, you need to provide valid API credentials, that you can provide them via environment:
APP_KEY=xxx APP_SECRET=xxx CONSUMER=xxx ENDPOINT=xxx composer phpunit
Please see CONTRIBUTING for details.
All Contributors from this repo
(Modified) BSD license. Please see LICENSE for more information.