diff --git a/.gitignore b/.gitignore index 81b9258..100c89a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +apigen.phar composer.lock phpunit.xml +site vendor + diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4fd8b31 --- /dev/null +++ b/Makefile @@ -0,0 +1,53 @@ +.PHONY: apigen composer test docs mkdocs + +COMPOSER_ARGS=update --no-interaction --prefer-source +PHPUNIT_ARGS=--process-isolation + +composer: + @command -v composer >/dev/null 2>&1; \ + if test $$? -eq 0; then \ + composer $(COMPOSER_ARGS); \ + elif test -r composer.phar; then \ + php composer.phar $(COMPOSER_ARGS); \ + else \ + echo >&2 "Cannot find composer; aborting."; \ + false; \ + fi + +test: composer + @command -v phpunit >/dev/null 2>&1; \ + if test $$? -eq 0; then \ + phpunit $(PHPUNIT_ARGS); \ + elif test -r phpunit.phar; then \ + php phpunit.phar $(PHPUNIT_ARGS); \ + else \ + echo >&2 "Cannot find phpunit; aborting."; \ + false; \ + fi + +apigen: + @command -v apigen >/dev/null 2>&1; \ + if test $$? -eq 0; then \ + apigen generate; \ + elif test -r apigen.phar; then \ + php apigen.phar generate; \ + else \ + echo >&2 "Cannot find apigen; aborting."; \ + false; \ + fi + +mkdocs: + @command -v mkdocs >/dev/null 2>&1; \ + if test $$? -eq 0; then \ + mkdocs build --clean; \ + else \ + echo >&2 "Cannot find mkdocs; aborting."; \ + false; \ + fi + +docs: mkdocs apigen + +publish-docs: docs + mkdocs gh-deploy + @echo "If origin is your local fork, you may need to run:" + @echo " " git push REMOTE gh-pages:gh-pages diff --git a/README.md b/README.md index b084b11..f024810 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -# GeoJson +# GeoJson PHP Library [![Build Status](https://travis-ci.org/jmikola/geojson.png?branch=master)](https://travis-ci.org/jmikola/geojson) +[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/jmikola/geojson/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/jmikola/geojson/?branch=master) +[![Code Coverage](https://scrutinizer-ci.com/g/jmikola/geojson/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/jmikola/geojson/?branch=master) This library implements the [GeoJSON format specification](http://www.geojson.org/geojson-spec.html). @@ -20,87 +22,7 @@ The library is published as a $ composer require "jmikola/geojson=~1.0" ``` -## Usage +## More Resources -Classes in this library are immutable. - -### GeoJson Constructors - -Geometry objects are constructed using a single coordinates array. This may be -a tuple in the case of a `Point`, an array of tuples for a `LineString`, etc. -Constructors for each class will validate the coordinates array and throw an -`InvalidArgumentException` on error. - -More primitive geometry objects may also be used for constructing complex -objects. For instance, a `LineString` may be constructed from an array of -`Point` objects. - -Feature objects are constructed from a geometry object, associative properties -array, and an identifier, all of which are optional. - -Feature and geometry collection objects are constructed from an array of their -respective types. - -#### Specifying a Bounding Box or CRS - -All GeoJson constructors support `BoundingBox` and `CoordinateReferenceSystem` -objects as optional arguments beyond those explicitly listed in their prototype. -These objects may appear in any order *after* the explicit arguments. - -```php -$crs = new \GeoJson\CoordinateReferenceSystem\Named('urn:ogc:def:crs:OGC:1.3:CRS84'); -$box = new \GeoJson\BoundingBox([-180, -90, 180, 90]); -$point = new \GeoJson\Geometry\Point([0, 0], $crs, $box); -``` - -Note that the `Feature` class is unique in that it has three arguments, all with -default values. In order to construct a `Feature` with a bounding box or CRS, -all three arguments must be explicitly listed (e.g. with `null` placeholders). - -```php -$box = new \GeoJson\BoundingBox([-180, -90, 180, 90]); -$feature = new \GeoJson\Feature\Feature(null, null, null, $box); -``` - -### JSON Serialization - -Each class in the library implements PHP 5.4's -[JsonSerializable](http://php.net/manual/en/class.jsonserializable.php) -interface, which allows objects to be passed directly to `json_encode()`. - -```php -$point = new \GeoJson\Geometry\Point([1, 1]); -$json = json_encode($point); -``` - -Printing the `$json` variable would yield (sans whitespace): - -```json -{ - "type": "Point", - "coordinates": [1, 1] -} -``` - -A stub interface is included for compatibility with PHP 5.3, although lack of -core support for the interface means that `jsonSerialize()` will need to be -manually called and its return value passed to `json_encode()`. - -### JSON Unserialization - -The core `GeoJson` class implements an internal `JsonUnserializable` interface, -which defines a static factory method, `jsonUnserialize()`, that can be used to -create objects from the return value of `json_decode()`. - -```php -$json = '{ "type": "Point", "coordinates": [1, 1] }'; -$json = json_decode($json); -$point = \GeoJson\GeoJson::jsonUnserialize($json); -``` - -If errors are encountered during unserialization, an `UnserializationException` -will be thrown by `jsonUnserialize()`. Possible errors include: - - * Missing properties (e.g. `type` is not present) - * Unexpected values (e.g. `coordinates` property is not an array) - * Unsupported `type` string when parsing a GeoJson object or CRS + * [Documentation](http://jmikola.github.io/geojson) + * [API reference](http://jmikola.github.io/geojson/api) diff --git a/apigen.neon b/apigen.neon new file mode 100644 index 0000000..e786e34 --- /dev/null +++ b/apigen.neon @@ -0,0 +1,23 @@ +source: + - src + +destination: site/api + +charset: + - UTF-8 + +main: GeoJSON PHP library +title: GeoJSON PHP library +baseUrl: http://jmikola.github.io/geojson +googleCseId: null +googleAnalytics: null +templateTheme: bootstrap +templateConfig: null + +deprecated: false +internal: false +todo: false + +php: false +tree: true +download: false diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e5e717c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,108 @@ +# GeoJson PHP Library + +This library implements the +[GeoJSON format specification](http://www.geojson.org/geojson-spec.html). + +The `GeoJson` namespace includes classes for each data structure defined in the +GeoJSON specification. Core GeoJSON objects include geometries, features, and +collections. Geometries range from primitive points to more complex polygons. +Classes also exist for bounding boxes and coordinate reference systems. + +## Installation + +The library is published as a +[package](https://packagist.org/packages/jmikola/geojson) and is installable via +[Composer](http://getcomposer.org/): + +``` +$ composer require "jmikola/geojson=^1.0" +``` + +## API Documentation + +API documentation may be found [here](./api). + +## Usage + +Classes in this library are immutable. + +### GeoJson Constructors + +Geometry objects are constructed using a single coordinates array. This may be +a tuple in the case of a `Point`, an array of tuples for a `LineString`, etc. +Constructors for each class will validate the coordinates array and throw an +`InvalidArgumentException` on error. + +More primitive geometry objects may also be used for constructing complex +objects. For instance, a `LineString` may be constructed from an array of +`Point` objects. + +Feature objects are constructed from a geometry object, associative properties +array, and an identifier, all of which are optional. + +Feature and geometry collection objects are constructed from an array of their +respective types. + +#### Specifying a Bounding Box or CRS + +All GeoJson constructors support `BoundingBox` and `CoordinateReferenceSystem` +objects as optional arguments beyond those explicitly listed in their prototype. +These objects may appear in any order *after* the explicit arguments. + +```php +$crs = new \GeoJson\CoordinateReferenceSystem\Named('urn:ogc:def:crs:OGC:1.3:CRS84'); +$box = new \GeoJson\BoundingBox([-180, -90, 180, 90]); +$point = new \GeoJson\Geometry\Point([0, 0], $crs, $box); +``` + +Note that the `Feature` class is unique in that it has three arguments, all with +default values. In order to construct a `Feature` with a bounding box or CRS, +all three arguments must be explicitly listed (e.g. with `null` placeholders). + +```php +$box = new \GeoJson\BoundingBox([-180, -90, 180, 90]); +$feature = new \GeoJson\Feature\Feature(null, null, null, $box); +``` + +### JSON Serialization + +Each class in the library implements PHP 5.4's +[JsonSerializable](http://php.net/manual/en/class.jsonserializable.php) +interface, which allows objects to be passed directly to `json_encode()`. + +```php +$point = new \GeoJson\Geometry\Point([1, 1]); +$json = json_encode($point); +``` + +Printing the `$json` variable would yield (sans whitespace): + +```json +{ + "type": "Point", + "coordinates": [1, 1] +} +``` + +A stub interface is included for compatibility with PHP 5.3, although lack of +core support for the interface means that `jsonSerialize()` will need to be +manually called and its return value passed to `json_encode()`. + +### JSON Unserialization + +The core `GeoJson` class implements an internal `JsonUnserializable` interface, +which defines a static factory method, `jsonUnserialize()`, that can be used to +create objects from the return value of `json_decode()`. + +```php +$json = '{ "type": "Point", "coordinates": [1, 1] }'; +$json = json_decode($json); +$point = \GeoJson\GeoJson::jsonUnserialize($json); +``` + +If errors are encountered during unserialization, an `UnserializationException` +will be thrown by `jsonUnserialize()`. Possible errors include: + + * Missing properties (e.g. `type` is not present) + * Unexpected values (e.g. `coordinates` property is not an array) + * Unsupported `type` string when parsing a GeoJson object or CRS diff --git a/docs/pretty.js b/docs/pretty.js new file mode 100644 index 0000000..cd0aa1e --- /dev/null +++ b/docs/pretty.js @@ -0,0 +1,4 @@ +$(document).ready(function() { + $('pre code').parent().addClass('prettyprint well'); + prettyPrint(); +}); diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..67decb7 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,7 @@ +site_name: "GeoJSON PHP library" +repo_url: https://github.com/jmikola/geojson +theme: spacelab +pages: + - [index.md, Home] +extra_javascript: + - pretty.js