Overview

Namespaces

  • GeoIp2
    • Compat
    • Database
    • Exception
    • Model
    • Record
    • WebService
  • PHP

Classes

  • Client
  • Overview
  • Namespace
  • Class
  • Tree
  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: 
GeoIP2 PHP API v2.4.1 API documentation generated by ApiGen