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