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 service
17: * end points. The end points are Country, City, and Insights. Each end point
18: * returns a different set of data about an IP address, with Country returning
19: * the least data and Insights the most.
20: *
21: * Each web service end point is represented by a different model class, and
22: * these model classes in turn contain multiple Record classes. The record
23: * classes have 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 end point 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.3.2';
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: */
65: public function __construct(
66: $userId,
67: $licenseKey,
68: $locales = array('en'),
69: $options = array()
70: ) {
71: $this->locales = $locales;
72:
73: // This is for backwards compatibility. Do not remove except for a
74: // major version bump.
75: if (is_string($options)) {
76: $options = array( 'host' => $options );
77: }
78:
79: if (!isset($options['host'])) {
80: $options['host'] = 'geoip.maxmind.com';
81: }
82:
83: $options['userAgent'] = $this->userAgent();
84:
85: $this->client = new WsClient($userId, $licenseKey, $options);
86: }
87:
88: private function userAgent()
89: {
90: return 'GeoIP2-API/' . Client::VERSION;
91: }
92:
93: /**
94: * This method calls the GeoIP2 Precision: City endpoint.
95: *
96: * @param string $ipAddress IPv4 or IPv6 address as a string. If no
97: * address is provided, the address that the web service is called
98: * from will be used.
99: *
100: * @return \GeoIp2\Model\City
101: *
102: * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
103: * provided is not in our database (e.g., a private address).
104: * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
105: * with the user ID or license key that you provided.
106: * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
107: * of queries.
108: * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
109: * received by the web service but is invalid for some other reason.
110: * This may indicate an issue with this API. Please report the error to
111: * MaxMind.
112: * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
113: * code or message was returned. This could indicate a problem with the
114: * connection between your server and the web service or that the web
115: * service returned an invalid document or 500 error code.
116: * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
117: * class to the above exceptions. It will be thrown directly if a 200
118: * status code is returned but the body is invalid.
119: */
120: public function city($ipAddress = 'me')
121: {
122: return $this->responseFor('city', 'City', $ipAddress);
123: }
124:
125: /**
126: * This method calls the GeoIP2 Precision: Country endpoint.
127: *
128: * @param string $ipAddress IPv4 or IPv6 address as a string. If no
129: * address is provided, the address that the web service is called
130: * from will be used.
131: *
132: * @return \GeoIp2\Model\Country
133: *
134: * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
135: * provided is not in our database (e.g., a private address).
136: * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
137: * with the user ID or license key that you provided.
138: * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
139: * of queries.
140: * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
141: * received by the web service but is invalid for some other reason.
142: * This may indicate an issue with this API. Please report the error to
143: * MaxMind.
144: * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
145: * code or message was returned. This could indicate a problem with the
146: * connection between your server and the web service or that the web
147: * service returned an invalid document or 500 error code.
148: * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
149: * class to the above exceptions. It will be thrown directly if a 200
150: * status code is returned but the body is invalid.
151: */
152: public function country($ipAddress = 'me')
153: {
154: return $this->responseFor('country', 'Country', $ipAddress);
155: }
156:
157: /**
158: * This method calls the GeoIP2 Precision: Insights endpoint.
159: *
160: * @param string $ipAddress IPv4 or IPv6 address as a string. If no
161: * address is provided, the address that the web service is called
162: * from will be used.
163: *
164: * @return \GeoIp2\Model\Insights
165: *
166: * @throws \GeoIp2\Exception\AddressNotFoundException if the address you
167: * provided is not in our database (e.g., a private address).
168: * @throws \GeoIp2\Exception\AuthenticationException if there is a problem
169: * with the user ID or license key that you provided.
170: * @throws \GeoIp2\Exception\OutOfQueriesException if your account is out
171: * of queries.
172: * @throws \GeoIp2\Exception\InvalidRequestException} if your request was
173: * received by the web service but is invalid for some other reason.
174: * This may indicate an issue with this API. Please report the error to
175: * MaxMind.
176: * @throws \GeoIp2\Exception\HttpException if an unexpected HTTP error
177: * code or message was returned. This could indicate a problem with the
178: * connection between your server and the web service or that the web
179: * service returned an invalid document or 500 error code.
180: * @throws \GeoIp2\Exception\GeoIp2Exception This serves as the parent
181: * class to the above exceptions. It will be thrown directly if a 200
182: * status code is returned but the body is invalid.
183: */
184: public function insights($ipAddress = 'me')
185: {
186: return $this->responseFor('insights', 'Insights', $ipAddress);
187: }
188:
189: private function responseFor($endpoint, $class, $ipAddress)
190: {
191: $path = implode('/', array(self::$basePath, $endpoint, $ipAddress));
192:
193: try {
194: $body = $this->client->get('GeoIP2 ' . $class, $path);
195: } catch (\MaxMind\Exception\IpAddressNotFoundException $ex) {
196: throw new AddressNotFoundException(
197: $ex->getMessage(),
198: $ex->getStatusCode(),
199: $ex
200: );
201: } catch (\MaxMind\Exception\AuthenticationException $ex) {
202: throw new AuthenticationException(
203: $ex->getMessage(),
204: $ex->getStatusCode(),
205: $ex
206: );
207: } catch (\MaxMind\Exception\InsufficientFundsException $ex) {
208: throw new OutOfQueriesException(
209: $ex->getMessage(),
210: $ex->getStatusCode(),
211: $ex
212: );
213: } catch (\MaxMind\Exception\InvalidRequestException $ex) {
214: throw new InvalidRequestException(
215: $ex->getMessage(),
216: $ex->getErrorCode(),
217: $ex->getStatusCode(),
218: $ex->getUri(),
219: $ex
220: );
221: } catch (\MaxMind\Exception\HttpException $ex) {
222: throw new HttpException(
223: $ex->getMessage(),
224: $ex->getStatusCode(),
225: $ex->getUri(),
226: $ex
227: );
228:
229: } catch (\MaxMind\Exception\WebServiceException $ex) {
230: throw new GeoIp2Exception(
231: $ex->getMessage(),
232: $ex->getCode(),
233: $ex
234: );
235: }
236:
237: $class = "GeoIp2\\Model\\" . $class;
238: return new $class($body, $this->locales);
239:
240: }
241: }
242: