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..d7f4602 100644 --- a/src/IPStack/GeoLookup.php +++ b/src/IPStack/GeoLookup.php @@ -11,49 +11,64 @@ */ class GeoLookup { + /** + * The API key used to connect to the IPStack API. + * + * @var string + */ + private $api_key; + /** * The timeout for the current server. * * @var int */ - private $timeout; + private $timeout = 10; /** - * The API key used to connect to the IPStack API. + * If set to true, HTTPS will be used for the connection. * - * @var string + * @var bool */ - private $api_key; + private $use_https = false; /** - * If set to true, HTTPS will be used for the connection. + * 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 $use_https; + 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 +85,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 +132,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 +213,129 @@ public function getClientLocation() return $this->getLocationFor($ip); } + + /** + * Set whether or not to attempt reverse hostname lookup when + * looking up location data. + * + * @param 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. + * + * @param 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. + * + * @param 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. + * + * @param int $value The new value. + * + * @return \IPStack\PHP\GeoLookup + */ + public function setTimeout(int $value) + { + $this->timeout = $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. + * + * @param 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; + } } diff --git a/tests/GeoLookupTest.php b/tests/GeoLookupTest.php index 2d0183e..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() @@ -69,4 +67,13 @@ public function testGetLocationsBulkRequestReturnsExceptionOnMoreThan50IPs() } $location = $geo->getLocations(...$input); } + + public function testGetOwnLocationReturnsArray() + { + $geo = new GeoLookup('d0164200acfaa5ad0a154d1a7398bc90'); + + $location = $geo->getOwnLocation(); + + $this->assertInternalType('array', $location); + } }