1 <?php
2
3 namespace GeoIp2\WebService;
4
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;
14
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';
50
51 const VERSION = 'v2.4.4';
52
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;
75
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 }
81
82 if (!isset($options['host'])) {
83 $options['host'] = 'geoip.maxmind.com';
84 }
85
86 $options['userAgent'] = $this->userAgent();
87
88 $this->client = new WsClient($userId, $licenseKey, $options);
89 }
90
91 private function userAgent()
92 {
93 return 'GeoIP2-API/' . Client::VERSION;
94 }
95
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 }
127
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 }
159
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 }
191
192 private function responseFor($endpoint, $class, $ipAddress)
193 {
194 $path = implode('/', array(self::$basePath, $endpoint, $ipAddress));
195
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 }
238
239 $class = "GeoIp2\\Model\\" . $class;
240 return new $class($body, $this->locales);
241 }
242 }
243