data-values / geo
Geographical value objects, parsers and formatters
Fund package maintenance!
JeroenDeDauw
Installs: 534 973
Dependents: 21
Suggesters: 2
Security: 0
Stars: 16
Watchers: 13
Forks: 10
Open Issues: 3
Requires
- php: >=7.3
- data-values/data-values: ^3.0|^2.0|^1.0|~0.1
- data-values/interfaces: ^1.0.0|^0.2.0
- symfony/polyfill-php80: ^1.18.1
Requires (Dev)
- maglnet/composer-require-checker: ^3.0|^2.0
- mediawiki/mediawiki-codesniffer: ^34 || ^35 || ^36 || ^38
- ockcyp/covers-validator: ^1.3.3
- phpmd/phpmd: ^2.9.1
- phpstan/phpstan: ^0.12.68 || ^1.0.0
- phpunit/phpunit: ^9.4.1
- vimeo/psalm: ^4.4.1
This package is auto-updated.
Last update: 2024-09-14 19:58:38 UTC
README
Small library for parsing, formatting and representing coordinates. This library supports multiple coordinate formats, it is well tested, and it is used by the software behind Wikipedia and Wikidata.
On Packagist:
Usage
To parse a string to a LatLongValue
object you use one of the coordinate parsers.
$parser = new LatLongParser(); $latLongValue = $parser->parse('55.7557860 N, 37.6176330 W'); var_dump($latLongValue->getLongitude()); // float: -37.6176330
These parsers are provided:
LatLongParser
- Facade for format specific parsers. In most cases you will be using this oneDdCoordinateParser
- Parses decimal degree coordinatesDmCoordinateParser
- Parses decimal minute coordinatesDmsCoordinateParser
- Parses degree minute second coordinatesFloatCoordinateParser
- Parses float coordinatesGlobeCoordinateParser
- Parses coordinates intoGlobeCoordinateValue
objects
To turn a coordinate object into a string you use one of the coordinate formatters.
$formatter = new LatLongFormatter(); $coordinateString = $formatter->format(new LatLongValue(42.23, 13.37));
These formatters are provided:
LatLongFormatter
- Formats aLatLongValue
into any of the supported formatsGlobeCoordinateFormatter
- Formats aGlobeCoordinateValue
To represent a set of coordinates you use one of the Value Objects.
LatLongValue
has a float latitude and longitude. GlobeCoordinateValue
wraps LatLongValue
and adds a precision and a globe identifier.
The supported coordinate formats are:
- Degree minute second (
55° 45' 20.8296", -37° 37' 3.4788"
or55° 45' 20.8296" N, 37° 37' 3.4788" W
) - Decimal minute (
55° 30', -37° 30'
or55° 30' N, 37° 30' W
) - Decimal degree (
55.7557860°, -37.6176330°
or55.7557860° N, 37.6176330° W
) - Float (
55.7557860, -37.6176330
or55.7557860 N, 37.6176330 W
)
The parsers and formatters allow you to customize the used symbols for degrees, minutes and seconds and to change the letters used to indicate direction (N, E, S, W).
Requirements
Geo 4.x: PHP 7.1 or later (tested with PHP 7.1 up to PHP 7.4)
Geo 3.x: PHP 5.5 or later (tested with PHP 5.5 up to PHP 7.4 and HHVM)
Installation
To add this package as a local, per-project dependency to your project, simply add a
dependency on data-values/geo
to your project's composer.json
file.
Here is a minimal example of a composer.json
file that just defines a dependency on
version 4.x of this package:
{ "require": { "data-values/geo": "^4.0.0" } }
Running the tests
For tests only
composer test
For style checks only
composer cs
For a full CI run
composer ci
Authors
DataValues Geo is based upon and contains a lot of code written by Jeroen De Dauw for the Maps and Semantic MediaWiki projects.
Significant contributions where made by the Wikidata team, as Wikimedia Germany employees for the Wikidata project.
Release notes
4.4.0 (2022-10-21)
- Implemented
__serialize
and__unserialize
inLatLongValue
andGlobeCoordinateValue
, improving compatibility with PHP 8.1 - Added
LatLongValue::getSerializationForHash
; classes that use the PHP serialization of aLatLongValue
for a hash should instead call this method
4.3.0 (2021-04-21)
- Raised minimum PHP version from 7.1 to 7.3
4.2.3 (2021-04-23)
GlobeCoordinateValue::newFromArray
now supports numeric strings (thanks @Silvan-WMDE)
4.2.2 (2021-01-20)
- Added compatibility with
data-values/data-values
3.x - Added compatibility with
data-values/interfaces
1.x
4.2.1 (2019-12-18)
- Fixed
GlobeCoordinateParser
not being able to parse multiple values (4.2.0 regression)
4.2.0 (2019-09-20)
- Added
GlobeCoordinateValue::withPrecision
4.1.0 (2018-10-29)
- Added "PHP strict types" to all files
LatLongValue
no longer extendsDataValueObject
GlobeCoordinateValue
no longer extendsDataValueObject
- Reordered methods in
LatLongValue
andGlobeCoordinateValue
for readability - Undeprecated
LatLongValue::newFromArray
- Undeprecated
GlobeCoordinateValue::newFromArray
4.0.1 (2018-08-10)
- Fixed parsing of coordinates with lowercase S/W directions
- Fixed parsing DMS coordinates that omit a single minute number
3.0.1 (2018-08-01)
- Fixed parsing of coordinates with lowercase S/W directions
2.1.2 (2018-08-01)
- Fixed parsing of coordinates with lowercase S/W directions
4.0.0 (2018-07-13)
- Updated minimum required PHP version from 5.5.9 to 7.1
- Added scalar type hints
- Added return type hints
- Added nullable type hints
- Made constant visibility explicit
- Constructing an invalid
LatLongValue
now causesInvalidArgumentException
instead ofOutOfRangeException
3.0.0 (2018-03-20)
- Removed
DATAVALUES_GEO_VERSION
constant - The parsers no longer extend
StringValueParser
- They no longer have public methods
setOptions
andgetOptions
- They no longer have protected field
options
- They no longer have protected methods
requireOption
,defaultOption
andstringParse
GlobeCoordinateParser
andLatLongParser
no longer have protected methodgetOption
- They no longer have public methods
- Made several protected fields and methods private
- All fields of
LatLongValue
- The
detect…Precision
methods inGlobeCoordinateParser
LatLongParser::getParsers
- All fields of
- Removed public static method
LatLongParser::areCoordinates
- Dropped dependence on the DataValues Common library
- Removed long deprecated class aliases
DataValues\GlobeCoordinateValue
(now inDataValues\Geo\Values
)DataValues\LatLongValue
(now inDataValues\Geo\Values
)DataValues\Geo\Formatters\GeoCoordinateFormatter
(nowLatLongFormatter
)DataValues\Geo\Parsers\GeoCoordinateParser
(nowLatLongParser
)
2.1.1 (2017-08-09)
- Allow use with ~0.4.0 of DataValues/Common
2.1.0 (2017-08-09)
- Remove MediaWiki integration
- Make use of the …::class feature
- Add .gitattributes to exclude not needed files from git exports
- Use Wikibase CodeSniffer instead of Mediawiki's
- Move to short array syntax
2.0.1 (2017-06-26)
- Fixed
GlobeCoordinateValue::newFromArray
andLatLongValue::newFromArray
not accepting mixed values. - Deprecated
GlobeCoordinateValue::newFromArray
andLatLongValue::newFromArray
. - Updated minimum required PHP version from 5.3 to 5.5.9.
2.0.0 (2017-05-09)
GlobeCoordinateValue
does not accept empty strings as globes any more.GlobeCoordinateValue
does not accept precisions outside the [-360..+360] interval any more.- Changed hash calculation of
GlobeCoordinateValue
in an incompatible way. - Renamed
GeoCoordinateFormatter
toLatLongFormatter
, leaving a deprecated alias. - Renamed
GeoCoordinateParser
toLatLongParser
, leaving a deprecated alias. - Renamed
GeoCoordinateParserBase
toLatLongParserBase
. - Deprecated
LatLongParser::areCoordinates
.
1.2.2 (2017-03-14)
- Fixed multiple rounding issues in
GeoCoordinateFormatter
.
1.2.1 (2016-12-16)
- Fixed another IEEE issue in
GeoCoordinateFormatter
.
1.2.0 (2016-11-11)
- Added missing inline documentation to public methods and constants.
- Added a basic PHPCS rule set, can be run with
composer phpcs
.
1.1.8 (2016-10-12)
- Fixed an IEEE issue in
GeoCoordinateFormatter
- Fixed a PHP 7.1 compatibility issue in a test
1.1.7 (2016-05-25)
- Made minor documentation improvements
1.1.6 (2016-04-02)
- Added compatibility with DataValues Common 0.3.x
1.1.5 (2015-12-28)
- The component can now be installed together with DataValues Interfaces 0.2.x
1.1.4 (2014-11-25)
- Add fall back to default on invalid precision to more places.
1.1.3 (2014-11-19)
- Fall back to default on invalid precision instead of dividing by zero.
1.1.2 (2014-11-18)
- Precision detection in
GlobeCoordinateParser
now has a lower bound of 0.00000001°
1.1.1 (2014-10-21)
- Removed remaining uses of class aliases from messages and comments
- Fixed some types in documentation
1.1.0 (2014-10-09)
- Made the component installable with DataValues 1.x
GeoCoordinateFormatter
now supports precision in degreesGlobeCoordinateFormatter
now passes the globe precision to theGeoCoordinateFormatter
it uses- Introduced
FORMAT_NAME
class constants on ValueParsers in order to use them as expectedFormat - Changed ValueParsers to pass rawValue and expectedFormat arguments when constructing a
ParseException
1.0.0 (2014-07-31)
- All classes and interfaces have been moved into the
DataValues\Geo
namespaceDataValues\LatLongValue
has been left as deprecated aliasDataValues\GlobeCoordinateValue
has been left as deprecated alias
- Globe in
GlobeCoordinateValue
now defaults tohttp://www.wikidata.org/entity/Q2
0.2.0 (2014-07-07)
- Removed deprecated
GeoCoordinateValue
- Added
GlobeMath
0.1.2 (2014-01-22)
- Added support for different levels of spacing in GeoCoordinateFormatter
0.1.1 (2013-11-30)
- Added support for direction notation to GeoCoordinateFormatter
- Decreased complexity of GeoCoordinateFormatter
- Decreased complexity and coupling of GeoCoordinateFormatterTest
0.1.0 (2013-11-17)
Initial release with these features:
- LatLongValue
- GlobeCoordinateValue
- GeoCoordinateFormatter
- GlobeCoordinateFormatter
- DdCoordinateParser
- DmCoordinateParser
- DmsCoordinateParser
- FloatCoordinateParser
- GeoCoordinateParser
- GlobeCoordinateParser