A PHP package that retrieves Uganda's districts with their respective counties, sub counties, parishes and villages in Uganda.

Overview

Uganda Geo Data

This is a PHP package that retrieves Uganda's districts with their respective counties, sub counties, parishes and villages in Uganda. This data has been scrapped off Uganda's passport's official portal.

Description

This package gives you the leverage to access all sub levels ranging from districts, counties, subcounties, parishes to villages in Uganda. You can also access the different mentioned areas independently.

Table of Contents

Requirements

In order to run this project, ensure that you have installed;

  • PHP 7.4 or later
  • Composer

Installation

This project using composer.

$ composer require kusaasira/uganda-geo

Usage

The examples below show examples of usage of the package and their resulting outputs

Retrieve Districts data.


require 'vendor/autoload.php';

use Uganda\Geo;

$geo = new Geo();

# Retrieve all districts
$all_districts = $geo->districts()->all();
echo $all_districts;

# Retrieve all counties in particular ditrict
$counties = $geo
                ->districts('Mukono')
                ->counties()->all();
echo $counties;

# Retrieve all sub counties under county in particular ditrict
$sub_counties = $geo
                ->districts('Mukono')
                ->counties('Mukono Municipality')
                ->sub_counties()->all();
echo $sub_counties;

# Retrieve all parishes in a sub county under county in particular ditrict
$parishes = $geo
                ->districts('Mukono')
                ->counties('Mukono Municipality')
                ->sub_counties('Goma Division')
                ->parishes()->all();
echo $parishes;

# Retrieve villages in a parish under a sub county under county in particular ditrict
$villages = $geo
                ->districts('Mukono')
                ->counties('Mukono Municipality')
                ->sub_counties('Goma Division')
                ->parishes('Nantabulirwa Ward')
                ->villages()->all();
echo $villages;

Retrieve Individual geo units data.

Retrieve all districts

# Query Districts

require 'vendor/autoload.php';

use Uganda\Geo;

$geo = new Geo();
$all_districts = $geo->districts()->all();
echo $all_districts;
{
  "districts": {
    "count": 135,
    "data": [
      {
        "id": "98",
        "name": "Abim"
      },
      {
        "id": "68",
        "name": "Adjumani"
      },
      {
        "id": "23",
        "name": "Agago"
      },
      ...
    ]
  }
}

Retrieve all counties in Uganda


require 'vendor/autoload.php';

use Uganda\Geo;

$geo = new Geo();
$counties = $geo->counties()->all();
echo $counties;
{
  "counties": {
    "count": 303,
    "data": [
      {
      "id": "242",
      "name": "Labwor County",
      "district": "98"
      },
      {
      "id": "166",
      "name": "Adjumani East County",
      "district": "68"
      },
      {
      "id": "165",
      "name": "Adjumani West County",
      "district": "68"
      },
      ...
    ]
  }
}

Retrieve all sub counties in Uganda


require 'vendor/autoload.php';

use Uganda\Geo;

$geo = new Geo();
$sub_counties = $geo->sub_counties()->all();
echo $sub_counties;
{
  "sub_counties": {
    "count": 2120,
    "data": [
      {
      "id": "242",
      "name": "Labwor County",
      "district": "98"
      },
      {
      "id": "166",
      "name": "Adjumani East County",
      "district": "68"
      },
      {
      "id": "165",
      "name": "Adjumani West County",
      "district": "68"
      },
      ...
    ]
  }
}

Retrieve all parishes in Uganda

require 'vendor/autoload.php';

use Uganda\Geo;

$geo = new Geo();

$parishes = $geo->parishes()->all();
echo $parishes;
{
  "parishes": {
    "count": 10365,
    "data": [
      {
      "id": "9127",
      "name": "Abongepach",
      "subcounty": "1546"
      },
      {
      "id": "9150",
      "Name": "Adwal",
      "subcounty": "1546"
      },
      {
      "id": "7279",
      "name": "Aninata",
      "subcounty": "1546"
      },
      ...
    ]
  }
}

Retrieve villages in Uganda

require 'vendor/autoload.php';

use Uganda\Geo;

$geo = new Geo();

$villages = $geo->villages()->all();
echo $villages;
{
  "villages": {
    "count": 71250,
    "data": [
      {
        "id":"57217",
        "name":"ABONGEPACH",
        "parish":"9127"
      },
      {
        "id":"58161",
        "name":"AMITA PRISON",
        "parish":"9127"
      },
      {
        "id":"58171",
        "name":"AMONICEK",
        "parish":"9127"
      },
      ...
    ]
  }
}

Credits

The data used in this package has been scrapped off This data has been scrapped off Uganda's passport's official portal as there is no updated geo data source since 2018 published anywhere.

Collaborators

timek
Timo Ek
kusaasira
Joshua Kusaasira
Marshud
Marshud

Contributors

kusaasira
Joshua Kusaasira

License

This package is free software distributed under the terms of the MIT license.

Comments
  • Fetch all subcounties in a particular district

    Fetch all subcounties in a particular district

    Create a method that fetches only sub counties from a particular parsed district.

    Follow Appblocks Standards and Guidelines.

    At the moment, one has to go through a chain to fetch subcounties i.e. see code block below.

    $geo = new Geo();
    $data = $geo
            ->districts('Mukono')
            ->counties('Mukono Municipality')
            ->sub_counties->all();
    

    Refactor this to accept fetching subcounties as indicated below;

    $geo = new Geo();
    $data = $geo
            ->districts('Mukono')
            ->sub_counties->all();
    

    For more information on the structure, checkout the repo wiki.

    Follow PSR-12 coding standards and guidelines.

    hacktoberfest 
    opened by kusaasira 3
  • Move the searching from Traits into Class based to allow for the dropping of the all() method and search functionality

    Move the searching from Traits into Class based to allow for the dropping of the all() method and search functionality

    Pull Request Description

    Change to how we are structing the data

    This Pull Request has changed the application from using Traits and using Classes, this allows us to create a tree like structure so when it comes to searching for specific locations we can go down the branches of the tree to location it as long it's lower down the tree. Tree Data Structure

    Reading of the JSON files

    When it comes to getting the information this is done when creating the Uganda object for the first time and we store the information in memory. This allows us to access the information quickly since we won't be required to do multiple reads every time we want to access the information.

    Since we aren't changing the state of the tree structure we are just creating copies of branches that we want. We only need to read the file when we create the object for the first time and we won't have to worry about the information since the Objects are immutable.

    Testing

    Since now we have Classes instead of Traits we can now test each section without the need to call the JSON data since they are just newly created objects with fake data.

    PHPStan

    Previously we was unable to go above PHPStan Level 1 when it came to static analyzing with the new changes we can now support Level 9. PHPStan Level

    The Ability to get specific types of location data from any level

    When doing the refactor I saw the issue of #4 and made it possible to access all of the information for each branch of the data.

    So for the issue ticket we are now able to complete this by doing the following $uganda->district('Bugweri')->subCounties(); This will return you an array of SubCounty objects that are from the District object of Bugweri.

    The dropping of the all()

    Previously all methods had to end with all() to get the information. Using this new approach we are getting the information from methods that are self descriptive.

    Type (Feature, Fix, Config, etc)

    • [X] Bug fix 🐞
      • Resolving the Issue #4
      • Resolving the Issue #6
    • [X] New feature ✨
      • The ability to access all Geographical information for every specific type of Geographical location
    • [X] Breaking change 🔩
      • Removal of the Geo class and now called Uganda
    • [X] This change requires a documentation update 📙
      • All of the new ways of accessing the information has been added to the README.md
    • [X] Improvement 🌠
    • [X] Refactor 🔄
    • [X] Add Test Specs 🚦
      • All new tests have been added to cover the new classes

    Tests

    Tests have been written to match the new flow of the package

    Tests configurations and running:

    • PHP Unit
    vendor/bin/phpunit
    

    Checklist:

    • [X] My code follows the style guidelines of this project
    • [X] I have performed a self-review of my own code
    • [X] I have commented my code, particularly in hard-to-understand areas
    • [X] I have made corresponding changes to the documentation
    • [X] My changes generate no new warnings
    • [X] I have added tests that prove my fix is effective or that my feature works
    • [X] New and existing unit tests pass locally with my changes
    hacktoberfest hacktoberfest-accepted 
    opened by RoadSigns 2
  • Introducing Github Actions to ensure that pull requests are breaking features

    Introducing Github Actions to ensure that pull requests are breaking features

    Pull Request Description

    This pull request is to allow users to control the dependencies themselves when using the package. Leaving a composer.lock with outdated dependencies can introduce vulnerabilities into peoples applications but having a soft cap via composer.json allows Developers to be in control of their own packages.

    Linting has been added to package to allow the support of PSR-12 (https://www.php-fig.org/psr/psr-12/) This is a coding standard that is used by Symfony, Laravel and also WordPress. This also sets a standard that other developers are use too, so it can increase the possibility of additional contributors.

    Added the PHPUnit tests to the pipeline, this will ensure that no new pull requests will be breaking the unit tests, so all new versions of the package will have a working version.

    Type (Feature, Fix, Config, etc)

    • [ ] Bug fix 🐞
    • [ ] New feature ✨
    • [ ] Breaking change 🔩
    • [ ] This change requires a documentation update 📙
    • [X] Improvement 🌠
    • [X] Refactor 🔄
    • [ ] Add Test Specs 🚦

    Tests configurations and running:

    • PHP Unit
    ./vendor/bin/phpunit
    
    • Easy Coding Standard Test
    ./vendor/bin/ecs check src
    
    ./vendor/bin/ecs check src --fix
    

    Checklist:

    • [X] My code follows the style guidelines of this project
    • [X] I have performed a self-review of my own code
    • [ ] I have commented my code, particularly in hard-to-understand areas
    • [X] I have made corresponding changes to the documentation
    • [ ] My changes generate no new warnings
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [X] New and existing unit tests pass locally with my changes
    hacktoberfest hacktoberfest-accepted 
    opened by RoadSigns 2
  • Remove chaining dependability on the all method.

    Remove chaining dependability on the all method.

    Currently all requests end methods end with the all() method. This is decoupling the code. Refactor this to increase maintainability and reduce dependability on the all() method.

    Follow PSR-12 coding standards and guidelines.

    hacktoberfest 
    opened by kusaasira 0
  • Code Refactor

    Code Refactor

    Code Refactor

    This PR aims to do something (detailed description).

    Type (Feature, Fix, Config, etc)

    • [ ] Bug fix 🐞
    • [ ] New feature ✨
    • [ ] Breaking change 🔩
    • [ ] This change requires a documentation update 📙
    • [ ] Improvement 🌠
    • [x] Refactor 🔄
    • [ ] Add Test Specs 🚦

    Tests

    Tests description

    • [x] Fetching Districts.
    • [x] Fetching counties in under a district.
    • [x] Fetching sub-counties in under a district->county.
    • [x] Fetching parishes in under a district->countty->subcounty.
    • [x] Fetching parishes in under a district->countty->subcounty.
    • [x] Fetching vilages in under a district->countty->subcounty->parish.

    Tests configurations and running:

    • PHP Unit
    vendor/bin/phpunit
    

    Checklist:

    • [x] My code follows the style guidelines of this project
    • [x] I have performed a self-review of my own code
    • [x] I have commented my code, particularly in hard-to-understand areas
    • [x] I have made corresponding changes to the documentation
    • [x] My changes generate no new warnings
    • [ ] I have added tests that prove my fix is effective or that my feature works
    • [x] New and existing unit tests pass locally with my changes
    hacktoberfest hacktoberfest-accepted 
    opened by kusaasira 0
  • Adding Laravel Package support to the Library

    Adding Laravel Package support to the Library

    Since a lot of applications are built using Laravel these days, do we want to look into adding support for Laravel in this package. That way people can just start using the Ugandan geo information within their applications.

    This is just the start of a discussion post around what would be required if we wanted to support this going forward?

    Information regarding packages within Laravel: https://laravel.com/docs/9.x/packages

    opened by RoadSigns 0
  • Look into dropping support for PHP 7.4

    Look into dropping support for PHP 7.4

    Since PHP 7.4 will no longer get any security updates. Do we want to look into dropping support for this and only allowing the package to be used on PHP 8.0?

    Obviously this package can still be downloaded using the older tags but all new tags move across to a newer version of PHP?

    opened by RoadSigns 1
Owner
Joshua Kusaasira
Fullstack Software Engineer (PHP | Javascript | Python)
Joshua Kusaasira
GitScrum is a Project Management Tool, developed to help entrepreneurs, freelancers, managers, and teams Skyrocket their Productivity with the Agile methodology and Gamification.

GitScrum is a Project Management Tool, developed to help entrepreneurs, freelancers, managers, and teams Skyrocket their Productivity with the Agile methodology and Gamification.

GitScrum 2.8k Jan 6, 2023
Server manager is a open source project made for people so that they can add the servers to one single place irrespective of their provider and manage it through one location.

Server Manager Are you sick of having to log into hundreads of different website just to access your server? Well we got you, Server manager is a open

null 8 Aug 9, 2022
AdoteUm.Dev has the proposal to connect people who are looking for developers for their projects

AdoteUm.Dev has the proposal to connect people who are looking for developers for their projects. AdoteUmDev is a web application, developed in PHP language and the Laravel Framework.

Beer And Code 101 Oct 19, 2022
ControlPanel's Dashboard is a dashboard application designed to offer clients a management tool to manage their pterodactyl servers.

Features PayPal Integration Email Verification Audit Log Admin Dashboard User/Server Management Store (credit system) Vouchers and so much more! Contr

ControlPanel.gg 223 Jan 5, 2023
Livewire component to show records according to their current status

Livewire Status Board Livewire component to show records/data according to their current status Preview Installation You can install the package via c

Andrés Santibáñez 288 Dec 24, 2022
A slim, lean forum package designed for quick and easy integration in Laravel projects

Complete documentation is available on teamteatime.net. Installation Requires Laravel 6+ and PHP 7.4+. Step 1: Install the package Install the package

TeamTeaTime 486 Dec 31, 2022
Dynamic photo package for blog posts and other features, integrating CKEditor Smart WYSIWYG

Dynamic Photo Dynamic Photo is a package to assist in integration with CKEditor, a powerful WYSIWYG. With the package it is possible to send photos dy

Michael Frank 7 Jul 18, 2022
Simple PHP package to get any Facebook Page posts

Get Facebook Page Feed It is simple wrapper class written in php to fetch posts from certain Facebook page. Currently I am using Facebook graph API wi

Mohd Hafiz 61 Dec 14, 2022
Dolibarr ERP & CRM is a modern software package that helps manage your organization's activity (contacts, suppliers, invoices, orders, stocks, agenda…).

Dolibarr ERP CRM is a modern software package to manage your company or foundation activity (contacts, suppliers, invoices, orders, stocks, agenda, accounting, ...). It is open source software written in PHP and designed for small and medium businesses, foundations and freelancers. You can freely install, use and distribute it as a standalone application or as a web application to use it from every internet access and media.

Dolibarr ERP & CRM 3.7k Jan 7, 2023
Improved File Manager package for YunoHost

IFM for YunoHost Lire ce readme en français. This package allows you to install IFM quickly and simply on a YunoHost server. If you don't have YunoHos

null 4 Nov 12, 2022
A simple blog package for Laravel 4

Laravel Blog A Laravel 4 package to add a simple blog to a site Features Paginated index view with configurable results per page Year/Month archive fi

Five by Five 74 Apr 12, 2020
Personal Knowledge Management. Use branch "minimal change" to deploy as laravel package.

Knowfox Knowfox is my Personal Knowledge Management system. Having been an keen Evernote user since 2012, I finally got around to taking my precious n

null 180 Dec 28, 2022
Package to get a free id (for example: in XML)

Get Free ID Description Package to get a free id (for example: in XML) Requirements PHP >= 7.3 Installation composer require vitkuz573/get-free-id Usa

Vitaly Kuzyaev 0 Dec 19, 2022
Laravelium Feed package for Laravel.

Laravelium Feed package Laravelium Feed package for Laravel. Notes Dev branches are for development and are UNSTABLE (use on your own risk)! Installat

Laravelium 362 Nov 27, 2022
A Laravel package that can be used for fetching favicons from websites

A Laravel package that can be used for fetching favicons from websites.

Ash Allen 103 Jan 2, 2023
A free and open-source accounting and production system for businesses and non-profits with support for multiple users and varied integrations

A free and open-source accounting and production system for businesses and non-profits with support for multiple users and varied integrations.

null 3 Sep 22, 2022
Created simple login system and chat type website using mysql database along with php and html , css and javascript.

Created simple login system and chat type website using mysql database along with php and html , css and javascript.

null 1 Jan 6, 2022
Emoncms is an open-source web application for processing, logging and visualising energy, temperature and other environmental data and is part of the OpenEnergyMonitor project.

Emoncms is an open-source web application for processing, logging and visualising energy, temperature and other environmental data and is part of the OpenEnergyMonitor project.

Emoncms 1.1k Dec 22, 2022
This prj we have two NODEMCU ( ESP8266) and two RFID_RC522 and some rfid tags we used ARDUINO IDE on NODEMCU and running server with XAMPP

This prj we have two NODEMCU ( ESP8266) and two RFID_RC522 and some rfid tags we used ARDUINO IDE on NODEMCU and running server with XAMPP

Mohammadamir Soltanzadeh 2 Mar 29, 2022