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.1';
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: }
244: