MDL-48766 lib: Import MaxMind GeoIP2 PHP API
[moodle.git] / lib / maxmind / GeoIp2 / WebService / Client.php
1 <?php
3 namespace GeoIp2\WebService;
5 use GeoIp2\Exception\AddressNotFoundException;
6 use GeoIp2\Exception\AuthenticationException;
7 use GeoIp2\Exception\GeoIp2Exception;
8 use GeoIp2\Exception\HttpException;
9 use GeoIp2\Exception\InvalidRequestException;
10 use GeoIp2\Exception\OutOfQueriesException;
11 use GeoIp2\ProviderInterface;
12 use MaxMind\Exception\InvalidInputException;
13 use MaxMind\WebService\Client as WsClient;
15 /**
16  * This class provides a client API for all the GeoIP2 Precision web services.
17  * The services are Country, City, and Insights. Each service returns a
18  * different set of data about an IP address, with Country returning the
19  * least data and Insights the most.
20  *
21  * Each web service is represented by a different model class, and these model
22  * classes in turn contain multiple record classes. The record classes have
23  * attributes which contain data about the IP address.
24  *
25  * If the web service does not return a particular piece of data for an IP
26  * address, the associated attribute is not populated.
27  *
28  * The web service may not return any information for an entire record, in
29  * which case all of the attributes for that record class will be empty.
30  *
31  * ## Usage ##
32  *
33  * The basic API for this class is the same for all of the web service end
34  * points. First you create a web service object with your MaxMind `$userId`
35  * and `$licenseKey`, then you call the method corresponding to a specific end
36  * point, passing it the IP address you want to look up.
37  *
38  * If the request succeeds, the method call will return a model class for
39  * the service you called. This model in turn contains multiple record
40  * classes, each of which represents part of the data returned by the web
41  * service.
42  *
43  * If the request fails, the client class throws an exception.
44  */
45 class Client implements ProviderInterface
46 {
47     private $locales;
48     private $client;
49     private static $basePath = '/geoip/v2.1';
51     const VERSION = 'v2.4.2';
53     /**
54      * Constructor.
55      *
56      * @param int $userId     Your MaxMind user ID
57      * @param string $licenseKey Your MaxMind license key
58      * @param array $locales  List of locale codes to use in name property
59      * from most preferred to least preferred.
60      * @param array $options Array of options. Valid options include:
61      *      * `host` - The host to use when querying the web service.
62      *      * `timeout` - Timeout in seconds.
63      *      * `connectTimeout` - Initial connection timeout in seconds.
64      *      * `proxy` - The HTTP proxy to use. May include a schema, port,
65      *        username, and password, e.g.,
66      *        `http://username:password@127.0.0.1:10`.
67      */
68     public function __construct(
69         $userId,
70         $licenseKey,
71         $locales = array('en'),
72         $options = array()
73     ) {
74         $this->locales = $locales;
76         // This is for backwards compatibility. Do not remove except for a
77         // major version bump.
78         if (is_string($options)) {
79             $options = array( 'host' => $options );
80         }
82         if (!isset($options['host'])) {
83             $options['host'] = 'geoip.maxmind.com';
84         }
86         $options['userAgent'] = $this->userAgent();
88         $this->client = new WsClient($userId, $licenseKey, $options);
89     }
91     private function userAgent()
92     {
93         return 'GeoIP2-API/' . Client::VERSION;
94     }
96     /**
97      * This method calls the GeoIP2 Precision: City service.
98      *
99      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
100      * address is provided, the address that the web service is called
101      * from will be used.
102      *
103      * @return \GeoIp2\Model\City
104      *
105      * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
106      *   provided is not in our database (e.g., a private address).
107      * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
108      *   with the user ID or license key that you provided.
109      * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
110      *   of queries.
111      * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
112      *   received by the web service but is invalid for some other reason.
113      *   This may indicate an issue with this API. Please report the error to
114      *   MaxMind.
115      * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
116      *   code or message was returned. This could indicate a problem with the
117      *   connection between your server and the web service or that the web
118      *   service returned an invalid document or 500 error code.
119      * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
120      *   class to the above exceptions. It will be thrown directly if a 200
121      *   status code is returned but the body is invalid.
122      */
123     public function city($ipAddress = 'me')
124     {
125         return $this->responseFor('city', 'City', $ipAddress);
126     }
128     /**
129      * This method calls the GeoIP2 Precision: Country service.
130      *
131      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
132      * address is provided, the address that the web service is called
133      * from will be used.
134      *
135      * @return \GeoIp2\Model\Country
136      *
137      * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
138      *   provided is not in our database (e.g., a private address).
139      * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
140      *   with the user ID or license key that you provided.
141      * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
142      *   of queries.
143      * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
144      *   received by the web service but is invalid for some other reason.
145      *   This may indicate an issue with this API. Please report the error to
146      *   MaxMind.
147      * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
148      *   code or message was returned. This could indicate a problem with the
149      *   connection between your server and the web service or that the web
150      *   service returned an invalid document or 500 error code.
151      * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
152      *   class to the above exceptions. It will be thrown directly if a 200
153      *   status code is returned but the body is invalid.
154      */
155     public function country($ipAddress = 'me')
156     {
157         return $this->responseFor('country', 'Country', $ipAddress);
158     }
160     /**
161      * This method calls the GeoIP2 Precision: Insights service.
162      *
163      * @param string $ipAddress IPv4 or IPv6 address as a string. If no
164      * address is provided, the address that the web service is called
165      * from will be used.
166      *
167      * @return \GeoIp2\Model\Insights
168      *
169      * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
170      *   provided is not in our database (e.g., a private address).
171      * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
172      *   with the user ID or license key that you provided.
173      * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
174      *   of queries.
175      * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
176      *   received by the web service but is invalid for some other reason.
177      *   This may indicate an issue with this API. Please report the error to
178      *   MaxMind.
179      * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
180      *   code or message was returned. This could indicate a problem with the
181      *   connection between your server and the web service or that the web
182      *   service returned an invalid document or 500 error code.
183      * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
184      *   class to the above exceptions. It will be thrown directly if a 200
185      *   status code is returned but the body is invalid.
186      */
187     public function insights($ipAddress = 'me')
188     {
189         return $this->responseFor('insights', 'Insights', $ipAddress);
190     }
192     private function responseFor($endpoint, $class, $ipAddress)
193     {
194         $path = implode('/', array(self::$basePath, $endpoint, $ipAddress));
196         try {
197             $body = $this->client->get('GeoIP2 ' . $class, $path);
198         } catch (\MaxMind\Exception\IpAddressNotFoundException $ex) {
199             throw new AddressNotFoundException(
200                 $ex->getMessage(),
201                 $ex->getStatusCode(),
202                 $ex
203             );
204         } catch (\MaxMind\Exception\AuthenticationException $ex) {
205             throw new AuthenticationException(
206                 $ex->getMessage(),
207                 $ex->getStatusCode(),
208                 $ex
209             );
210         } catch (\MaxMind\Exception\InsufficientFundsException $ex) {
211             throw new OutOfQueriesException(
212                 $ex->getMessage(),
213                 $ex->getStatusCode(),
214                 $ex
215             );
216         } catch (\MaxMind\Exception\InvalidRequestException $ex) {
217             throw new InvalidRequestException(
218                 $ex->getMessage(),
219                 $ex->getErrorCode(),
220                 $ex->getStatusCode(),
221                 $ex->getUri(),
222                 $ex
223             );
224         } catch (\MaxMind\Exception\HttpException $ex) {
225             throw new HttpException(
226                 $ex->getMessage(),
227                 $ex->getStatusCode(),
228                 $ex->getUri(),
229                 $ex
230             );
231         } catch (\MaxMind\Exception\WebServiceException $ex) {
232             throw new GeoIp2Exception(
233                 $ex->getMessage(),
234                 $ex->getCode(),
235                 $ex
236             );
237         }
239         $class = "GeoIp2\\Model\\" . $class;
240         return new $class($body, $this->locales);
241     }