germania-kg/geodata

Interfaces and traits for geo data

3.6.0 2023-01-04 14:49 UTC

Requires

• php: ^7.4|^8.0
• guzzlehttp/guzzle: ^6.0|^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.0|^3.0
• php-coveralls/php-coveralls: ^2.0
• phpspec/prophecy-phpunit: ^2.0
• phpstan/phpstan: ^1.9
• phpunit/phpunit: ^8.0|^9.0
• spatie/phpunit-watcher: ^1.8

MIT

• Carsten Witt

README

Germania KG · GeoData

Installation

$ composer require germania-kg/geodata

Interfaces

GeoDataProviderInterface

<?php
use Germania\GeoData\GeoDataProviderInterface;

/**
 * @return null|GeoDataInterface
 */
public function getGeoData();

GeoDataInterface

<?php
use Germania\GeoData\GeoDataInterface;

/**
 * @return float|null
 */
public function getLatitude();

/**
 * @return float|null
 */
public function getLongitude();


/**
 * @return float[]
 */
public function getLatLon();

/**
 * @return string|null
 */
public function getSource();

/**
 * @return string|null
 */
public function getStatus();

Traits

GeoDataProviderTrait

The GeoDataProviderTrait provides a public geodata property as well as a getGeoData method prescribed by GeoDataProviderInterface:

<?php
use Germania\GeoData\GeoDataProviderTrait;

class MyGeoDataProvider
{
	use GeoDataProviderTrait;
}

$object = new MyGeoDataProvider;

// Property or GeoDataProviderInterface method
$object->geodata;
$object->getGeoData();

Classes

GeoDataAbstract

The GeoDataAbstract provides public latitude and longitude properties as well as the methods prescribed by GeoDataInterface:

<?php
use Germania\GeoData\GeoDataAbstract;

class MyGeoData extends GeoDataAbstract
{
	use GeoDataTrait;
}

$object = new MyGeoData;

// Properties
echo $object->latitude;
echo $object->longitude;

// GeoDataProviderInterface methods
echo $object->getLatitude();
echo $object->getLongitude();
$coords = $object->getLatLon();

GeoData

The GeoData class extends GeoDataAbstract and implements GeoDataInterface and also GeoDataProviderInterface:

<?php
use Germania\GeoData\GeoData;  

// "Null" object
$geo = new GeoData();
$coords = $object->getLatLon();    // [ null, null]
$coords = $object->getLatitude();  // null
$coords = $object->getLongitude(); // null
echo $geo->getSource(); // null

// With real data
$latitude = 54.0;
$longitude = 10.0;
$description = "provided by Google Maps";

$geo = new GeoData( $latitude, $longitude, $description);
$geo->setSource("Corrected manually");
$get->setStatus("Not too exact");

$coords = $object->getLatLon(); // [ 54.0, 10.0]
echo $geo->getSource(); // "Corrected manually"

Factories

GeoDataFactory

The GeoDataFactory class provides a fromArray method:

<?php
use Germania\GeoData\GeoDataFactory;  
use Germania\GeoData\GeoData;  

$factory = new GeoDataFactory;

// All these fields default to null
$geodata = $factory([
  'latitude'  => 54, 
  'longitude' => 10, 
  'source' => "Test case", 
  'status' => "OK"  
]);

GuzzleGeoDataFactory

The GuzzleGeoDataFactory is a client for Germania's Geocoding API. It implements StringGeoDataFactoryInterface and requires Guzzle, configured to ask Germania's GeoCoder API.

Sorry, the API is not public. You may use the Factory class to cook your own HTTP-client-based GeoData factory.

<?php
use Germania\GeoData\GuzzleGeoDataFactory;
use GuzzleHttp\Client as GuzzleClient;

$guzzle = new GuzzleClient( ... );
$factory = new GuzzleGeoDataFactory($guzzle);

$geodata = $factory->fromString("Musterstraße 1, 12345 Musterstadt");
echo get_class( $geodata ); // Germania\GeoData\GeoData

Exceptions: Just in case the Guzzle client throws an exception or the API response is invalid, watch out for these:

<?php
use Germania\GeoData\GeoDataExceptionInterface;
use Germania\GeoData\GeoDataFactoryRuntimeException;

// For 404 ClientExceptions, extends GeoDataFactoryRuntimeException
use Germania\GeoData\GeoDataFactoryNotFoundException;

Filters

NotEmptyGeoDataFilterIterator

Accepts any Traversable and filters for GeoDataInterface or GeoDataProviderInterface items whose getLatitude and getLongitude results are not empty.

Development

$ git clone https://github.com/GermaniaKG/Geodata.git
$ cd Geodata
$ composer install

Unit tests

Either copy phpunit.xml.dist to phpunit.xml and adapt to your needs, or leave as is. Run PhpUnit test or composer scripts like this:

$ composer test
# or
$ vendor/bin/phpunit