README

PHP 8.3 Composer package for downloading GeoNames dump files, parsing them with memory-safe generators, and producing a top-down geozone stream that can populate a database table from world/continent level down to locality/city level.

The package is intentionally DB-agnostic. It does not require Laminas, Doctrine, Laravel, or a specific persistence layer. Applications receive normalized GeozoneRecord objects and decide how to insert or update them.

Installation

composer require edns-andrew/geozone-importer

Quick start

<?php

use EdnsAndrew\GeozoneImporter\Download\DownloadProfile;
use EdnsAndrew\GeozoneImporter\GeoNamesImporter;
use EdnsAndrew\GeozoneImporter\Model\PersistedGeozone;

$importer = GeoNamesImporter::createDefault();

$snapshot = $importer->downloadLatest(
    profile: DownloadProfile::worldCities1000(),
    cacheDir: __DIR__ . '/var/geonames'
);

$persistedByCode = [];

foreach ($importer->topDownGeozones($snapshot) as $record) {
    $parent = null;

    if ($record->parentGeozoneCode !== null) {
        $parent = $persistedByCode[$record->parentGeozoneCode]
            ?? $repository->findByGeozoneCode($record->parentGeozoneCode);
    }

    $id = $repository->upsertAndReturnIdByGeozoneCode([
        'parentID' => $parent?->id,
        'parentGeozoneCode' => $record->parentGeozoneCode,
        'regionType' => $record->regionType->value,
        'sourceLevel' => $record->sourceLevel->value,
        'geozoneCode' => $record->geozoneCode,
        'source' => $record->source,
        'sourceID' => $record->sourceID,
        'geozoneName' => $record->geozoneName,
        'descriptiveName' => $record->descriptiveName,
        'countryCode' => $record->countryCode,
        'admin1Code' => $record->admin1Code,
        'admin2Code' => $record->admin2Code,
        'admin3Code' => $record->admin3Code,
        'admin4Code' => $record->admin4Code,
        'latitude' => $record->latitude,
        'longitude' => $record->longitude,
        'population' => $record->population,
        'timezone' => $record->timezone,
        'weight' => $record->weight,
        'active' => $record->active ? 1 : 0,
        'sourceModifiedDate' => $record->sourceModifiedDate?->format('Y-m-d'),
        'importBatchCode' => $record->importBatchCode,
        'lastModified' => time(),
    ]);

    $persistedByCode[$record->geozoneCode] = new PersistedGeozone(
        id: $id,
        geozoneCode: $record->geozoneCode
    );
}

Optional console helpers

vendor/bin/geozone geonames:download --profile=world-cities1000 --cache-dir=var/geonames
vendor/bin/geozone geonames:stream --profile=world-cities1000 --cache-dir=var/geonames
vendor/bin/geozone geonames:inspect --cache-dir=var/geonames

The console commands are convenience tools. The primary integration path is the PHP API.

MariaDB table documentation

A recommended MariaDB table definition is included in:

docs/database/mariadb-geozone.sql

It contains:

1. CREATE TABLE IF NOT EXISTS geozone for new installations.
2. ALTER TABLE geozone migration SQL for projects that already have the original table.
3. Indexes for parent lookups, source lookups, administrative filtering, locality search, and import batch auditing.

Download profiles

DownloadProfile::worldCities1000();
DownloadProfile::worldCities5000();
DownloadProfile::worldCities15000();
DownloadProfile::country('CA');
DownloadProfile::countries(['CA', 'US']);
DownloadProfile::fullWorld();

Source identity strategy

Importer-generated geozoneCode values are stable external keys:

geonames:6167865
m49:region:019

Use your local table's auto-increment id only for local parent references such as parentID.

Publishing to GitHub and Packagist

This repository is Packagist-ready because it has a root composer.json with a valid package name, library type, license, autoload configuration, and optional binary entry. Composer documents name, type, license, require, and PSR-4 autoload fields as root package properties in composer.json.

git init
git add .
git commit -m "Initial geozone importer package"
git branch -M main
git remote add origin git@github.com:edns-andrew/geozone-importer.git
git push -u origin main

Then submit the public GitHub repository URL to Packagist.

License

MIT. See LICENSE.