README

Cartographer is a PHP library providing the ability to programmatically generate GeoJSON objects.

GeoJSON is a format for encoding a variety of geographic data structures. A GeoJSON object may represent a geometry, a feature, or a collection of features. GeoJSON supports the following geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection. Features in GeoJSON contain a geometry object and additional properties, and a feature collection represents a list of features.

Cartographer was written to adhere to the GeoJSON specification, information can be found here: http://geojson.org/geojson-spec.html

Requirements

PHP >= 7.3.0

This library is unit tested against PHP 7.3, 7.4, 8.0, 8.1 and 8.2!

If you need to use an older version of PHP, you should instead install the 1.x version of this library (see below for details).

License

This client library is released under the GPLv3 license, you are welcome to use it, improve it and contribute your changes back!

Installation

The recommended way of installing this library is via. Composer; To install using Composer type the following command at the console:

composer require ballen/cartographer

If you need to use an older version of PHP, version 1.x.x supports PHP 5.3, 5.4, 5.5, 5.6, 7.0, 7.1 and 7.2, you can install this version using Composer with this command instead:

composer require ballen/cartographer ^1.0

Example usage

Point

The "Point" type is the most basic to construct, this example shows an example of plotting a single point on a map.

use Ballen\Cartographer\Core\LatLong;
use Ballen\Cartographer\Point;

$point = new Point(new LatLong(52.005523, 1.045936));
echo $point->generate();
// {"type":"Point","coordinates":[1.045936,52.005523]}

Check out the GitHub Gist rendition of the GeoJSON output: https://gist.github.com/allebb/55f059efbd708be130112b6d39b16406

Linestring

The "LineString" type contains a list of geographic points (Lat/Longs) of which are joined together to display a line.

use Ballen\Cartographer\Core\LatLong;
use Ballen\Cartographer\LineString;

$points = [
    new LatLong(51.973683,1.044497),
    new LatLong(51.974067,1.044134),
    new LatLong(51.974355,1.045795),
    new LatLong(51.975010,1.049768),
    new LatLong(51.976018,1.055869),
    new LatLong(51.976195,1.056060),
    new LatLong(51.976432,1.056083),
    new LatLong(51.976774,1.056036),
    new LatLong(51.977023,1.056115),
    new LatLong(51.977107,1.056379),
    new LatLong(51.977102,1.056658),
 ];
$linestring = new LineString($points);
echo $linestring->generate();
// {"type":"LineString","coordinates":[[1.044497,51.973683],[1.044134,51.974067],[1.045795,51.974355],[1.049768,51.97501],[1.055869,51.976018],[1.05606,51.976195],[1.056083,51.976432],[1.056036,51.976774],[1.056115,51.977023],[1.056379,51.977107],[1.056658,51.977102]]}

Check out the GitHub Gist rendition of the GeoJSON output: https://gist.github.com/allebb/ec422a00b877e28a3d6913df68c5954c

Polygon

A Polygon type object, contains a list of coordinates, the first and last coordinate must match. For Polygons with multiple rings, the first must be the exterior ring and any others must be interior rings or holes.

use Ballen\Cartographer\Core\LatLong;
use Ballen\Cartographer\Polygon;
use Ballen\Cartographer\Core\LinearRing;

$points = [
    (new LatLong(52.064761, 1.174470))->lngLatArray(),
    (new LatLong(52.065045, 1.176098))->lngLatArray(),
    (new LatLong(52.064964, 1.176156))->lngLatArray(),
    (new LatLong(52.065172, 1.177106))->lngLatArray(),
    (new LatLong(52.064146, 1.177594))->lngLatArray(),
    (new LatLong(52.063968, 1.176768))->lngLatArray(),
    (new LatLong(52.063714, 1.174875))->lngLatArray(),
    (new LatLong(52.064761, 1.174470))->lngLatArray(),
];
$linestring = new Polygon((new LinearRing())->addRing($points));
echo $linestring->generate();
// {"type":"Polygon","coordinates":[[[1.17447,52.064761],[1.176098,52.065045],[1.176156,52.064964],[1.177106,52.065172],[1.177594,52.064146],[1.176768,52.063968],[1.174875,52.063714],[1.17447,52.064761]]]}

Check out the GitHub Gist rendition of the GeoJSON object: https://gist.github.com/allebb/30dd0db2a33b763309e64af8cfe3e33c

Feature

A feature enables you to plot a single GeoJSON object on a map with associated properties, Google Maps enable you to render Feature and FeatureCollection types.

A example of a Point feature type is as follows:

use Ballen\Cartographer\Core\LatLong;
use Ballen\Cartographer\Feature;
use Ballen\Cartographer\Point;

$feature = new Feature(new Point(new LatLong(52.063186, 1.157385)), [
    // Your own personal marker points (appear when you click on the Feature point)
    'Park' => 'Christchurch Park',
    'Post code' => 'IP4 2BX',
    'Link' => 'http://focp.org.uk/',
    // Optional Mapbox supported properties (See: https://www.mapbox.com/help/markers/)
    'marker-color' => '#3bb2d0', // A light blue marker colour
    'marker-symbol' => 'park',
    'marker-size' => 'large',
]);
echo $feature->generate();
// {"type":"Feature","geometry":{"type":"Point","coordinates":[1.157385,52.063186]},"properties":{"Park":"Christchurch Park","Post code":"IP4 2BX","Link":"http:\/\/focp.org.uk\/","marker-color":"#3bb2d0","marker-symbol":"park","marker-size":"large"}}

Check out the GitHub Gist rendition of the GeoJSON output: https://gist.github.com/allebb/a1dfa013273cc75ce061a13250ae6683

Feature Collection

A feature collection can contain any number of GeoJSON objects with their own properties, all of the features in a collection with their own properties.

use Ballen\Cartographer\Core\LatLong;
use Ballen\Cartographer\Feature;
use Ballen\Cartographer\Point;

$park = new Feature(new Point(new LatLong(52.063186, 1.157385)), [
    // Your own personal marker points (appear when you click on the Feature point)
    'Park' => 'Christchurch Park',
    'Post code' => 'IP4 2BX',
    'Link' => 'http://focp.org.uk/',
    // Optional Mapbox supported properties (See: https://www.mapbox.com/help/markers/)
    'marker-color' => '#3bb2d0', // A light blue marker colour
    'marker-symbol' => 'park',
    'marker-size' => 'large',
]);

// Train Station Specific codes
$station_properties = [
    'marker-color' => '#F6546A',
    'marker-symbol' => 'rail',
    'marker-size' => 'medium'
];

// Set some train stations with their own names (merge the standard train station details)
$station_central = new Feature(new Point(new LatLong(52.050743, 1.143012)), array_merge($station_properties, ['Name' => 'Ipswich Train Station']));
$station_derbyroad = new Feature(new Point(new LatLong(52.050808, 1.182638)), array_merge($station_properties, ['Name' => 'Derby Road Station']));
$station_westerfield = new Feature(new Point(new LatLong(52.081026, 1.166773)), array_merge($station_properties, ['Name' => 'Westerfield Train Station']));

// Create the new collection and add each of the GeoJSON objects to it...
$collection = new Ballen\Cartographer\FeatureCollection([$station_central, $park, $station_westerfield, $station_derbyroad]);
echo $collection->generate();
// {"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[1.143012,52.050743]},"properties":{"marker-color":"#F6546A","marker-symbol":"rail","marker-size":"medium","Name":"Ipswich Train Station"}},{"type":"Feature","geometry":{"type":"Point","coordinates":[1.157385,52.063186]},"properties":{"Park":"Christchurch Park","Post code":"IP4 2BX","Link":"http:\/\/focp.org.uk\/","marker-color":"#3bb2d0","marker-symbol":"park","marker-size":"large"}},{"type":"Feature","geometry":{"type":"Point","coordinates":[1.166773,52.081026]},"properties":{"marker-color":"#F6546A","marker-symbol":"rail","marker-size":"medium","Name":"Westerfield Train Station"}},{"type":"Feature","geometry":{"type":"Point","coordinates":[1.182638,52.050808]},"properties":{"marker-color":"#F6546A","marker-symbol":"rail","marker-size":"medium","Name":"Derby Road Station"}}]}

Check out the GitHub Gist rendition of the GeoJSON output: https://gist.github.com/allebb/1802d538814ed0875ab05060a439b774

Other examples

Other examples of the types of GeoJSON object type, see the examples/test.php file.

Tests and coverage

This library is fully unit tested using PHPUnit.

I use GitHub Actions for continuous integration, which triggers tests for PHP 7.3, 7.4, 8.0, 8.1 and 8.2 each time a commit is pushed.

If you wish to run the tests yourself you should run the following:

# Install the Cartographer Library (which will include PHPUnit as part of the require-dev dependencies)
composer install

# Now we run the unit tests (from the root of the project) like so:
./vendor/bin/phpunit

Code coverage can also be run, and a report generated (this does require XDebug to be installed)...

./vendor/bin/phpunit --coverage-html ./report

Support

I am happy to provide support via. my personal email address, so if you need a hand drop me an email at: ballen@bobbyallen.me.

ballen / cartographer

Maintainers

Details