webit / terc
Provides polish territorial entities based on GUS TERC file
Requires
- php: >=7.1
- doctrine/cache: ^1.8.0
Requires (Dev)
- ext-pdo_sqlite: *
- doctrine/orm: ^2.6.0
- phpunit/phpunit: ^7.3.2
Suggests
- doctrine/orm: For Doctrine ORM infrastructure support.
This package is auto-updated.
Last update: 2024-10-24 08:12:26 UTC
README
Provides polish territorial entities based on GUS TERC file (http://eteryt.stat.gov.pl) Please note, this repository contains JUST sample data. Obtain real data from official GUS website.
Installation
Install via composer
composer require webit/terc
Usage
Voivodeship
VoivodeshipRepository
provides access to Voivodeship
objects representing voivodeships in Poland (pol. "województwo").
<?php use Webit\Terc\VoivodeshipRepository; use Webit\Terc\Voivodeship; use Webit\Terc\VoivodeshipCode; // check how to obtain an instance of repository in the Infrastructure section of this README.md /** @var VoivodeshipRepository $repository */ /** @var Voivodeship $voivodeship */ $voivodeship = $repository->get(new VoivodeshipCode('02')); // returns `Voivodeship` echo $voivodeship->code() . "\n"; // shows `VoivodeshipCode` object echo $voivodeship->name() . "\n"; // shows voivodeship's name echo (string)$voivodeship . "\n"; // returns voivodeship's name $voivodeship = $repository->getByName('dolnośląskie'); // returns `Voivodeship` // getting all the voivodeships foreach ($repository->getAll() as $province) { // do something }
District
DistrictRepository
provides access to District
objects representing districts in Poland (pol. "powiat").
<?php use Webit\Terc\DistrictCode; use Webit\Terc\DistrictRepository; use Webit\Terc\District; use Webit\Terc\VoivodeshipCode; // check how to obtain an instance of repository in the Infrastructure section of this README.md /** @var DistrictRepository $repository */ /** @var District $district */ $district = $repository->get(new DistrictCode('02')); echo $district->code() . "\n"; // shows `DistrictCode` object (4 digits code) echo $district->name() . "\n"; // shows district name echo $district->type() . "\n"; // shows district type echo $district->code()->voivodeshipCode() . "\n"; // shows `VoivodeshipCode` echo $district->code()->districtCode() . "\n"; // shows two digits district code echo (string)$district . "\n"; // returns districts name echo $repository->getByVoivodeshipAndName(new VoivodeshipCode('02'), 'dzierżoniowski'); // returns districts's name // getting all the districts $limitOffset = \Webit\Terc\LimitOffset::create(250, 0); // optional, 100, 0 by default foreach ($repository->getAll($limitOffset) as $district) { // do something } // getting all the districts of given voivodeship foreach ($repository->getAllOfVoivodeship(new VoivodeshipCode('02')) as $district) { // do something }
Borough
BoroughRepository
provides access to Borough
objects representing boroughs in Poland (pol. "gmina").
<?php use Webit\Terc\DistrictCode; use Webit\Terc\BoroughCode; use Webit\Terc\BoroughRepository; use Webit\Terc\Borough; use Webit\Terc\VoivodeshipCode; // check how to obtain an instance of repository in the Infrastructure section of this README.md /** @var BoroughRepository $repository */ /** @var Borough $borough */ $borough = $repository->get(new BoroughCode('0201011')); echo $borough->code() . "\n"; // shows `BoroughCode` object (7 digits code) echo $borough->name() . "\n"; // shows borough name echo $borough->code()->voivodeshipCode() . "\n"; // shows `VoivodeshipCode` object echo $borough->code()->districtCode() . "\n"; // shows `DistrictCode` object echo $borough->code()->boroughCode() . "\n"; // shows two digits borough code echo $borough->code()->boroughType() . "\n"; // shows `BoroughType` object echo (string)$borough . "\n"; // returns districts's name $boroughs = $repository->getByDistrictAndName(new DistrictCode('0201'), 'Boleslawiec'); // returns `BoroughCollection` // getting all the boroughs $limitOffset = \Webit\Terc\LimitOffset::create(250, 0); // optional, 100, 0 by default foreach ($repository->getAll($limitOffset) as $borough) { // do something } // getting all the boroughs of given voivodeship $limitOffset = \Webit\Terc\LimitOffset::create(250, 0); // optional, 100, 0 by default foreach ($repository->getAllOfVoivodeship(new VoivodeshipCode('02'), $limitOffset) as $boroughs) { // do something } // getting all the boroughs of given district foreach ($repository->getAllOfDistrict(new DistrictCode('0201')) as $boroughs) { // do something }
Infrastructure
The library provides two infrastructure implementations:
InMemory
- keeps all the entities in memoryDoctrine
- based on Doctrine ORM
InMemory Infrastructure
Voivodeship
<?php use Webit\Terc\Infrastructure\InMemory\VoivodeshipRepositoryBuilder; use Webit\Terc\Infrastructure\TercFile; $builder = VoivodeshipRepositoryBuilder::create(); $builder->setLazy(false); // if you want initialise repository on build, true by default $builder->fromFile(TercFile::create('my_TERC_filename.csv')); // if you want to provide own TERC.csv file (using build-in be default) $builder->setCacheDir('/cache/dir'); // sets cache to FilesystemCache of Doctrine with a given directory $builder->setCache(new \Doctrine\Common\Cache\ArrayCache()); // sets preconfigured cache $voivodeshipRepository = $builder->build();
District
<?php use Webit\Terc\Infrastructure\InMemory\DistrictRepositoryBuilder; use Webit\Terc\Infrastructure\TercFile; $builder = DistrictRepositoryBuilder::create(); $builder->setLazy(false); // if you want initialise repository on build, true by default $builder->fromFile(TercFile::create('my_TERC_filename.csv')); // if you want to provide own TERC.csv file (using build-in be default) $builder->setCacheDir('/cache/dir'); // sets cache to FilesystemCache of Doctrine with a given directory $builder->setCache(new \Doctrine\Common\Cache\ArrayCache()); // sets preconfigured cache $districtRepository = $builder->build();
Borough
<?php use Webit\Terc\Infrastructure\InMemory\BoroughRepositoryBuilder; use Webit\Terc\Infrastructure\TercFile; $builder = BoroughRepositoryBuilder::create(); $builder->setLazy(false); // if you want initialise repository on build, true by default $builder->fromFile(TercFile::create('my_TERC_filename.csv')); // if you want to provide own TERC.csv file (using build-in be default) $builder->setCacheDir('/cache/dir'); // sets cache to FilesystemCache of Doctrine with a given directory $builder->setCache(new \Doctrine\Common\Cache\ArrayCache()); // sets preconfigured cache $boroughRepository = $builder->build();
Updating TERC entities with a new file
If InMemory
repositories are using cache, you should use TercEntitiesInMemoryUpdater
in order to replace
current entities with ones from a new file.
<?php use Webit\Terc\Infrastructure\InMemory\TercEntitiesInMemoryUpdater; use Webit\Terc\Infrastructure\TercEntityFromCsvLoader; use Webit\Terc\Infrastructure\TercFile; use Doctrine\Common\Cache\FilesystemCache; $tercEntityLoader = new TercEntityFromCsvLoader( TercFile::create('new_TERC_file.csv'), $cache = new FilesystemCache('/cache/dir') // or any other used ); $updater = new TercEntitiesInMemoryUpdater( $tercEntityLoader, $cache ); $updater->update();
Doctrine ORM Infrastructure
In order to use Doctrine Infrastructure you need to configure EntityManager
and update database schema
<?php use Doctrine\ORM\Configuration; use Doctrine\ORM\EntityManager; use Webit\Terc\Infrastructure\Doctrine\Mapping\Mapping; use Doctrine\DBAL\DriverManager; $configuration = new Configuration(); $configuration->setMetadataDriverImpl(Mapping::createDriver()); $configuration->setProxyDir(sys_get_temp_dir().substr(md5(time().mt_rand(0, 100000)), 0, 6)); $configuration->setProxyNamespace('DoctrineProxy\\'); $entityManager = EntityManager::create( DriverManager::getConnection(['url' => 'sqlite:///:memory:']), $configuration );
Voivodeship
<?php use Webit\Terc\Infrastructure\Doctrine\Voivodeship; /** @var Doctrine\ORM\EntityManager $entityManager */ $voivodeshipRepository = $entityManager->getRepository(Voivodeship::class);
District
<?php use Webit\Terc\Infrastructure\Doctrine\District; /** @var Doctrine\ORM\EntityManager $entityManager */ $districtRepository = $entityManager->getRepository(District::class);
Borough
<?php use Webit\Terc\Infrastructure\Doctrine\Borough; /** @var Doctrine\ORM\EntityManager $entityManager */ $boroughRepository = $entityManager->getRepository(Borough::class);
Updating TERC entities with a new file
<?php use Webit\Terc\Infrastructure\Doctrine\TercEntitiesDoctrineUpdater; use Webit\Terc\Infrastructure\TercEntityFromCsvLoader; use Webit\Terc\Infrastructure\TercFile; /** @var Doctrine\ORM\EntityManager $entityManager */ $updater = new TercEntitiesDoctrineUpdater( $entityManager, new TercEntityFromCsvLoader( TercFile::create('new_TERC_file.csv') ) ); $updater->update();
Tests
docker-compose run --rm composer docker-compose run --rm phpunit