claz/wishi

An agnostic package to get different countries, states and counties.


README

Coverage Status Build Status StyleCI
If you have ever needed basic information about countries, and their states, then Locator is for you. Locator is a PHP package that works with the Yahoo API. It returns data that you need just by calling one method. There is a Service Provider and a Facade to make it easy to integrate with your Laravel project. It can also be used with other PHP frameworks like Lumen, CakePHP, Zend, etc. Version 1.0.0 only provides information about the following:

  • Countries
  • States in the country
  • Counties in the state

Dependencies

  • PHP 5.5+
  • Composer 1.4+
  • Apache

Getting Started

To use this package with a PHP project, first require the package using composer.

composer require claz/wishi
  • Note that you must be registered in Yahoo as a developer. Add your Yahoo details to your environment variables.
YAHOO_CLIENT_ID=*********************************

Using plain PHP

If you are using this project with a plain PHP project, follow the following steps:

  • Run composer dumpautoload if required.
  • Require autoload.php and load the package with its dependencies.
require_once ('vendor/autoload.php')

use Wishi\Controllers\Locator;
  • Instantiate the Locator class and you are good to go.
$locator = new Locator();

Using with Laravel

If you are using this project with Laravel, follow the following steps:

  • Open app.config in config folder and,

  • Register the ServiceProvider inside config.php

Wishi\Providers\LocatorServiceProvider::class,
  • To use the Facade, simple add it to the same file.
Locator => Wishi\Facades\Locator::class,
  • Import the Facade into your project.
use Locator;

Example

  • To get all the countries.
// With normal PHP applications
$countries = $locator->getCountries();

// With the Facade in Laravel applications
$countries = Locator::getCountries();

var_dump($countries); // Collection of countries
  • To get all the states in a country.
// With normal PHP applications
$states = $locator->getStates('Nigeria');

// With the Facade in Laravel applications
$states = Locator::getStates('Nigeria');

var_dump($states); // Collection of states
  • To get all the counties in a state.
// With normal PHP applications
$counties = $locator->getCounties('Lagos');

// With the Facade in Laravel applications
$counties = Locator::getCounties('Lagos');

var_dump($counties); // Collection of counties

One very common use is illustrated below in a Laravel project that lists all the state in the Nigeria.

<ul>
@foreach(Locator::getStates('Nigeria') as $state)
    <li> {{ $state->name }} </li>
@endforeach
</ul>

License

This project uses the MIT License feel free to contribute.