Extend documentation for easier contribution (#12)

* Split up documentation from readme into docs folder
* Extend contributing information
* Add copyright statement

Author: Felix D

CLA.md

@@ -0,0 +1,31 @@
+# Contributor License Agreement
+
+If you are an employee and have created the contribution as part of your employment,
+you need to have your employer approve this agreement.
+If you do not own the copyright in the entire work of authorship,
+any other author of the contribution also needs to sign this.
+
+## Copyright License
+
+You hereby grant to Oneoff-tech UG, the maintainer of GeoServer PHP Client,
+a worldwide, royalty-free, non-exclusive, perpetual and irrevocable license,
+with the right to transfer an unlimited number of non-exclusive licenses
+or to grant sublicenses to third parties, under the copyright covering the contribution
+to use the contribution by all means, including, but not limited to:
+
+* publish the contribution,
+* modify the contribution,
+* prepare derivative works based upon or containing the contribution
+  and/or to combine the contribution with other materials,
+* reproduce the contribution in original or modified form,
+* distribute, to make the contribution available to the public, display
+  and publicly perform the contribution in original or modified form.
+
+## Free Software Pledge
+
+We agree to irrevocably (sub)license the contribution
+or any materials containing, based on or derived from your contribution
+under the terms of any licenses
+the Free Software Foundation classifies as [Free Software licenses](https://www.gnu.org/licenses/license-list.html)
+and which are approved by the Open Source Initiative as [Open Source licenses](http://opensource.org/licenses).
+See the [LICENSE](/LICENSE.txt) file, for the current license used.

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# How to contribute to GeoServer PHP Client
+
+This library is Free and Open Source Software. All Contributions to this project are most welcome, and can take many forms such as detailed bug reports, documentation, tests, features, and patches. Note that all contributions are managed by [OneOffTech](https://www.oneofftech.xyz).
+
+## Bugs and Help
+
+GitHub [issues should only be created](https://github.com/OneOffTech/geoserver-client-php/issues/new) to log bugs or ask for help. Before posting to Github, please also search the existing issues to see if the bug has already been reported, and add any further details to the existing issue.
+
+## Development
+
+Contributions are most easily managed via GitHub [pull requests](https://github.com/oneofftech/geoserver-client-php/pulls). To prepare one, [fork the GeoServer PHP Client](https://github.com/oneofftech/geoserver-client-php/fork) into your own GitHub repository. Then you'll be able to commit your work and submit pull requests. Once you are done, Github allows you to create a pull request and propose your changes to the original repository. Make sure you target your pull request to the `master` branch.
+
+The project follows the PSR-2 coding standard. Please run `./vendor/bin/php-cs-fixer fix` before wrapping everything up.
+
+## Documentation
+
+All documentation is stored in the ["docs" directory of this repository](https://github.com/OneOffTech/geoserver-client-php/tree/master/docs). Any contribution on improving the documentation is highly appreciated and a good way to become a welcomed contributor.
+
+## Contributor License Agreement
+
+The [Contributor License Agreement](./CLA.md) specifies the way how copyright of your contribution is handled. Please include in the comment on your pull request a statement like the following:
+
+> I'd like to contribute `feature X|bugfix Y|docs|something else` to GeoServer PHP Client. I confirm that my contributions to GeoServer PHP Client will be compatible with the GeoServer PHP Client Contributor License Agreement at the time of contribution.

README.md

@@ -0,0 +1,50 @@
+[![Build Status](https://travis-ci.org/OneOffTech/geoserver-client-php.svg?branch=master)](https://travis-ci.org/OneOffTech/geoserver-client-php)
+![Packagist](https://img.shields.io/packagist/v/oneofftech/geoserver-client-php.svg)
+
+# GeoServer PHP Client
+
+This PHP library provides programmatic functions to access a [GeoServer](http://geoserver.org/).
+
+It is Free and Open Source Software. All contributions are most welcome. Learn more about [how to contribute](./CONTRIBUTING.md).
+
+#### Features
+
+* Obtain the [version](./docs/usage.md#get-the-geoserver-version) of the connected GeoServer instance
+* [Create workspace](./docs/usage.md#create-the-workspace) or retrieve existing workspace details
+* [Create datastores](./docs/usage.md#data-stores) and listing them
+* [Create coveragestores](./docs/usage.md#coverage-stores) and listing them
+* [Upload files](./docs/usage.md#uploading-geographic-files) in various [formats](#supported-file-formats)
+* [Manage styles](./docs/usage.md#styles) in SLD format
+
+For detailed information of each of the provided functions check out the [documentation on the usage](./docs/usage.md).
+
+#### Requirements
+
+* [PHP 7.1](http://www.php.net/) or above.
+* [GeoServer](http://geoserver.org/) 2.13.0 or above
+
+## Installation
+
+The GeoServer PHP Client uses [Composer](http://getcomposer.org/) to manage its dependencies.
+
+```bash
+composer require php-http/guzzle6-adapter guzzlehttp/psr7 oneofftech/geoserver-client-php
+```
+
+For more information, please review the [documentation on the installation process](./docs/installation.md).
+
+## Supported file formats
+
+The library handles:
+
+* `Shapefile`
+* `Shapefile` inside `zip` archive
+* `GeoTIFF`
+* `GeoPackage` format version 1.2 (can contain both vector and raster data, but will be reported as vector)
+* Styled Layer Descriptor `SLD` files for layer styles in XML format
+
+Read more on [supported file formats and encoding](./docs/supported-files.md).
+
+## License
+
+This project is Free and Open Source Software, licensed under the [AGPL v3 license](./LICENSE.txt).

docs/installation.md

@@ -0,0 +1,16 @@
+# Installation
+
+The GeoServer client uses [Composer](http://getcomposer.org/) to manage its dependencies. 
+
+```bash
+composer require php-http/guzzle6-adapter guzzlehttp/psr7 oneofftech/geoserver-client-php
+```
+
+The GeoServer client is not hard coupled to [Guzzle](https://github.com/guzzle/guzzle) or any other library that sends HTTP messages. It uses an abstraction called [HTTPlug](http://httplug.io/). This will give you the flexibilty to choose what PSR-7 implementation and HTTP client to use.
+
+## Why requiring so many packages?
+
+GeoServer client has a dependency on the virtual package
+[php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation) which requires to you install **an** adapter, but we do not care which one. That is an implementation detail in your application. We also need **a** PSR-7 implementation and **a** message factory.
+
+You do not have to use the `php-http/guzzle6-adapter` if you do not want to. You may use the `php-http/curl-client`. Read more about the virtual packages, why this is a good idea and about the flexibility it brings at the [HTTPlug docs](http://docs.php-http.org/en/latest/httplug/users.html).

docs/supported-files.md

@@ -0,0 +1,43 @@
+# Supported file formats
+
+The library is able to recognize:
+
+* `Shapefile`
+* `Shapefile` inside `zip` archive
+* `GeoTIFF`
+* `GeoPackage` format version 1.2 (can contain both vector and raster data, but will be reported as vector)
+* Styled Layer Descriptor `SLD` files for layer styles in XML format
+
+You can check if a file is supported using
+
+```php
+use OneOffTech\GeoServer\GeoFile;
+use OneOffTech\GeoServer\StyleFile;
+
+$isSupported = GeoFile::isSupported($path);
+// => true/false
+
+
+// For style files, the support is available with the StyleFile class
+$isSupported = StyleFile::isSupported($path);
+// => true/false
+```
+
+> The library supports only the file formats that can be uploaded to a GeoServer. 
+> For example `Geojson`, `KML` and `GPX` are not supported out-of-the-box by GeoServer,
+> although plugins might be available for doing that
+
+# File Character Encoding
+
+GeoServer can deal with character encoding of layers/features, but tests highlighted
+a limited support when using UTF-8 for data/coverage store names.
+
+To prevent issues with UTF-8 features attributes, the client set the character encoding
+to UTF-8 when uploading a file. In this way GeoServer will consider UTF-8 as the
+character encoding for features/attributes contained in the file. This do not affect
+layer or store names.
+
+As by design decision the store name is the filename, or the assigned name when 
+performing the upload, we highly reccomend to use ASCII characters for it.
+Use of UTF-8 encoded filenames (or store name) might prevent the client to retrieve the 
+store/layer corresponding to the uploaded file.

docs/tests.md

@@ -0,0 +1,35 @@
+# Testing
+
+The library is covered with unit and integration tests. 
+
+```
+vendor/bin/phpunit
+```
+
+By default integration tests are not executed unless in the phpunit.xml file a GeoServer instance is specified.
+
+The `phpunit.xml.dist` define the `GEOSERVER_URL`, `GEOSERVER_USER`, `GEOSERVER_PASSWORD` for that purpose. 
+If you want you can copy `phpunit.xml.dist` to `phpunit.xml` and edit those variables in place 
+or define them in your environment variables.
+
+```xml
+<env name="GEOSERVER_URL" value="http://localhost:8600/geoserver/"/>
+<env name="GEOSERVER_USER" value="user"/>
+<env name="GEOSERVER_PASSWORD" value="pass"/>
+```
+
+If you don't have a GeoServer instance to trash there is a `docker-compose.yml` file that, with 
+the help of Docker and the [kartoza/geoserver image](https://hub.docker.com/r/kartoza/geoserver/), 
+creates a running GeoServer instance on port 8600.
+
+> Be aware that the Kartoza GeoServer image requires [4GB of RAM](https://github.com/kartoza/docker-geoserver/blob/master/Dockerfile#L23-L25) to run
+
+```bash
+docker-compose -f ./tests/docker-compose.yml up -d
+# here better to wait for the full startup of the geoserver
+vendor/bin/phpunit
+```
+
+**Notes on testing files**
+
+- The GeoPackage testing file was copied from [github.com/ngageoint/geopackage-js](https://github.com/ngageoint/geopackage-js/blob/master/test/fixtures/rivers.gpkg)