MDL-48766 lib: Import MaxMind GeoIP2 PHP API
[moodle.git] / lib / maxmind / GeoIp2 / Model / City.php
1 <?php
3 namespace GeoIp2\Model;
5 /**
6  * Model class for the data returned by GeoIP2 City web service and database.
7  *
8  * The only difference between the City and Insights model classes is which
9  * fields in each record may be populated. See
10  * http://dev.maxmind.com/geoip/geoip2/web-services more details.
11  *
12  * @property-read \GeoIp2\Record\City $city City data for the requested IP
13  * address.
14  *
15  * @property-read \GeoIp2\Record\Continent $continent Continent data for the
16  * requested IP address.
17  *
18  * @property-read \GeoIp2\Record\Country $country Country data for the requested
19  * IP address. This object represents the country where MaxMind believes the
20  * end user is located.
21  *
22  * @property-read \GeoIp2\Record\Location $location Location data for the
23  * requested IP address.
24  *
25  * @property-read \GeoIp2\Record\Postal $postal Postal data for the
26  * requested IP address.
27  *
28  * @property-read \GeoIp2\Record\MaxMind $maxmind Data related to your MaxMind
29  * account.
30  *
31  * @property-read \GeoIp2\Record\Country $registeredCountry Registered country
32  * data for the requested IP address. This record represents the country
33  * where the ISP has registered a given IP block and may differ from the
34  * user's country.
35  *
36  * @property-read \GeoIp2\Record\RepresentedCountry $representedCountry
37  * Represented country data for the requested IP address. The represented
38  * country is used for things like military bases. It is only present when
39  * the represented country differs from the country.
40  *
41  * @property-read array $subdivisions An array of {@link \GeoIp2\Record\Subdivision}
42  * objects representing the country subdivisions for the requested IP
43  * address. The number and type of subdivisions varies by country, but a
44  * subdivision is typically a state, province, county, etc. Subdivisions
45  * are ordered from most general (largest) to most specific (smallest).
46  * If the response did not contain any subdivisions, this method returns
47  * an empty array.
48  *
49  * @property-read \GeoIp2\Record\Subdivision $mostSpecificSubdivision An  object
50  * representing the most specific subdivision returned. If the response
51  * did not contain any subdivisions, this method returns an empty
52  * {@link \GeoIp2\Record\Subdivision} object.
53  *
54  * @property-read \GeoIp2\Record\Traits $traits Data for the traits of the
55  * requested IP address.
56  */
57 class City extends Country
58 {
59     /**
60      * @ignore
61      */
62     protected $city;
63     /**
64      * @ignore
65      */
66     protected $location;
67     /**
68      * @ignore
69      */
70     protected $postal;
71     /**
72      * @ignore
73      */
74     protected $subdivisions = array();
76     /**
77      * @ignore
78      */
79     public function __construct($raw, $locales = array('en'))
80     {
81         parent::__construct($raw, $locales);
83         $this->city = new \GeoIp2\Record\City($this->get('city'), $locales);
84         $this->location = new \GeoIp2\Record\Location($this->get('location'));
85         $this->postal = new \GeoIp2\Record\Postal($this->get('postal'));
87         $this->createSubdivisions($raw, $locales);
88     }
90     private function createSubdivisions($raw, $locales)
91     {
92         if (!isset($raw['subdivisions'])) {
93             return;
94         }
96         foreach ($raw['subdivisions'] as $sub) {
97             array_push(
98                 $this->subdivisions,
99                 new \GeoIp2\Record\Subdivision($sub, $locales)
100             );
101         }
102     }
104     /**
105      * @ignore
106      */
107     public function __get($attr)
108     {
109         if ($attr == 'mostSpecificSubdivision') {
110             return $this->$attr();
111         } else {
112             return parent::__get($attr);
113         }
114     }
116     private function mostSpecificSubdivision()
117     {
118         return empty($this->subdivisions) ?
119             new \GeoIp2\Record\Subdivision(array(), $this->locales) :
120             end($this->subdivisions);
121     }