|
| 1 | +# GeoJson PHP Library |
| 2 | + |
| 3 | +This library implements the |
| 4 | +[GeoJSON format specification](http://www.geojson.org/geojson-spec.html). |
| 5 | + |
| 6 | +The `GeoJson` namespace includes classes for each data structure defined in the |
| 7 | +GeoJSON specification. Core GeoJSON objects include geometries, features, and |
| 8 | +collections. Geometries range from primitive points to more complex polygons. |
| 9 | +Classes also exist for bounding boxes and coordinate reference systems. |
| 10 | + |
| 11 | +## Installation |
| 12 | + |
| 13 | +The library is published as a |
| 14 | +[package](https://packagist.org/packages/jmikola/geojson) and is installable via |
| 15 | +[Composer](http://getcomposer.org/): |
| 16 | + |
| 17 | +``` |
| 18 | +$ composer require "jmikola/geojson=^1.0" |
| 19 | +``` |
| 20 | + |
| 21 | +## API Documentation |
| 22 | + |
| 23 | +API documentation may be found [here](./api). |
| 24 | + |
| 25 | +## Usage |
| 26 | + |
| 27 | +Classes in this library are immutable. |
| 28 | + |
| 29 | +### GeoJson Constructors |
| 30 | + |
| 31 | +Geometry objects are constructed using a single coordinates array. This may be |
| 32 | +a tuple in the case of a `Point`, an array of tuples for a `LineString`, etc. |
| 33 | +Constructors for each class will validate the coordinates array and throw an |
| 34 | +`InvalidArgumentException` on error. |
| 35 | + |
| 36 | +More primitive geometry objects may also be used for constructing complex |
| 37 | +objects. For instance, a `LineString` may be constructed from an array of |
| 38 | +`Point` objects. |
| 39 | + |
| 40 | +Feature objects are constructed from a geometry object, associative properties |
| 41 | +array, and an identifier, all of which are optional. |
| 42 | + |
| 43 | +Feature and geometry collection objects are constructed from an array of their |
| 44 | +respective types. |
| 45 | + |
| 46 | +#### Specifying a Bounding Box or CRS |
| 47 | + |
| 48 | +All GeoJson constructors support `BoundingBox` and `CoordinateReferenceSystem` |
| 49 | +objects as optional arguments beyond those explicitly listed in their prototype. |
| 50 | +These objects may appear in any order *after* the explicit arguments. |
| 51 | + |
| 52 | +```php |
| 53 | +$crs = new \GeoJson\CoordinateReferenceSystem\Named('urn:ogc:def:crs:OGC:1.3:CRS84'); |
| 54 | +$box = new \GeoJson\BoundingBox([-180, -90, 180, 90]); |
| 55 | +$point = new \GeoJson\Geometry\Point([0, 0], $crs, $box); |
| 56 | +``` |
| 57 | + |
| 58 | +Note that the `Feature` class is unique in that it has three arguments, all with |
| 59 | +default values. In order to construct a `Feature` with a bounding box or CRS, |
| 60 | +all three arguments must be explicitly listed (e.g. with `null` placeholders). |
| 61 | + |
| 62 | +```php |
| 63 | +$box = new \GeoJson\BoundingBox([-180, -90, 180, 90]); |
| 64 | +$feature = new \GeoJson\Feature\Feature(null, null, null, $box); |
| 65 | +``` |
| 66 | + |
| 67 | +### JSON Serialization |
| 68 | + |
| 69 | +Each class in the library implements PHP 5.4's |
| 70 | +[JsonSerializable](http://php.net/manual/en/class.jsonserializable.php) |
| 71 | +interface, which allows objects to be passed directly to `json_encode()`. |
| 72 | + |
| 73 | +```php |
| 74 | +$point = new \GeoJson\Geometry\Point([1, 1]); |
| 75 | +$json = json_encode($point); |
| 76 | +``` |
| 77 | + |
| 78 | +Printing the `$json` variable would yield (sans whitespace): |
| 79 | + |
| 80 | +```json |
| 81 | +{ |
| 82 | + "type": "Point", |
| 83 | + "coordinates": [1, 1] |
| 84 | +} |
| 85 | +``` |
| 86 | + |
| 87 | +A stub interface is included for compatibility with PHP 5.3, although lack of |
| 88 | +core support for the interface means that `jsonSerialize()` will need to be |
| 89 | +manually called and its return value passed to `json_encode()`. |
| 90 | + |
| 91 | +### JSON Unserialization |
| 92 | + |
| 93 | +The core `GeoJson` class implements an internal `JsonUnserializable` interface, |
| 94 | +which defines a static factory method, `jsonUnserialize()`, that can be used to |
| 95 | +create objects from the return value of `json_decode()`. |
| 96 | + |
| 97 | +```php |
| 98 | +$json = '{ "type": "Point", "coordinates": [1, 1] }'; |
| 99 | +$json = json_decode($json); |
| 100 | +$point = \GeoJson\GeoJson::jsonUnserialize($json); |
| 101 | +``` |
| 102 | + |
| 103 | +If errors are encountered during unserialization, an `UnserializationException` |
| 104 | +will be thrown by `jsonUnserialize()`. Possible errors include: |
| 105 | + |
| 106 | + * Missing properties (e.g. `type` is not present) |
| 107 | + * Unexpected values (e.g. `coordinates` property is not an array) |
| 108 | + * Unsupported `type` string when parsing a GeoJson object or CRS |
0 commit comments