├── src ├── Exceptions │ └── IncludeNotValidException.php ├── Barangay.php ├── City.php ├── Region.php ├── District.php ├── Province.php ├── Municipality.php ├── Facades │ ├── City.php │ ├── Region.php │ ├── Barangay.php │ ├── District.php │ ├── Province.php │ ├── Municipality.php │ └── SubMunicipality.php ├── SubMunicipality.php ├── Providers │ └── PSGCServiceProvider.php ├── Resources │ ├── Region.php │ ├── District.php │ ├── Province.php │ ├── SubMunicipality.php │ ├── Barangay.php │ ├── City.php │ ├── Municipality.php │ └── BaseResource.php └── Base.php ├── composer.json ├── license.md └── readme.md /src/Exceptions/IncludeNotValidException.php: -------------------------------------------------------------------------------- 1 | resource = 'barangays'; 17 | 18 | $this->class = Resources\Barangay::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/City.php: -------------------------------------------------------------------------------- 1 | resource = 'cities'; 17 | 18 | $this->class = Resources\City::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/Region.php: -------------------------------------------------------------------------------- 1 | resource = 'regions'; 17 | 18 | $this->class = Resources\Region::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/District.php: -------------------------------------------------------------------------------- 1 | resource = 'districts'; 17 | 18 | $this->class = Resources\District::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/Province.php: -------------------------------------------------------------------------------- 1 | resource = 'provinces'; 17 | 18 | $this->class = Resources\Province::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/Municipality.php: -------------------------------------------------------------------------------- 1 | resource = 'municipalities'; 17 | 18 | $this->class = Resources\Municipality::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/Facades/City.php: -------------------------------------------------------------------------------- 1 | resource = 'sub-municipalities'; 17 | 18 | $this->class = Resources\SubMunicipality::class; 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /src/Facades/Region.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 22 | $this->name = $data->name; 23 | $this->population = $data->population; 24 | 25 | $this->initializeProvinces($data); 26 | $this->initializeDistricts($data); 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /src/Resources/District.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 24 | $this->name = $data->name; 25 | $this->population = $data->population; 26 | 27 | $this->initializeCities($data); 28 | $this->initializeMunicipalities($data); 29 | 30 | if (property_exists($data, 'region')) { 31 | $this->region = new Region($data->region); 32 | } 33 | } 34 | } 35 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "bkintanar/psgc-api-wrapper", 3 | "description": "PHP Wrapper for Philippine Standard Geographic Code API", 4 | "type": "library", 5 | "license": "MIT", 6 | "authors": [ 7 | { 8 | "name": "Bertrand Kintanar", 9 | "email": "bertrand.kintanar@gmail.com" 10 | } 11 | ], 12 | "require": { 13 | "guzzlehttp/guzzle": "^6.5|^7.0", 14 | "illuminate/support": "^6.0|^7.0|^8.0", 15 | "ext-json": "*" 16 | }, 17 | "autoload": { 18 | "psr-4": { 19 | "PSGC\\": "src" 20 | } 21 | }, 22 | "extra": { 23 | "laravel": { 24 | "providers": [ 25 | "PSGC\\Providers\\PSGCServiceProvider" 26 | ] 27 | } 28 | }, 29 | "prefer-stable": true, 30 | "minimum-stability": "dev" 31 | } 32 | -------------------------------------------------------------------------------- /src/Resources/Province.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 26 | $this->name = $data->name; 27 | $this->incomeClass = $data->income_class; 28 | $this->population = $data->population; 29 | 30 | $this->initializeCities($data); 31 | $this->initializeMunicipalities($data); 32 | 33 | if (property_exists($data, 'region')) { 34 | $this->region = new Region($data->region); 35 | } 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /src/Resources/SubMunicipality.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 26 | $this->name = $data->name; 27 | $this->population = $data->population; 28 | 29 | $this->initializeBarangays($data); 30 | 31 | if (property_exists($data, 'city')) { 32 | $this->city = new City($data->city); 33 | } 34 | 35 | if (property_exists($data, 'district')) { 36 | $this->district = new District($data->district); 37 | } 38 | 39 | if (property_exists($data, 'region')) { 40 | $this->region = new Region($data->region); 41 | } 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /license.md: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright 2020 Bertrand Kintanar 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 6 | 7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 10 | -------------------------------------------------------------------------------- /src/Resources/Barangay.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 24 | $this->name = $data->name; 25 | $this->urbanRural = $data->urban_rural; 26 | 27 | if (property_exists($data, 'population')) { 28 | $this->population = $data->population; 29 | } 30 | 31 | if (property_exists($data, 'municipality')) { 32 | $this->municipality = new Municipality($data->municipality); 33 | } 34 | 35 | if (property_exists($data, 'province')) { 36 | $this->province = new Province($data->province); 37 | } 38 | 39 | if (property_exists($data, 'region')) { 40 | $this->region = new Region($data->region); 41 | } 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /src/Resources/City.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 30 | $this->name = $data->name; 31 | $this->cityClass = $data->city_class; 32 | $this->incomeClass = $data->income_class; 33 | $this->population = $data->population; 34 | 35 | $this->initializeBarangays($data); 36 | $this->initializeSubMunicipalities($data); 37 | 38 | if (property_exists($data, 'province')) { 39 | $this->province = new Province($data->province); 40 | } 41 | 42 | if (property_exists($data, 'region')) { 43 | $this->region = new Region($data->region); 44 | } 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /src/Resources/Municipality.php: -------------------------------------------------------------------------------- 1 | code = $data->code; 29 | $this->name = $data->name; 30 | $this->incomeClass = $data->income_class; 31 | $this->population = $data->population; 32 | 33 | $this->initializeBarangays($data); 34 | 35 | if (property_exists($data, 'province')) { 36 | $this->province = new Province($data->province); 37 | } 38 | 39 | if (property_exists($data, 'district')) { 40 | $this->district = new District($data->district); 41 | } 42 | 43 | if (property_exists($data, 'region')) { 44 | $this->region = new Region($data->region); 45 | } 46 | } 47 | } 48 | -------------------------------------------------------------------------------- /src/Resources/BaseResource.php: -------------------------------------------------------------------------------- 1 | provinces = collect(); 11 | 12 | foreach ($data->provinces as $province) { 13 | $this->provinces->push(new Province($province)); 14 | } 15 | } 16 | } 17 | 18 | protected function initializeDistricts($data) 19 | { 20 | if (property_exists($data, 'districts')) { 21 | $this->districts = collect(); 22 | 23 | foreach ($data->districts as $district) { 24 | $this->districts->push(new District($district)); 25 | } 26 | } 27 | } 28 | 29 | protected function initializeCities($data) 30 | { 31 | if (property_exists($data, 'cities')) { 32 | $this->cities = collect(); 33 | 34 | foreach ($data->cities as $city) { 35 | $this->cities->push(new City($city)); 36 | } 37 | } 38 | } 39 | 40 | protected function initializeMunicipalities($data) 41 | { 42 | if (property_exists($data, 'municipalities')) { 43 | $this->municipalities = collect(); 44 | 45 | foreach ($data->municipalities as $municipality) { 46 | $this->municipalities->push(new Municipality($municipality)); 47 | } 48 | } 49 | } 50 | 51 | protected function initializeSubMunicipalities($data) 52 | { 53 | if (property_exists($data, 'sub_municipalities')) { 54 | $this->subMunicipalities = collect(); 55 | 56 | foreach ($data->sub_municipalities as $subMunicipality) { 57 | $this->subMunicipalities->push(new SubMunicipality($subMunicipality)); 58 | } 59 | } 60 | } 61 | 62 | protected function initializeBarangays($data) 63 | { 64 | if (property_exists($data, 'barangays')) { 65 | $this->barangays = collect(); 66 | 67 | foreach ($data->barangays as $barangay) { 68 | $this->barangays->push(new Barangay($barangay)); 69 | } 70 | } 71 | } 72 | } 73 | -------------------------------------------------------------------------------- /src/Base.php: -------------------------------------------------------------------------------- 1 | client = new Client(['base_uri' => 'http://bkintanar-psgc.herokuapp.com/api/']); 33 | } 34 | 35 | /** 36 | * @param $code 37 | * 38 | * @throws IncludeNotValidException 39 | * @throws \GuzzleHttp\Exception\GuzzleException 40 | * 41 | * @return mixed 42 | */ 43 | public function find($code) 44 | { 45 | $this->endpoint = "{$this->resource}/{$code}"; 46 | 47 | return $this->request(); 48 | } 49 | 50 | /** 51 | * @param array|string $includes 52 | * 53 | * @return Base 54 | */ 55 | public function includes($includes = []): Base 56 | { 57 | if (! is_array($includes)) { 58 | $includes = [$includes]; 59 | } 60 | 61 | $this->includes = $includes; 62 | 63 | return $this; 64 | } 65 | 66 | /** 67 | * @throws IncludeNotValidException 68 | * @throws \GuzzleHttp\Exception\GuzzleException 69 | * 70 | * @return mixed 71 | */ 72 | public function get() 73 | { 74 | $this->endpoint = $this->resource; 75 | $this->perPage = 'all'; 76 | 77 | return $this->request(); 78 | } 79 | 80 | public function first() 81 | { 82 | $response = $this->get(); 83 | 84 | if ($response) { 85 | return $response->first(); 86 | } 87 | 88 | return collect(); 89 | } 90 | 91 | /** 92 | * @throws IncludeNotValidException 93 | * @throws \GuzzleHttp\Exception\GuzzleException 94 | * 95 | * @return mixed 96 | */ 97 | private function request() 98 | { 99 | $this->validateIncludes(); 100 | 101 | $query = $this->buildQueryParams(); 102 | 103 | try { 104 | $response = $this->client->request('GET', $this->endpoint, compact('query')); 105 | 106 | if ($response->getStatusCode() == 200) { 107 | $data = json_decode($response->getBody()->getContents())->data; 108 | 109 | if (is_array($data)) { 110 | $result = collect(); 111 | foreach ($data as $item) { 112 | $result->push(new $this->class($item)); 113 | } 114 | 115 | return $result->sortBy('code'); 116 | } 117 | 118 | return new $this->class($data); 119 | } 120 | } catch (GuzzleException $e) { 121 | if ($e->getCode() == 404) { 122 | return collect(); 123 | } 124 | } 125 | } 126 | 127 | /** 128 | * @throws IncludeNotValidException 129 | * 130 | * @return void 131 | */ 132 | private function validateIncludes(): void 133 | { 134 | if (empty($this->includes)) { 135 | return; 136 | } 137 | 138 | foreach ($this->includes as $include) { 139 | if (! in_array($include, $this->validIncludes)) { 140 | throw new IncludeNotValidException("\"{$include}\" is not a valid includes for the resource \"{$this->resource}\". Valid includes for \"{$this->resource}\" are: " . implode(', ', $this->validIncludes)); 141 | } 142 | } 143 | } 144 | 145 | /** 146 | * @return string 147 | */ 148 | private function buildQueryParams(): string 149 | { 150 | return http_build_query(array_filter(['include' => implode(',', $this->includes), 'page' => $this->page, 'per_page' => $this->perPage])); 151 | } 152 | } 153 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # PHP Wrapper for Philippine Standard Geographic Code API 2 | 3 | ## Overview 4 | 5 | This package is a simple php wrapper for the PSGC API found here: https://github.com/bkintanar/psgc-api. 6 | 7 | ## Installation 8 | 9 | The recommended way to install PSGC API Wrapper is with Composer. Composer is a dependency management tool for PHP that allows you to declare the dependencies your project needs and installs them into your project. 10 | 11 | ```shell script 12 | # Install Composer 13 | curl -sS https://getcomposer.org/installer | php 14 | ``` 15 | 16 | You can add PSGC API Wrapper as a dependency using Composer: 17 | 18 | ```shell script 19 | composer require bkintanar/psgc-api-wrapper 20 | ``` 21 | 22 | Alternatively, you can specify PSGC API Wrapper as a dependency in your project's existing composer.json file: 23 | 24 | ```json 25 | { 26 | "require": { 27 | "bkintanar/psgc-api-wrapper": "*" 28 | } 29 | } 30 | ``` 31 | 32 | ## Supported Methods 33 | 34 | All endpoints provided by `https://github.com/bkintanar/psgc-api` are supported. 35 | 36 | ``` 37 | +----------+------------------------------------------+ 38 | | Method | URI | 39 | +----------+------------------------------------------+ 40 | | GET|HEAD | api/barangays | 41 | | GET|HEAD | api/barangays/{barangay} | 42 | | GET|HEAD | api/cities | 43 | | GET|HEAD | api/cities/{city} | 44 | | GET|HEAD | api/districts | 45 | | GET|HEAD | api/districts/{district} | 46 | | GET|HEAD | api/municipalities | 47 | | GET|HEAD | api/municipalities/{municipality} | 48 | | GET|HEAD | api/provinces | 49 | | GET|HEAD | api/provinces/{province} | 50 | | GET|HEAD | api/regions | 51 | | GET|HEAD | api/regions/{region} | 52 | | GET|HEAD | api/sub-municipalities | 53 | | GET|HEAD | api/sub-municipalities/{subMunicipality} | 54 | +----------+------------------------------------------+ 55 | ``` 56 | 57 | ### Using Laravel 58 | 59 | #### Region 60 | 61 | Region is the highest geographic level used by The Republic of the Philippines. The Philippines is divided into 17 regions as of 31 March 2020. 62 | 63 | ```php 64 | get(); // Get a Collection of regions and provinces 71 | Region::includes('districts')->get(); // Get a Collection of regions and districts 72 | Region::includes(['provinces', 'districts'])->get(); // Get a Collection of regions and provinces and districts 73 | ``` 74 | 75 | #### District 76 | 77 | > This geographic level is only used by the National Capital Region (NCR). 78 | 79 | Unlike other administrative regions in the Philippines, Metro Manila is not composed of provinces. Instead, the region is divided into four geographic areas called "districts." 80 | 81 | So instead of the usual geographic hierarchy of: 82 | 83 | ``` 84 | Region > Provinces > Cities, Municipalities > Barangays 85 | ``` 86 | 87 | The National Capital Region follows the geographic hierarchy of: 88 | 89 | ``` 90 | Region > Districts > Cities > Sub Municipalities > Barangays 91 | ``` 92 | 93 | ```php 94 | get(); // Get a Collection of districts with its collection of cities 101 | District::includes('cities')->find('133900000'); // Get a specific district with its collection of cities 102 | ``` 103 | 104 | #### Province 105 | 106 | One or more provinces belongs to one region. The Philippines is administratively divided into 81 provinces as of 31 March 2020. Any given province has one or more cities, and municipalities under it. 107 | 108 | ```php 109 | get(); // Get a Collection of provinces with its collection of cities 116 | Province::includes('cities')->find('072200000'); // Get a specific province with its collection of cities 117 | Province::includes('municipalities')->get(); // Get a Collection of provinces with its collection of municipalities 118 | Province::includes('municipalities')->find('072200000'); // Get a specific province with its collection of municipalities 119 | Province::includes(['cities', 'municipalities'])->get(); // Get a Collection of provinces with its collection of cities and municipalities 120 | Province::includes(['cities', 'municipalities'])->find('072200000'); // Get a specific province with its collection of cities and municipalities 121 | ``` 122 | 123 | 124 | #### City 125 | 126 | One or more cities belongs to one province or district. The Philippines is administratively divided into 146 cities as of 31 March 2020. Any given city has one or more barangays, sub-municipalities under it. 127 | 128 | ```php 129 | get(); // Get a Collection of cities with its collection of barangays. Not advised as this will retrieve all 42,046 barangays. 136 | City::includes('barangays')->find('072217000'); // Get a specific city with its collection of barangays 137 | City::includes('subMunicipalities')->find('133900000'); // Get a specific city with its collection of sub-municipalities 138 | ``` 139 | 140 | #### Municipality 141 | 142 | One or more municipalities belongs to one Province. The Philippines is administratively divided into 1,488 municipalities as of 31 March 2020. Any given municipality has one or more barangays under it. 143 | 144 | ```php 145 | get(); // Get a Collection of municipalities with its collection of barangays. 152 | Municipality::includes('barangays')->find('072201000'); // Get a specific municipality with its collection of barangays 153 | ``` 154 | 155 | #### Sub Municipality 156 | 157 | > This geographic level is only used by the National Capital Region (NCR). 158 | 159 | As far as NCR is concerned, cities have one or more sub-municipalities and each sub-municipality has one or more barangays. 160 | 161 | ```php 162 | get(); // Get a Collection of sub-municipalities with its collection of barangays. 169 | SubMunicipality::includes('barangays')->find('133901000'); // Get a specific sub-municipality with its collection of barangays 170 | ``` 171 | 172 | #### Barangay 173 | 174 | This is the lowest geographic level used by The Philippines. Any given barangay may be under to one city, one municipality, one sub-municipality. As barangay's the lowest geographic level, it doesn't have any geographic level under it, so no valid `includes`. 175 | 176 | ```php 177 | get(); // Get a Collection of regions 197 | $region->find('070000000'); // Get a specific region 198 | $region->includes('provinces')->get(); // Get a Collection of regions and provinces 199 | $region->includes('districts')->get(); // Get a Collection of regions and districts 200 | $region->includes(['provinces', 'districts'])->get(); // Get a Collection of regions and provinces and districts 201 | ``` 202 | 203 | > Follow the pattern above to use with other geographic levels. 204 | --------------------------------------------------------------------------------