OVHcloud APIs lightweight PHP wrapper
, (*1)
, (*2)
This PHP package is a lightweight wrapper for OVHcloud APIs., (*3)
The easiest way to use OVHcloud APIs in your PHP applications., (*4)
Compatible with PHP 7.4, 8.0, 8.1, 8.2., (*5)
Installation
Install this wrapper and integrate it inside your PHP application with Composer:, (*6)
composer require ovh/ovh
Basic usage
<?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'];
Advanced usage
Handle exceptions
Under the hood, php-ovh uses Guzzle by default to issue API requests., (*7)
If everything goes well, it will return the response directly as shown in the examples above., (*8)
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., (*9)
You can get the error details with a code like:, (*10)
try {
echo "Welcome " . $ovh->get('/me')['firstname'];
} catch (GuzzleHttp\Exception\ClientException $e) {
$response = $e->getResponse();
$responseBodyAsString = $response->getBody()->getContents();
echo $responseBodyAsString;
}
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, (*11)
<?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'];
Authorization flow
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., (*12)
See "OVHcloud API authentication" section below for more information about the authorization flow., (*13)
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.
Code sample: Enable network burst on GRA1 dedicated servers
Here is a more complex example of how to use the wrapper to enable network burst on GRA1 dedicated servers., (*14)
<?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;
}
}
More code samples
Do you want to use OVHcloud APIs? Maybe the script you want is already written in the example part of this repository!, (*15)
OAuth2 authentification
php-ovh supports two forms of authentication:, (*16)
- 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., (*17)
Once you have retrieved your client_id and client_secret, you can instantiate an API client using:, (*18)
use \Ovh\Api;
$ovh = Api::withOauth2($clientId, $clientSecret, $endpoint);
Supported endpoints are only ovh-eu, ovh-ca and ovh-us., (*19)
Custom OVHcloud API authentication
To use the OVHcloud APIs you need three credentials:, (*20)
- 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., (*21)
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., (*22)
They can also be created together if your application is intended to use only your own OVHcloud account., (*23)
Supported endpoints
OVHcloud Europe
OVHcloud US
OVHcloud North America / Canada
So you Start Europe
So you Start North America
Kimsufi Europe
Kimsufi North America
Building documentation
Documentation is based on phpdocumentor and inclued in the project.
To generate documentation, it's possible to use directly:, (*24)
composer phpdoc
Documentation is available in docs/ directory., (*25)
Code check / Linting
Code check is based on PHP CodeSniffer and inclued in the project.
To check code, it's possible to use directly:, (*26)
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:, (*27)
composer phpcbf
Testing
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:, (*28)
APP_KEY=xxx APP_SECRET=xxx CONSUMER=xxx ENDPOINT=xxx composer phpunit
Contributing
Please see CONTRIBUTING for details., (*29)
Credits
All Contributors from this repo, (*30)
License
(Modified) BSD license. Please see LICENSE for more information., (*31)
Wallogit.com
