Add attached domain example

Signed-off-by: Vincent Casse <vincent.casse@corp.ovh.com>

README.md

@@ -48,6 +48,11 @@ Then, you can install OVH APIs wrapper and dependencies with:
 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](examples/README.md) of this repository!
+
 How to login as a user?
 -----------------------
 

examples/README.md

@@ -0,0 +1,17 @@
+PHP wrapper examples
+--------------------
+
+In this part, you can find real use cases for the OVH php wrapper
+
+## Domains
+
+Following examples are related to [domains offers](https://www.ovh.ie/domains/) proposed by OVH.
+
+ - [How to create HTTP redirection using php wrapper?](create-Redirection/api_create_redirection.md)
+
+## Web hosting
+
+Following examples are related to [web hosting offers](https://www.ovh.ie/web-hosting/) proposed by OVH.
+
+ - [How to get web hosting capabilities using php wrapper?](hosting-getCapabilities/api_get_hosting_capacities.md)
+ - [How to attach domains to a web hosting offer using the php wrapper?](hosting-attachedDomain/api_attach_domain_to_web_hosting.md)

examples/hosting-attachedDomain/api_attach_domain_to_web_hosting.md

@@ -0,0 +1,89 @@
+How to attach domains to a web hosting offer using the php wrapper?
+-------------------------------------------------------------------
+
+This documentation will help you to create, edit and delete domains attached to your webhosting offer. This documentation is the equivalent of [MultiDomain SoAPI](http://www.ovh.com/soapi/en/?method=multiDomainAdd) and [SubDomain SoAPI](http://www.ovh.com/soapi/en/?method=subDomainAdd)
+
+## Compatibility note
+
+MultiDomains and SubDomains features are merged into one feature called **Attached Domains**. You can manage both with this new feature in OVH APIs.
+
+## Requirements
+
+- Having PHP 5.2+
+- Having a domain at OVH
+- Having an hosting account
+
+## Download PHP wrapper
+
+- Download the latest release **with dependencies** on github: https://github.com/ovh/php-ovh/releases
+
+```bash
+# When this article was written, latest version was 2.0.0
+wget https://github.com/ovh/php-ovh/releases/download/v2.0.0/php-ovh-2.0.0-with-dependencies.tar.gz
+```
+
+- Extract it
+
+```bash
+tar xzvf php-ovh-2.0.0-with-dependencies.tar.gz 
+```
+
+## Create a new token
+You can create a new token using [this url](https://api.ovh.com/createToken/?GET=/hosting/web/my_domain/attachedDomain&POST=/hosting/web/my_domain/attachedDomain&GET=/hosting/web/my_domain/attachedDomain/*&PUT=/hosting/web/my_domain/attachedDomain/*&DELETE=/hosting/web/my_domain/attachedDomain/*). Keep the application key, the application secret and the consumer key to complete the script.
+
+Be warned, this token is only valid for this script and for hosting called **my_domain**. Please replace **my_domain** by your web hosting reference!
+If you need a more generic token, make sure to set the rights field to your needs
+
+## Attach a domain to your web hosting
+
+When you call the API to attach a domain to your web hosting, the api call returns a **task**. The task is the current state of an operation to attach this domain to your hosting. The [example script](createAttachedDomain.php) explains how to attach a domain an wait the end of the operation.
+
+If this script works, you should see someting like:
+```bash
+Task #42 is created
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'doing'
+Domain attached to the web hosting
+```
+
+## List all your attached domains
+
+The [example script](listAttachedDomain.php) explains how to show all your domains attached to a web hosting
+For instance, using the example values in this script, the answer could be look like:
+
+```bash
+Array
+(
+    [domain] => myotherdomaintoattach.ovh
+    [cdn] => none
+    [ipLocation] => 
+    [ownLog] => myotherdomaintoattach.ovh
+    [firewall] => none
+    [path] => otherFolder
+)
+```
+
+## Detach a domain from your web hosting
+
+The [example script](deleteAttachedDomain.php) explains how to detach a domain to your web hosting.
+
+If this script works, you should see someting like:
+```bash
+Task #42 is created
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'todo'
+Status of task #42 is 'doing'
+Domain detached from the web hosting
+```
+
+## What's next?
+
+You can discover all hosting possibilities by using API console to show all available endpoints: [https://api.ovh.com/console](https://api.ovh.com/console)
+

examples/hosting-attachedDomain/createAttachedDomain.php

@@ -0,0 +1,82 @@
+<?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';
+
+// Informations about your web hosting and the attached domain (compulsory)
+$domain = 'mydomain.ovh'; // Web hosting id (often domain ordered with it)
+$domainToAttach = 'myotherdomaintoattach.ovh';
+$path = 'otherFolder'; // Folder where website files are stored
+
+// Informations about the attached domain (optional)
+$cdn = 'none'; // Enable CDN on the attached domain. Can be NULL, 'none' or 'active'
+$firewall = 'none'; // Enable HTTP firewall (block dangerous pattern requests with Apache mod_security). Can be NULL, 'active' or 'none'
+$ownLog = 'myotherdomaintoattach.ovh'; // Separate logs by domain. Can be 'null' or domain offer you have at OVH
+
+$http_client = new Client([
+	'timeout'         => 30,
+	'connect_timeout' => 5,
+]);
+
+// Create a new attached domain
+$conn = new Api(    $applicationKey,
+                    $applicationSecret,
+                    $endpoint,
+                    $consumer_key,
+		    $http_client);
+
+try {
+
+	// This call will create a "task". The task is the status of the attached domain creation.
+	// You can follow the task on /hosting/web/{serviceName}/tasks/{id}
+	$task = $conn->post('/hosting/web/' . $domain . '/attachedDomain', array(
+		'domain'	=> $domainToAttach,
+		'path'		=> $path,
+		'cdn'		=> $cdn,
+		'firewall'	=> $firewall,
+		'ownLog'	=> $ownLog,
+	));
+
+	echo "Task #" . $task['id'] . " is created" . PHP_EOL;
+
+	// we check every 5 seconds if the task is done
+	// When the task disappears, the task is done
+	while ( 1 ) {
+		try {
+			$wait = $conn->get('/hosting/web/' . $domain . '/tasks/' . $task['id']);
+			
+			if ( strcmp( $wait['status'], 'error' ) === 0 ) {
+				// The task is in error state. Please check your parameters, retry or contact support.
+				echo "An error has occured during the task" . PHP_EOL;
+				break;
+			} elseif ( strcmp( $wait['status'], 'cancelled' ) === 0 ) {
+				// The task is in cancelled state. Please check your parameters, retry or contact support.
+				echo "Task has been cancelled during the task" . PHP_EOL;
+				break;
+			}
+
+			echo "Status of task #". $wait['id'] . " is '". $wait['status'] ."'" . PHP_EOL;
+		} catch ( \GuzzleHttp\Exception\ClientException $ex) {
+			$response = $ex->getResponse();
+			if ( $response && $response->getStatusCode() === 404 ) {
+				echo "Domain attached to the web hosting" . PHP_EOL;
+				break;
+			}
+			throw $ex;
+		}
+
+		sleep(5);
+	}
+
+} catch ( Exception $ex ) {
+	print_r( $ex->getMessage() );
+}
+?>

examples/hosting-attachedDomain/deleteAttachedDomain.php

@@ -0,0 +1,70 @@
+<?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';
+
+// Informations about your web hosting and the attached domain (compulsory)
+$domain = 'mydomain.ovh'; // Web hosting id (often domain order with it)
+$domainToAttach = 'myotherdomaintoattach.ovh';
+
+$http_client = new Client([
+	'timeout'         => 30,
+	'connect_timeout' => 5,
+]);
+
+// Create a new attached domain
+$conn = new Api(    $applicationKey,
+                    $applicationSecret,
+                    $endpoint,
+                    $consumer_key,
+		    $http_client);
+
+try {
+
+	// This call will create a "task". The task is the status of the attached domain deletion.
+	// You can follow the task on /hosting/web/{serviceName}/tasks/{id}
+	$task = $conn->delete('/hosting/web/' . $domain . '/attachedDomain/' . $domainToDetach);
+
+	echo "Task #" . $task['id'] . " is created" . PHP_EOL;
+
+	// we check every 5 seconds if task is done
+	// When the task disappears, the task is done
+	while ( 1 ) {
+		try {
+			$wait = $conn->get('/hosting/web/' . $domain . '/tasks/' . $task['id']);
+			
+			if ( strcmp( $wait['status'], 'error' ) === 0 ) {
+				// The task is in error state. Please check your parameters, retry or contact support.
+				echo "An error has occured during the task" . PHP_EOL;
+				break;
+			} elseif ( strcmp( $wait['status'], 'cancelled' ) === 0 ) {
+				// The task is in cancelled state. Please check your parameters, retry or contact support.
+				echo "Task has been cancelled during the task" . PHP_EOL;
+				break;
+			}
+
+			echo "Status of task #". $wait['id'] . " is '". $wait['status'] ."'" . PHP_EOL;
+		} catch ( \GuzzleHttp\Exception\ClientException $ex) {
+			$response = $ex->getResponse();
+			if ( $response && $response->getStatusCode() === 404 ) {
+				echo "Domain detached from the web hosting" . PHP_EOL;
+				break;
+			}
+			throw $ex;
+		}
+
+		sleep(5);
+	}
+
+} catch ( Exception $ex ) {
+	print_r( $ex->getMessage() );
+}
+?>

examples/hosting-attachedDomain/listAttachedDomains.php

@@ -0,0 +1,41 @@
+<?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';
+
+// Information about your web hosting(compulsory)
+$domain = 'mydomain.ovh'; // Web hosting id (often domain order with it)
+
+$http_client = new Client([
+	'timeout'         => 30,
+	'connect_timeout' => 5,
+]);
+
+// Create a new attached domain
+$conn = new Api(    $applicationKey,
+                    $applicationSecret,
+                    $endpoint,
+                    $consumer_key,
+		    $http_client);
+
+try {
+
+	$attachedDomainsIds = $conn->get('/hosting/web/' . $domain . '/attachedDomain');
+
+	foreach( $attachedDomainsIds as $attachedDomainsId) {
+		$attachedDomain = $conn->get('/hosting/web/' . $domain . '/attachedDomain/' . $attachedDomainsId );
+		print_r( $attachedDomain );
+	}
+
+} catch ( Exception $ex ) {
+	print_r( $ex->getMessage() );
+}
+?>