README

Lexer and parser library for geographic coordinate strings.

Installation

composer require longitude-one/geo-parser

Current version:

composer require longitude-one/geo-parser:3.0.3

Usage

The parser supports two usage patterns. Pass the value to parse to the constructor, then call parse() on the resulting Parser object:

use LongitudeOne\Geo\String\Parser;

$input  = '79°56′55″W, 40°26′46″N';

$parser = new Parser($input);

$value = $parser->parse(); // [-79.948611111111, 40.446111111111]

When parsing many values, reuse a single Parser instance:

use LongitudeOne\Geo\String\Parser;

$input1 = '56.242 E';
$input2 = '40:26:46 S';

$parser = new Parser();

$value1 = $parser->parse($input1); //56.242
$value2 = $parser->parse($input2); //-40.446111111111

Supported Formats

Both single values and coordinate pairs are supported. The following examples illustrate the supported formats; they are not exhaustive.

1. Simple single-signed values

   • 40
   • -40
   • -8.543
   • +132
   • +77.2

2. Simple single signed values with degree symbol

   • 40°
   • -40°
   • -5.234°
   • +43°
   • +38.43°

3. Single unsigned values with or without degree symbol, and cardinal direction

   • 40° N
   • 40 S
   • 56.242 E

4. Single values of signed integer degrees with degree symbol, and decimal minutes with apostrophe

   • 40° 26.222'
   • -65° 32.22'
   • +165° 52.22'

5. Single values of unsigned integer degrees with degree symbol, decimal minutes with apostrophe, and cardinal direction

   • 40° 26.222' E
   • 65° 32.22' S

6. Single values of signed integer degrees with degree symbol, integer minutes with apostrophe, and optional integer or decimal seconds with quote

   • 40° 26' 46"
   • -79° 58' 56"
   • 93° 19' 25.8"
   • +120° 19' 25.8"

7. Single values of signed integer degrees with colon symbol, integer minutes, and optional colon and integer or decimal seconds

   • +40:26:46
   • -79:58:56
   • 93:19:25.8

8. Single values of unsigned integer degrees with degree symbol, integer minutes with apostrophe, optional integer or decimal seconds with quote, and cardinal direction

   • 40° 26' 46" S
   • 99° 58' 56" W
   • 44° 58' 53.9" N

9. Single values of unsigned integer degrees with a colon, integer minutes, optional integer or decimal seconds, and a cardinal direction

   • 40:26:46 S
   • 99:58:56 W
   • 44:58:53.9 N

10. Two of any one format separated by whitespace

11. Two of any one format separated by a comma

Return

The parser returns an integer or float for a single value, or an array containing a coordinate pair.

String inputs are tokenized and parsed as geographic coordinates. Native integer and float inputs are returned unchanged, including their type, without passing through the lexer or geographic range validation.

Exceptions

Library exceptions thrown by the Lexer and Parser implement the LongitudeOne\Geo\String\Exception\ExceptionInterface interface:

use LongitudeOne\Geo\String\Exception\ExceptionInterface;
use LongitudeOne\Geo\String\Parser;

try {
    $value = (new Parser('100N'))->parse();
} catch (ExceptionInterface $exception) {
    // Handle a library parsing exception.
}

Roadmap

Note

A major release may increase the minimum supported PHP version. Other breaking changes are documented in the changelog.

PHP versions marked as “tested”, along with every listed Doctrine Lexer version, are part of the continuous integration matrix.

Support Policy

Only the latest major version receives feature and bug fixes. Non-security issues will not be addressed during the security-fixes period.

Previous major versions may receive security fixes only, according to the roadmap above.