├── .travis.yml ├── README.md ├── composer.json ├── phpunit.xml ├── src ├── RecoverableWhoisApiException.php ├── WhoisApi.php └── WhoisApiException.php └── tests ├── WhoisApiIntegrationTest.php └── WhoisApiTest.php /.travis.yml: -------------------------------------------------------------------------------- 1 | language: php 2 | 3 | sudo: false 4 | 5 | cache: 6 | directories: 7 | - $HOME/.composer/cache 8 | 9 | env: 10 | global: 11 | - secure: "jOF/8DrVmhr85p9Cxu2eg+ByYHGHYPdxIthaMbCpoyNpxtdHbjKMeoqSyaNKffqXQ24e6L9lQ6xSZZ45iaQoqg64/04/dnF2JNj6A/czP3iq/apNNOHVCzzqCa1KOkrOv2e01YSxCWzR+Qw22PBxOvj6/0aZeZ94lY8VydJv59IbIG+Y3/HonYQusoljD/90uKZmUMjuAlvybvKFUg58oyF04nGflm9+mQRWpTp8BPtgZXteSZX1u21a/Kg0uykBpE8EZzaBwlMVvS4ZOC+XOP/R0HP5TAJBIPj9vUEuRBMCnihCLQ+zPLeqBaxjBz7gKZPy5hM/qKhiMzluuzEnx6o312SBbqiGokdFGThFFF1YFgGEHSKq467/jpuYKMXVMdy2vh5g30JiGIONNx9xfok3byZGpgAxM9FoDUVM/kL/CkYK8Tq1+bIgimF3ENcsEdWr54QJpuwhj7+jexZUy3PlGhqvPcHV1mTfzNyAxBfAuj+kgHQ4NfZNjLlUCNN7RmMYy+5nuN+Grmb6lMj5hP08bdGdhTo46NBIwdKF/E9LpS5DtlZkQS4N10KtRJWT+fTowaOfm4NZpOx/XVoGIXNQK7/OJuay98m9iWT2biI3d3QJnkZaxHzNu4Byj59ax3reHtLNnwRXOxly6wt+zKZpA3RkEOR4OzPUeaF3wpg=" 12 | 13 | php: 14 | - 7.1 15 | - 7.0 16 | - 5.6 17 | - hhvm 18 | 19 | install: 20 | - composer require squizlabs/php_codesniffer 21 | - composer require phpmd/phpmd 22 | 23 | script: 24 | - vendor/bin/phpunit 25 | - vendor/bin/phpcs --standard=PSR2 src/ tests/ 26 | - vendor/bin/phpmd src/ text cleancode,codesize,controversial,design,naming,unusedcode 27 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Domain API 2 | 3 | This is a client library for the [Whois API service](http://whois-api.domaininformation.de/). 4 | With this API you can 5 | 6 | - Check if a domain name is available 7 | - Get its whois data or query an arbitrary whois server 8 | - Don't worry about rate limits on the respective whois server 9 | 10 | The service supports all domains of the 11 | [Whois Server list](https://github.com/whois-server-list/whois-server-list), 12 | which is more than 500 top level domains. 13 | 14 | # Installation 15 | 16 | Use [Composer](https://getcomposer.org/): 17 | 18 | ```sh 19 | composer require whois-server-list/whois-api 20 | ``` 21 | 22 | # Usage 23 | 24 | You'll need an api key to use this library. Get one from 25 | the [Whois API](http://whois-api.domaininformation.de/). 26 | 27 | ```php 28 | $whoisApi = new whoisServerList\WhoisApi("apiKey"); 29 | ``` 30 | 31 | - [`WhoisApi::isAvailable()`](http://whois-server-list.github.io/whois-api-php/api/class-whoisServerList.WhoisApi.html#_isAvailable) 32 | checks if a domain name is available. 33 | - [`WhoisApi::areAvailable()`](http://whois-server-list.github.io/whois-api-php/api/class-whoisServerList.WhoisApi.html#_areAvailable) 34 | checks multiple domain names if they are available. 35 | - [`WhoisApi::whois()`](http://whois-server-list.github.io/whois-api-php/api/class-whoisServerList.WhoisApi.html#_whois) 36 | returns the whois data of a domain. 37 | - [`WhoisApi::query()`](http://whois-server-list.github.io/whois-api-php/api/class-whoisServerList.WhoisApi.html#_query) 38 | queries an arbitrary whois server. 39 | - [`WhoisApi::domains()`](http://whois-server-list.github.io/whois-api-php/api/class-whoisServerList.WhoisApi.html#_domains) 40 | Lists all top and second level domains which can be used by the Whois API. 41 | 42 | ## Example 43 | 44 | ```php 45 | $whoisApi = new whoisServerList\WhoisApi("apiKey"); 46 | echo $whoisApi->isAvailable("example.net") ? "available" : "registered"; 47 | ``` 48 | 49 | # License and authors 50 | 51 | This project is free and under the WTFPL. 52 | Responsable for this project is Markus Malkusch markus@malkusch.de. 53 | 54 | [![Build Status](https://travis-ci.org/whois-server-list/whois-api-php.svg?branch=master)](https://travis-ci.org/whois-server-list/whois-api-php) 55 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "whois-server-list/whois-api", 3 | "description": "Client library for the Whois API. You can check the availability of internet domain names or perform whois queries.", 4 | "keywords": ["whois", "domain"], 5 | "require": { 6 | "guzzlehttp/guzzle": "^6.1" 7 | }, 8 | "homepage": "http://whois-api.domaininformation.de/", 9 | "license": "WTFPL", 10 | "authors": [ 11 | { 12 | "name": "Markus Malkusch", 13 | "email": "markus@malkusch.de", 14 | "homepage": "http://markus.malkusch.de", 15 | "role": "Developer" 16 | } 17 | ], 18 | "require-dev": { 19 | "phpunit/phpunit": "^5" 20 | }, 21 | "autoload": { 22 | "psr-4": { 23 | "whoisServerList\\": "src/" 24 | } 25 | } 26 | } 27 | -------------------------------------------------------------------------------- /phpunit.xml: -------------------------------------------------------------------------------- 1 | 5 | 6 | 7 | tests 8 | 9 | 10 | -------------------------------------------------------------------------------- /src/RecoverableWhoisApiException.php: -------------------------------------------------------------------------------- 1 | 12 | * @link http://whois-api.domaininformation.de/ Whois API 13 | * @license http://www.wtfpl.net/txt/copying/ WTFPL 14 | */ 15 | class RecoverableWhoisApiException extends WhoisApiException 16 | { 17 | 18 | } 19 | -------------------------------------------------------------------------------- /src/WhoisApi.php: -------------------------------------------------------------------------------- 1 | 23 | * use whoisServerList\WhoisApi; 24 | * 25 | * $whoisApi = new WhoisApi("apiKey"); 26 | * echo $whoisApi->isAvailable("example.net") ? "available" : "registered"; 27 | * 28 | * 29 | * @author Markus Malkusch 30 | * @link http://whois-api.domaininformation.de/ Whois API 31 | * @license http://www.wtfpl.net/txt/copying/ WTFPL 32 | */ 33 | class WhoisApi 34 | { 35 | 36 | /** 37 | * @var ClientInterface HTTP client 38 | */ 39 | private $client; 40 | 41 | /** 42 | * Builds a Domain API. 43 | * 44 | * Register at http://whois-api.domaininformation.de/ to get an API key. 45 | * 46 | * @param string $apiKey API key 47 | * @param string $endpoint optional endpoint, default is "https://whois-v0.p.mashape.com/". 48 | */ 49 | public function __construct($apiKey, $endpoint = "https://whois-v0.p.mashape.com/") 50 | { 51 | if (empty($apiKey)) { 52 | throw new \InvalidArgumentException("API key is empty."); 53 | } 54 | if (empty($endpoint)) { 55 | throw new \InvalidArgumentException("Endpoint is empty."); 56 | } 57 | 58 | $this->client = new Client( 59 | [ 60 | "base_uri" => $endpoint, 61 | "headers" => ["X-Mashape-Key" => $apiKey], 62 | "http_errors" => false, 63 | ] 64 | ); 65 | } 66 | 67 | /** 68 | * Checks if a domain is available. 69 | * 70 | * If a domain is available (i.e. not registered) this method 71 | * will return true. 72 | * 73 | * @param string $domain domain name, e.g. "example.net" 74 | * @return bool true if the domain is available, false otherwise. 75 | * 76 | * @throws RecoverableWhoisApiException API failed, but you can try again. 77 | * This can happen if the upstream whois server did not respond in time. 78 | * @throws WhoisApiException API failed 79 | */ 80 | public function isAvailable($domain) 81 | { 82 | if (empty($domain)) { 83 | throw new \InvalidArgumentException("The domain is empty."); 84 | } 85 | 86 | $body = $this->sendRequest("check", ["domain" => $domain]); 87 | $result = json_decode($body); 88 | return $result->available; 89 | } 90 | 91 | /** 92 | * Checks multiple domains if they are available. 93 | * 94 | * areAvailable(["example.net", "example.org", "example.com"]) 95 | * could return this map: 96 | * 97 | * [ 98 | * "example.net" => true, // example.net is available 99 | * "example.org" => false, // example.org is registered 100 | * "example.com" => null // example.com failed 101 | * ] 102 | * 103 | * 104 | * @param string[] $domains domain names, e.g. ["example.net", "example.org"] 105 | * @return boolean[] map with the result for each domain. True means 106 | * the domain is available, false not. NULL however means that the 107 | * query failed for that domain. 108 | */ 109 | public function areAvailable(array $domains) 110 | { 111 | $promises = []; 112 | foreach ($domains as $domain) { 113 | $promises[$domain] = $this->client->requestAsync( 114 | "GET", 115 | "check", 116 | ["query" => ["domain" => $domain]] 117 | ); 118 | } 119 | $results = Promise\unwrap($promises); 120 | 121 | return array_map( 122 | function (ResponseInterface $response) { 123 | if ($response->getStatusCode() != 200) { 124 | return null; 125 | } 126 | $result = json_decode($response->getBody()); 127 | return $result->available; 128 | }, 129 | $results 130 | ); 131 | } 132 | 133 | /** 134 | * Returns the whois data for a domain. 135 | * 136 | * @param string $domain domain name, e.g. "example.net" 137 | * @return string response of the respective whois server 138 | * 139 | * @throws RecoverableWhoisApiException API failed, but you can try again. 140 | * This can happen if the upstream whois server did not respond in time. 141 | * @throws WhoisApiException API failed 142 | */ 143 | public function whois($domain) 144 | { 145 | if (empty($domain)) { 146 | throw new \InvalidArgumentException("The domain is empty."); 147 | } 148 | 149 | $body = $this->sendRequest("check", ["domain" => $domain]); 150 | $result = json_decode($body); 151 | return $result->whoisResponse; 152 | } 153 | 154 | /** 155 | * Queries a whois server. 156 | * 157 | * @param string $host hostname of the whois server, e.g. "whois.verisign-grs.com" 158 | * @param string $query query, e.g. "example.net" 159 | * 160 | * @return string response from the whois server 161 | * 162 | * @throws RecoverableWhoisApiException API failed, but you can try again. 163 | * This can happen if the upstream whois server did not respond in time. 164 | * @throws WhoisApiException API failed 165 | */ 166 | public function query($host, $query) 167 | { 168 | if (empty($host)) { 169 | throw new \InvalidArgumentException("The host is empty."); 170 | } 171 | if (empty($query)) { 172 | throw new \InvalidArgumentException("The query is empty."); 173 | } 174 | 175 | return $this->sendRequest("whois", ["host" => $host, "query" => $query]); 176 | } 177 | 178 | /** 179 | * Returns a list of all top and second level domains, which are 180 | * known to the Whois API. 181 | * 182 | * @return string[] all available top and second level domains. 183 | */ 184 | public function domains() 185 | { 186 | $body = $this->sendRequest("domains"); 187 | $result = json_decode($body); 188 | return $result; 189 | } 190 | 191 | /** 192 | * Sends a request and return the reponse body. 193 | * 194 | * @param string $path request path 195 | * @param string[] $parameters request paramters 196 | * 197 | * @return string response body 198 | * 199 | * @throws RecoverableWhoisApiException API failed, but you can try again. 200 | * @throws WhoisApiException API failed 201 | */ 202 | private function sendRequest($path, array $parameters = []) 203 | { 204 | try { 205 | $response = $this->client->request("GET", $path, ["query" => $parameters]); 206 | } catch (\Exception $e) { 207 | throw new WhoisApiException("Transport failed.", 0, $e); 208 | } 209 | 210 | switch ($response->getStatusCode()) { 211 | case 200: 212 | return $response->getBody()->__toString(); 213 | 214 | case 502: 215 | case 504: 216 | throw new RecoverableWhoisApiException( 217 | "Try again: {$response->getBody()}", 218 | $response->getStatusCode() 219 | ); 220 | 221 | default: 222 | throw new WhoisApiException("API failed: {$response->getBody()}", $response->getStatusCode()); 223 | } 224 | } 225 | } 226 | -------------------------------------------------------------------------------- /src/WhoisApiException.php: -------------------------------------------------------------------------------- 1 | 9 | * @link http://whois-api.domaininformation.de/ Whois API 10 | * @license http://www.wtfpl.net/txt/copying/ WTFPL 11 | */ 12 | class WhoisApiException extends \Exception 13 | { 14 | 15 | } 16 | -------------------------------------------------------------------------------- /tests/WhoisApiIntegrationTest.php: -------------------------------------------------------------------------------- 1 | 11 | * @link http://whois-api.domaininformation.de/ 12 | * @license http://www.wtfpl.net/txt/copying/ WTFPL 13 | */ 14 | class WhoisApiIntegrationTest extends \PHPUnit_Framework_TestCase 15 | { 16 | 17 | /** 18 | * @var WhoisApi the SUT 19 | */ 20 | private $api; 21 | 22 | protected function setUp() 23 | { 24 | parent::setUp(); 25 | 26 | $key = getenv("API_KEY"); 27 | if (empty($key)) { 28 | $this->markTestIncomplete("Please provide the API key with the environment variable API_KEY."); 29 | return; 30 | } 31 | 32 | $this->api = new WhoisApi($key); 33 | } 34 | 35 | /** 36 | * @test 37 | */ 38 | public function isAvailableShouldReturnTrue() 39 | { 40 | $this->assertFalse($this->api->isAvailable("example.net")); 41 | } 42 | 43 | /** 44 | * @test 45 | */ 46 | public function isAvailableShouldReturnFalse() 47 | { 48 | $this->assertTrue($this->api->isAvailable("dsfsdfsdfsdfdsfsdfdsfsdfdsfdssdfse.net")); 49 | } 50 | 51 | /** 52 | * @test 53 | */ 54 | public function isAvailableShouldFailForUnknownTLD() 55 | { 56 | $this->expectException(WhoisApiException::class); 57 | $this->api->isAvailable("invalid"); 58 | } 59 | 60 | /** 61 | * @test 62 | */ 63 | public function whoisShouldReturnString() 64 | { 65 | $response = $this->api->whois("example.net"); 66 | $this->assertNotEmpty($response); 67 | } 68 | 69 | /** 70 | * @test 71 | */ 72 | public function whoisShouldFailForUnknownTLD() 73 | { 74 | $this->expectException(WhoisApiException::class); 75 | $this->api->whois("invalid"); 76 | } 77 | 78 | /** 79 | * @test 80 | */ 81 | public function queryShouldReturnString() 82 | { 83 | $response = $this->api->query("whois.nic.de", "example.net"); 84 | $this->assertNotEmpty($response); 85 | } 86 | 87 | /** 88 | * @test 89 | */ 90 | public function queryShouldFailForWrongHost() 91 | { 92 | $this->expectException(WhoisApiException::class); 93 | $this->api->query("invalid", "example.net"); 94 | } 95 | 96 | /** 97 | * @test 98 | */ 99 | public function domainsShouldIncludKnownTLDs() 100 | { 101 | $domains = $this->api->domains(); 102 | $this->assertTrue(in_array("de", $domains)); 103 | $this->assertTrue(in_array("com", $domains)); 104 | $this->assertTrue(in_array("net", $domains)); 105 | } 106 | 107 | /** 108 | * @test 109 | */ 110 | public function areAvailableShouldReturnMap() 111 | { 112 | $result = $this->api->areAvailable( 113 | ["example.net", "dsfsdfsdfsdfdsfsdfdsfsdfdsfdssdfse.net", "invalid", "example.com"] 114 | ); 115 | 116 | $this->assertEquals( 117 | [ 118 | "example.net" => false, 119 | "dsfsdfsdfsdfdsfsdfdsfsdfdsfdssdfse.net" => true, 120 | "invalid" => null, 121 | "example.com" => false 122 | ], 123 | $result 124 | ); 125 | } 126 | } 127 | -------------------------------------------------------------------------------- /tests/WhoisApiTest.php: -------------------------------------------------------------------------------- 1 | 9 | * @link http://whois-api.domaininformation.de/ 10 | * @license http://www.wtfpl.net/txt/copying/ WTFPL 11 | */ 12 | class WhoisApiTest extends \PHPUnit_Framework_TestCase 13 | { 14 | 15 | /** 16 | * @dataProvider provideBuildingShouldFailWithInvalidParameters 17 | * @test 18 | */ 19 | public function buildingShouldFailWithInvalidParameters($apiKey, $endpoint) 20 | { 21 | $this->expectException(\InvalidArgumentException::class); 22 | new WhoisApi($apiKey, $endpoint); 23 | } 24 | 25 | public function provideBuildingShouldFailWithInvalidParameters() 26 | { 27 | return [ 28 | [null, "http://example.org"], 29 | ["", "http://example.org"], 30 | ["valid", null], 31 | ["valid", ""], 32 | ]; 33 | } 34 | 35 | /** 36 | * @dataProvider provideInvalidDomain 37 | * @test 38 | */ 39 | public function isAvailableShoudFailWithInvalidParameters($domain) 40 | { 41 | $this->expectException(\InvalidArgumentException::class); 42 | $api = new WhoisApi("key"); 43 | $api->isAvailable($domain); 44 | } 45 | 46 | /** 47 | * @dataProvider provideInvalidDomain 48 | * @test 49 | */ 50 | public function whoisShoudFailWithInvalidParameters($domain) 51 | { 52 | $this->expectException(\InvalidArgumentException::class); 53 | $api = new WhoisApi("key"); 54 | $api->whois($domain); 55 | } 56 | 57 | public function provideInvalidDomain() 58 | { 59 | return [ 60 | [null], 61 | [""], 62 | ]; 63 | } 64 | 65 | /** 66 | * @dataProvider provideQueryShoudFailWithInvalidParameters 67 | * @test 68 | */ 69 | public function queryShoudFailWithInvalidParameters($host, $query) 70 | { 71 | $this->expectException(\InvalidArgumentException::class); 72 | $api = new WhoisApi("key"); 73 | $api->query($host, $query); 74 | } 75 | 76 | public function provideQueryShoudFailWithInvalidParameters() 77 | { 78 | return [ 79 | [null, "example.net"], 80 | ["", "example.net"], 81 | ["whois.example.net", null], 82 | ["whois.example.net", ""], 83 | ]; 84 | } 85 | } 86 | --------------------------------------------------------------------------------