gp10devhts/ug-village-locations

village locations package for uganda

v1.0.4 2026-05-29 06:31 UTC

Requires

• php: ^8.3|^8.4
• illuminate/contracts: ^11.0||^12.0||^13.0
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.0.0||^10.0.0||^9.0.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Ahairwe Jordan

• laravel
• gp10devhts
• ug-village-locations

README

A production-ready Laravel package that provides Uganda administrative locations from District → County → Sub County → Parish → Village.

Features

• Full administrative hierarchy: Districts, Counties, Sub-Counties, Parishes, and Villages.
• Fast seeding via SQL dumps (offline support).
• Configurable hierarchy depth.
• Eloquent models and relationships.
• Name-based searching scopes.
• Maintainer tools for data collection from remote sources.
• Optional UUID support.

Installation

You can install the package via composer:

composer require gp10devhts/ug-village-locations

Publish the config and migrations:

php artisan vendor:publish --tag="ug-village-locations-config"
php artisan vendor:publish --tag="ug-village-locations-migrations"

Run the migrations:

php artisan migrate

Seed the locations:

php artisan ug-locations:seed

Configuration

You can customize the package via config/ug-village-locations.php:

return [
    'seed_levels' => [
        'districts',
        'counties',
        'sub_counties',
        'parishes',
        'villages',
    ],
    'use_uuids' => false,

    'models' => [
        'district' => \Gp10devhts\UgVillageLocations\Models\District::class,
        'county' => \Gp10devhts\UgVillageLocations\Models\County::class,
        'sub_county' => \Gp10devhts\UgVillageLocations\Models\SubCounty::class,
        'parish' => \Gp10devhts\UgVillageLocations\Models\Parish::class,
        'village' => \Gp10devhts\UgVillageLocations\Models\Village::class,
    ],
];

Usage

Eloquent Models

use Gp10devhts\UgVillageLocations\Models\District;
use Gp10devhts\UgVillageLocations\Models\Village;

// Get all districts
$districts = District::all();

// Search by name
$kampala = District::search('Kampala')->first();

// Relationships
$counties = $kampala->counties;
$villages = Village::where('name', 'like', '%Kibuli%')->with('parish.subCounty.county.district')->get();

// Using the Facade for model resolution and helper methods
use Gp10devhts\UgVillageLocations\Facades\UgVillageLocations;

$districtModel = UgVillageLocations::districtModel();
$districts = UgVillageLocations::districts();
$counties = UgVillageLocations::counties($districtId);

Demo Project

A demo Laravel project is available at github.com/GP10DevHTS/ug-locations-demo.

Notices:

• the project uses a custom District model to add regions.
• the model extention migrations use the default table names from the package.

Model Extensibility

You can override the default models by updating the models array in the config file. This allows you to add custom relationships, scopes, or traits.

// config/ug-village-locations.php
'models' => [
    'village' => App\Models\Village::class,
],

Your custom model should extend the package's base model:

namespace App\Models;

use Gp10devhts\UgVillageLocations\Models\Village as BaseVillage;

class Village extends BaseVillage
{
    // Custom logic
}

Artisan Commands

• php artisan ug-locations:seed: Seed the database from local SQL dumps.
• php artisan ug-locations:truncate: Wipe all administrative location data.
• php artisan ug-locations:fetch: (Maintainer only) Fetch fresh data from remote source.
• php artisan ug-locations:build-dump: (Maintainer only) Generate SQL dumps from fetched data.

Testing

composer test

License

The MIT License (MIT). Please see License File for more information.