search

ovh / php-ovh

Lightweight PHP wrapper for OVH APIs. That's the easiest way to use OVH.com APIs in your PHP applications.
Other
286 stars 107 forks source link
api-wrapper

readme

OVHcloud APIs lightweight PHP wrapper

PHP Wrapper for OVHcloud APIs

Source Code Build Status Codecov Code Coverage Total Downloads

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.

Installation

Install this wrapper and integrate it inside your PHP application with Composer:

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.

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;
}

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;

// 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.

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.

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.

<?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!

OAuth2 authentification

php-ovh supports two forms of authentication:

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.

Custom OVHcloud API authentication

To use the OVHcloud APIs you need three credentials:

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.

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:

composer phpdoc

Documentation is available in docs/ directory.

Code check / Linting

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

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:

APP_KEY=xxx APP_SECRET=xxx CONSUMER=xxx ENDPOINT=xxx composer phpunit

Contributing

Please see CONTRIBUTING for details.

Credits

All Contributors from this repo

License

(Modified) BSD license. Please see LICENSE for more information.