README

Currently the work in progress. It will receive updates with possible breaking changes. Not recommended using in production environments yet.

The package allows integrating geonames database with a Laravel application.

🗒️ Description

This package is a fork of nevadskiy/laravel-geonames.

The package is very useful for applications that rely on the geo data.

By default, the package provides 5 tables: continents, countries, divisions, cities and translations and fills them with data from the geonames service.

It also allows to keep the data up-to-date, so the package fetches all daily modifications provided by the geonames service and use them to synchronize your own database.

You can also set up the package to seed only data that belongs to specific countries, disable unneeded tables, set up minimal population filter and use your own custom models.

Translations are powered by the imcity-tech/laravel-translatable.

🔌 Installation

composer require imcity-tech/laravel-geonames

✅ Requirements

Laravel 9.0 or newer
PHP 8.0 or newer

🔨 Usage

Default structure and behaviour

Migrate the database

php artisan migrate

Run insert process

php artisan geonames:insert

It will insert download and insert the geonames dataset into your database.

Note that the insert process may take some time. On average, it is about 15 minutes (without downloading time).

Schedule updates

Add the following code to your console kernel (app/Console/Kernel.php) if you want to receive geonames daily updates.

protected function schedule(Schedule $schedule)
{
    $schedule->command('geonames:update')->dailyAt('4:00');
}

Note, that time is specified for the UTC timezone, so if you run server on another timezone, you need to convert time according to it.

Configure custom structure

If you want to configure package according to your needs, you need to publish the package configuration first.

php artisan vendor:publish --tag=geonames-config

Specifying source

You can choose appropriate data source for seeding as one of SOURCE_ALL_COUNTRIES, SOURCE_SINGLE_COUNTRY or SOURCE_ONLY_CITIES.

The default is SOURCE_ALL_COUNTRIES that indicates to fetch data from the allCountries.zip file. It contains all 4 models (continents, countries, divisions and cities). You can configure filters in the geonames configuration file to specify countries that is going to be seeded and minimal population.

The SOURCE_SINGLE_COUNTRY source is used to fetch data from country-based files (e.g. US.zip). The continents table will not be seeded with this source. You can specify which country (or countries) you are going to seed specifying countries filter in the geonames configuration file.

The SOURCE_ONLY_CITIES source is used to fetch data from city-based files (e.g. cities500.zip). There is only cities table available with this source type. You can specify minimal population filter to indicate which file it is going to fetch by population. It is also possible to use countries filter to seed cities that belongs only to specific countries.

Specifying filters

By default, there are two filters which you can use to filter data being seeded.

Countries filter

The countries filter is used to filter data that belongs only to specific country (or countries). If the SOURCE_SINGLE_COUNTRY source is specified, this filter will be used to download a country-based data source. The default is * that indicates that all countries are allowed. Multiple countries can be specified as an array of ISO country codes.

Example:

'filters' => [
    'countries' => ['AU', 'US']
]

Population filter

The population filter is used to filter cities by the indicated minimal population. If the SOURCE_ONLY_CITIES source is specified, this filter will be used to download a city-based data source. Any value from 0 and higher has be used, but in combination with the SOURCE_ONLY_CITIES source, available values are only 500, 1000, 5000 and 15000.

Example:

'filters' => [
    'population' => 15000
]

Overriding models

Most likely you will need your own models with their own behaviour and relations instead of provided ones by default.

To override them, use models key in the geonames configuration file.

If you are not going to use any model, you can switch the value to false and then corresponding tables will not be migrated at all.

For example, most applications probably will not need continent model.

'models' => [
    'continent' => false,
    'country' => App\Models\Country::class,
    'division' => App\Models\Division::class,
    'city' => App\Models\City::class,
],

Overriding migrations

To rename tables or remove unnecessary fields, you can publish migrations and edit them before execution migrations command.

To publish default migrations, use the following command:

php artisan vendor:publish --tag=geonames-migrations

Then disable default migrations from being migrated, setting default_migrations to false in the geonames configuration file.

'default_migrations' => false

Inserting custom structure

After configuring source and filters, you can execute migrations command. It will determine which tables should be migrated and create them in the database.

php artisan migrate

Then you can run insert command.

php artisan geonames:insert

Reinserting dataset

Sometimes you may need to delete all data and reinsert it again. To do it, pass the --reset option to geonames:insert command.

php artisan geonames:insert --reset

📑 Changelog

Please see CHANGELOG for more information what has changed recently.

☕ Contributing

Please see CONTRIBUTING for more information.

🔓 Security

If you discover any security related issues, please e-mail me instead of using the issue tracker.

📜 License

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

slivka-b / laravel-geonames

Maintainers

Details