From 943dfca9f42604e144f6e939e9f626c0b68dfa45 Mon Sep 17 00:00:00 2001 From: Nathan Fiscaletti Date: Thu, 27 Jun 2019 14:40:47 -0500 Subject: [PATCH 1/4] Added requester ip lookup, security option, language option and hostname option --- ReadMe.md | 103 ++++++++++++++--- src/IPStack/GeoLookup.php | 231 ++++++++++++++++++++++++++++++++++---- tests/GeoLookupTest.php | 9 ++ 3 files changed, 309 insertions(+), 34 deletions(-) diff --git a/ReadMe.md b/ReadMe.md index fdc87f9..2da0a77 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -15,22 +15,35 @@ Learn more about IPStack here: [ipstack.net](https://ipstack.com/product) ### Features * Retrieve the Geo Location data for any IP address. -* (Legacy) Link to a custom FreeGeoIP server +* Retrieve the Geo Location data for the system executing this code. +* Retrieve the Geo Location data for a client. +* Retrieve the Geo Location data for a batch of IP addresses. +* Assess the security of an IP address. + +### Legacy Features +* Link to a custom FreeGeoIP server + +--- + +### Basic Usage + +```php +$geo = new GeoLookup('.....'); +$location = $geo->getLocation('github.com'); +print_r($location); +``` ### Example Usage -> Note: See [Location.php](https://github.com/nathan-fiscaletti/ipstackgeo-php/blob/v1.4/src/IPStack/Location.php) for a list of available properties on the Location object. +> Note: See [IPStack: Response Objects](https://ipstack.com/documentation#objects) for a list of available properties in a response object. #### Create the GeoLookup object ```php use IPStack\PHP\GeoLookup; -$geoLookup = new GeoLookup( - 'acecac3893c90871c3', // API Key - false, // Use HTTPS (IPStack Basic plan and up only, defaults to false) - 10 // Timeout in seconds (defaults to 10 seconds) -); +// Create the GeoLookup object using your API key. +$geoLookup = new GeoLookup('acecac3893c90871c3'); ``` #### Lookup a location for an IP Address @@ -60,18 +73,80 @@ try { } ``` -#### Lookup IPs locations in bulk +#### Look up a Clients location -You can also look up the location for multiple IP addresses at once. - -> Note: This requires the PROFESSIONAL teir API key or higher and is limitted to 50 IPs at a time. +```php +$location = $geoLookup->getClientLocation(); +print_r($location); +``` +#### Look up own location ```php -$lookup = ['google.com', 'github.com', '1.1.1.1']; -$locations = $geoLookup->getLocations(...$lookup); -print_r($locations); +$location = $geoLookup->getOwnLocation(); +print_r($location); ``` +#### Other Features + +There are also a few other useful features built into this library and the IPStack API. + +1. Bulk Location Lookup + + The ipstack API also offers the ability to request data for multiple IPv4 or IPv6 addresses at the same time. This requires the PROFESSIONAL teir API key or higher and is limitted to 50 IPs at a time. + > See: [https://ipstack.com/documentation#bulk](https://ipstack.com/documentation#bulk) + + ```php + $lookup = ['google.com', 'github.com', '1.1.1.1']; + $locations = $geoLookup->getLocations(...$lookup); + print_r($locations); + ``` + +2. Requesting the hostname for an IP address. + + By default, the ipstack API does not return information about the hostname the given IP address resolves to. In order to include the hostname use the following. + > See: [https://ipstack.com/documentation#hostname](https://ipstack.com/documentation#hostname) + + ```php + $location = $geoLookup->setFindHostname(true)->getLocation('1.1.1.1'); + echo $location['hostname']; + ``` + + ``` + one.one.one.one + ``` + +3. Assessing Security + + Customers subscribed to the Professional Plus Plan may access the ipstack API's Security Module, which can be used to assess risks and threats originating from certain IP addresses before any harm can be done to a website or web application. + > See: [https://ipstack.com/documentation#security](https://ipstack.com/documentation#security) + + ```php + $location = $geoLookup->assessSecurity(true)->getLocation('github.com'); + ``` + +4. Set the language for a response + + The ipstack API is capable of delivering its result set in different languages. To request data in a language other than English (default) use following with one of the supported language codes. + > See: [https://ipstack.com/documentation#language](https://ipstack.com/documentation#language) + + [Supported Langauges](https://ipstack.com/documentation#language) + + ```php + $location = $geoLookup->setLanguage('en')->getLocation('github.com'); + ``` + +5. Configuring your request + + ```php + /// Use HTTPS + /// This requires IPStack Basic plan or higher. + $location = $geoLookup->useHttps(true)->getLocation('github.com'); + + /// Configure the timeout for requests + $location = $geoLookup->setTimeout(15)->getLocation('github.com'); + ``` + + #### Using the the Legacy [FreeGeoIP Binary](https://github.com/fiorix/freegeoip/releases/) You can still use the legacy FreeGeoIP Binary hosted on a server diff --git a/src/IPStack/GeoLookup.php b/src/IPStack/GeoLookup.php index 768c29b..0722918 100644 --- a/src/IPStack/GeoLookup.php +++ b/src/IPStack/GeoLookup.php @@ -12,48 +12,62 @@ class GeoLookup { /** - * The timeout for the current server. + * The API key used to connect to the IPStack API. * - * @var int + * @var string */ - private $timeout; + private $api_key; /** - * The API key used to connect to the IPStack API. + * The timeout for the current server. * - * @var string + * @var int */ - private $api_key; + private $timeout = 10; /** * If set to true, HTTPS will be used for the connection. * * @var bool */ - private $use_https; + private $use_https = false; + + /** + * Whether or not to attempt reverse hostname lookup when + * looking up location data. + * + * @var bool + */ + private $find_hostname = false; + + /** + * Whether or not to assess the security of an IP address. + * + * @var bool + */ + private $assess_security = false; + + /** + * The language to translate the response into. + * + * @var string + */ + private $language = 'en'; /** * Construct the FreeGeoIp object with server information. * Defaults to freegeoip.net. * - * @param string $api_key - * @param bool $use_https - * @param int $timeout + * @param string $api_key Your IPStack API Key. */ - public function __construct( - string $api_key, - bool $use_https = false, - int $timeout = 10 - ) { - $this->timeout = $timeout; + public function __construct(string $api_key) { $this->api_key = $api_key; - $this->use_https = $use_https; } /** * Retrieve a location for a specific IP address. * - * @param string $ip + * @param string $ip The IP to lookup. * * @return array|null * @throws \Exception @@ -70,7 +84,13 @@ public function getLocation(string $ip) : 'http' ).'://api.ipstack.com/', 'timeout' => $this->timeout, - ]))->get($ip.'?access_key='.$this->api_key.'&output=json'); + ]))->get( + $ip.'?access_key='.$this->api_key. + '&output=json'. + ($this->find_hostname?'&hostname=1':''). + ($this->assess_security?'&security=1':''). + '&language='.$this->language + ); if ($response->getStatusCode() == 200) { $compiled = json_decode($response->getBody()->getContents(), true); @@ -111,7 +131,54 @@ public function getLocations(string ...$ips) : 'http' ).'://api.ipstack.com/', 'timeout' => $this->timeout, - ]))->get(implode(',', $ips).'?access_key='.$this->api_key.'&output=json'); + ]))->get( + implode(',', $ips).'?access_key='.$this->api_key. + '&output=json'. + ($this->find_hostname?'&hostname=1':''). + ($this->assess_security?'&security=1':''). + '&language='.$this->language + ); + + if ($response->getStatusCode() == 200) { + $compiled = json_decode($response->getBody()->getContents(), true); + if (array_key_exists('error', $compiled)) { + throw new \Exception('Error: '.$compiled['error']['info']); + } + + $ret = $compiled; + } + } catch (\Exception $e) { + throw $e; + } + + return $ret; + } + + /** + * Retrieve the location information for the system executing this code. + * + * @return array|null + * @throws \Exception + */ + public function getOwnLocation() + { + $ret = null; + + try { + $response = (new Client([ + 'base_uri' => ( + ($this->use_https) + ? 'https' + : 'http' + ).'://api.ipstack.com/', + 'timeout' => $this->timeout, + ]))->get( + 'check?access_key='.$this->api_key. + '&output=json'. + ($this->find_hostname?'&hostname=1':''). + ($this->assess_security?'&security=1':''). + '&language='.$this->language + ); if ($response->getStatusCode() == 200) { $compiled = json_decode($response->getBody()->getContents(), true); @@ -145,4 +212,128 @@ public function getClientLocation() return $this->getLocationFor($ip); } + + /** + * Set whether or not to attempt reverse hostname lookup when + * looking up location data. + * + * @var bool $value The new value. + * + * @see https://ipstack.com/documentation#hostname + * @return \IPStack\PHP\GeoLookup + */ + public function setFindHostname(bool $value) + { + $this->find_hostname = $value; + + return $this; + } + + /** + * Get whether or not to attempt reverse hostname lookup when + * looking up location data. + * + * @return bool + */ + public function getFindHostname() + { + return $this->find_hostname; + } + + /** + * Set whether or not to use HTTPS with this connection. + * + * @var bool $value The new value. + * + * @return \IPStack\PHP\GeoLookup + */ + public function useHttps(bool $value) + { + $this->use_https = $value; + + return $this; + } + + /** + * Get whether or not to use HTTPS with this connection. + * + * @return bool + */ + public function isUsingHttps() + { + return $this->use_https; + } + + /** + * Set whether or not to assess the security of an IP address. + * + * @var bool $value The new value. + * + * @see https://ipstack.com/documentation#security + * @return \IPStack\PHP\GeoLookup + */ + public function assessSecurity(bool $value) + { + $this->assess_security = $value; + + return $this; + } + + /** + * Get whether or not to assess the security of an IP address. + * + * @return bool + */ + public function isAssessingSecurity() + { + return $this->assess_security; + } + + /** + * Set the timeout for connections. + * + * @var int $value The new value. + * + * @return \IPStack\PHP\GeoLookup + */ + public function setTimeout(int $value) + { + $this->timeout = $value; + + return $this; + } + + /** + * Specify the language that the response should be translated into. + * + * @var int $value The new language. + * + * @see https://ipstack.com/documentation#language + * @return \IPStack\PHP\GeoLookup + */ + public function setLanguage(string $language) + { + $this->language = $language; + + return $this; + } + + /** + * Retrieve the currently configured language. + * + * @return string + */ + public function getLanguage() + { + return $this->language; + } + + /** + * Get the timeout for connections. + * + * @return int + */ + public function getTimeout() { + return $this->timeout; + } } diff --git a/tests/GeoLookupTest.php b/tests/GeoLookupTest.php index 2d0183e..20cd11c 100644 --- a/tests/GeoLookupTest.php +++ b/tests/GeoLookupTest.php @@ -69,4 +69,13 @@ public function testGetLocationsBulkRequestReturnsExceptionOnMoreThan50IPs() } $location = $geo->getLocations(...$input); } + + public function testGetOwnLocationReturnsArray() + { + $geo = new GeoLookup('d0164200acfaa5ad0a154d1a7398bc90'); + + $location = $geo->getOwnLocation(); + + $this->assertInternalType('array', $location); + } } From eb65efce261d18268157abdc0edb987fc96a5b76 Mon Sep 17 00:00:00 2001 From: Nathan Fiscaletti Date: Thu, 27 Jun 2019 14:43:02 -0500 Subject: [PATCH 2/4] Fixed StyleCI: Stage 1 --- src/IPStack/GeoLookup.php | 51 ++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 25 deletions(-) diff --git a/src/IPStack/GeoLookup.php b/src/IPStack/GeoLookup.php index 0722918..42b548b 100644 --- a/src/IPStack/GeoLookup.php +++ b/src/IPStack/GeoLookup.php @@ -35,21 +35,21 @@ class GeoLookup /** * Whether or not to attempt reverse hostname lookup when * looking up location data. - * + * * @var bool */ private $find_hostname = false; /** * Whether or not to assess the security of an IP address. - * + * * @var bool */ private $assess_security = false; /** * The language to translate the response into. - * + * * @var string */ private $language = 'en'; @@ -60,7 +60,8 @@ class GeoLookup * * @param string $api_key Your IPStack API Key. */ - public function __construct(string $api_key) { + public function __construct(string $api_key) + { $this->api_key = $api_key; } @@ -87,8 +88,8 @@ public function getLocation(string $ip) ]))->get( $ip.'?access_key='.$this->api_key. '&output=json'. - ($this->find_hostname?'&hostname=1':''). - ($this->assess_security?'&security=1':''). + ($this->find_hostname ? '&hostname=1' : ''). + ($this->assess_security ? '&security=1' : ''). '&language='.$this->language ); @@ -134,8 +135,8 @@ public function getLocations(string ...$ips) ]))->get( implode(',', $ips).'?access_key='.$this->api_key. '&output=json'. - ($this->find_hostname?'&hostname=1':''). - ($this->assess_security?'&security=1':''). + ($this->find_hostname ? '&hostname=1' : ''). + ($this->assess_security ? '&security=1' : ''). '&language='.$this->language ); @@ -156,7 +157,7 @@ public function getLocations(string ...$ips) /** * Retrieve the location information for the system executing this code. - * + * * @return array|null * @throws \Exception */ @@ -175,8 +176,8 @@ public function getOwnLocation() ]))->get( 'check?access_key='.$this->api_key. '&output=json'. - ($this->find_hostname?'&hostname=1':''). - ($this->assess_security?'&security=1':''). + ($this->find_hostname ? '&hostname=1' : ''). + ($this->assess_security ? '&security=1' : ''). '&language='.$this->language ); @@ -217,7 +218,7 @@ public function getClientLocation() * Set whether or not to attempt reverse hostname lookup when * looking up location data. * - * @var bool $value The new value. + * @param bool $value The new value. * * @see https://ipstack.com/documentation#hostname * @return \IPStack\PHP\GeoLookup @@ -243,7 +244,7 @@ public function getFindHostname() /** * Set whether or not to use HTTPS with this connection. * - * @var bool $value The new value. + * @param bool $value The new value. * * @return \IPStack\PHP\GeoLookup */ @@ -267,7 +268,7 @@ public function isUsingHttps() /** * Set whether or not to assess the security of an IP address. * - * @var bool $value The new value. + * @param bool $value The new value. * * @see https://ipstack.com/documentation#security * @return \IPStack\PHP\GeoLookup @@ -292,7 +293,7 @@ public function isAssessingSecurity() /** * Set the timeout for connections. * - * @var int $value The new value. + * @param int $value The new value. * * @return \IPStack\PHP\GeoLookup */ @@ -303,10 +304,19 @@ public function setTimeout(int $value) return $this; } + /** + * Get the timeout for connections. + * + * @return int + */ + public function getTimeout() { + return $this->timeout; + } + /** * Specify the language that the response should be translated into. * - * @var int $value The new language. + * @param int $value The new language. * * @see https://ipstack.com/documentation#language * @return \IPStack\PHP\GeoLookup @@ -327,13 +337,4 @@ public function getLanguage() { return $this->language; } - - /** - * Get the timeout for connections. - * - * @return int - */ - public function getTimeout() { - return $this->timeout; - } } From 63ac5a56dfab60484134ab8b23ff359d22eb507e Mon Sep 17 00:00:00 2001 From: Nathan Fiscaletti Date: Thu, 27 Jun 2019 14:43:40 -0500 Subject: [PATCH 3/4] Fixed StyleCI: Stage 2 --- src/IPStack/GeoLookup.php | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/IPStack/GeoLookup.php b/src/IPStack/GeoLookup.php index 42b548b..d7f4602 100644 --- a/src/IPStack/GeoLookup.php +++ b/src/IPStack/GeoLookup.php @@ -306,10 +306,11 @@ public function setTimeout(int $value) /** * Get the timeout for connections. - * + * * @return int */ - public function getTimeout() { + public function getTimeout() + { return $this->timeout; } @@ -317,7 +318,7 @@ public function getTimeout() { * Specify the language that the response should be translated into. * * @param int $value The new language. - * + * * @see https://ipstack.com/documentation#language * @return \IPStack\PHP\GeoLookup */ @@ -330,7 +331,7 @@ public function setLanguage(string $language) /** * Retrieve the currently configured language. - * + * * @return string */ public function getLanguage() From 3a5ec23018891e0f6396677bd9bf14b1b8560d0f Mon Sep 17 00:00:00 2001 From: Nathan Fiscaletti Date: Thu, 27 Jun 2019 14:49:21 -0500 Subject: [PATCH 4/4] Fixed Tests --- tests/GeoLookupTest.php | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/tests/GeoLookupTest.php b/tests/GeoLookupTest.php index 20cd11c..eb8e653 100644 --- a/tests/GeoLookupTest.php +++ b/tests/GeoLookupTest.php @@ -21,12 +21,12 @@ public function testGetLocationForReturnsLocationObject() public function testGetLocationWithHttpsForReturnsLocationObjectOnInvalidPlan() { - $geo = new GeoLookup('d0164200acfaa5ad0a154d1a7398bc90', true); + $geo = new GeoLookup('d0164200acfaa5ad0a154d1a7398bc90'); $this->expectException(\Exception::class); $this->expectExceptionMessage('Error: Access Restricted - Your current Subscription Plan does not support HTTPS Encryption.'); - $location = $geo->getLocation('github.com'); + $location = $geo->useHttps(true)->getLocation('github.com'); $this->assertInternalType('array', $location); } @@ -39,8 +39,6 @@ public function testGetClientLocationOnUnableToFindClientIp() $this->expectExceptionMessage('Error: Unable to find client IP address.'); $location = $geo->getClientLocation(); - - $this->assertInstanceOf(Location::class, $location); } public function testGetLocationsBulkRequestReturnsErrorOnMissingAPIPermissions()