Updating the documentation for 5.0 (#158)

* Putting the documentation to sections

* Added docs about custom provider

* Added info about plugins

* Updated links

* fixed typo

Author: Nyholm

Resources/doc/cache.md

@@ -0,0 +1,50 @@
+# Caching the geocoder response
+
+*[<< Back to documentation index](Resources/doc/index.md)*
+
+It is quite rare that a location response gets updated. That is why it is a good idea to cache the responses. The second 
+request will be both quicker and free of charge. To get started with caching you may use the `CachePlugin` which is supported
+by default in our configuration. 
+
+```yaml
+# config.yml
+bazinga_geocoder:
+  providers:
+    acme:
+      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
+      cache: 'any.psr16.service'
+      cache_lifetime: 3600
+```
+
+You may use any [PSR16](http://www.php-fig.org/psr/psr-16/) cache [implementation](https://packagist.org/providers/psr/simple-cache-implementation).
+The `CachePlugin` helps you to cache all responses. 
+
+## Decorator pattern
+
+If you do not like using the `CachePlugin` for some reason you may use the [`CacheProvider`](https://github.com/geocoder-php/cache-provider).
+The `CacheProvider` is using the [Decorator pattern](https://en.wikipedia.org/wiki/Decorator_pattern) to do caching. Which 
+means that you wrap the `CacheProvider` around your existing provider. 
+
+```bash
+composer require geocoder-php/cache-provider
+```
+
+```yaml
+# config.yml
+bazinga_geocoder:
+  providers:
+    acme:
+      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
+```
+
+```yaml
+# services.yml
+servies:
+  my_cached_geocoder:
+    class: Geocoder\Provider\Cache\ProviderCache
+    arguments: ['@bazinga_geocoder.provider.acme', '@any.psr16.service', 3600]
+```
+
+## Installing a PSR16 cache
+
+You may use any adapter from [PHP-cache.com](http://www.php-cache.com/en/latest/) or `symfony/cache`. 

Resources/doc/custom-provider.md

@@ -0,0 +1,47 @@
+# Registering Your Own Providers
+
+*[<< Back to documentation index](Resources/doc/index.md)*
+
+If you want to use your own provider in your application, create a service, and tag it as `bazinga_geocoder.provider`:
+
+```xml
+<service id="acme_demo.geocoder.my_provider" class="Acme\Demo\Geocoder\Provider\MyProvider">
+    <argument type="service" id="foo_service" />
+    <tag name="bazinga_geocoder.provider" />
+</service>
+```
+
+The bundle will automatically register your provider into the`Geocoder\ProviderAggregator` service. However, it will not
+show up the the web profiler because it is not registered with the [PluginProvider](Resources/doc/plguins.md).
+
+If you want your provider to show up the web profiler you have to create a custom factory for your provider.
+
+```php
+namespace Acme\Demo\Geocoder\Factory;
+
+use Bazinga\GeocoderBundle\ProviderFactory\AbstractFactory;
+use Acme\Demo\Geocoder\Provider\MyProvider;
+use Acme\Demo\Service\Foo;
+
+final class MyFactory extends AbstractFactory
+{
+    private $fooService;
+    
+    public function __construct(Foo $service) {
+        $this->someService = $service;
+    }
+ 
+    protected function getProvider(array $config)
+    {
+        return new MyProvider($this->fooService);
+    }
+}
+``` 
+
+```yaml
+bazinga_geocoder:
+  providers:
+    acme:
+      factory: Acme\Demo\Geocoder\Factory\MyFactory
+      aliases: ['acme_demo.geocoder.my_provider']
+```

Resources/doc/index.md

@@ -1,19 +1,28 @@
 BazingaGeocoderBundle
 =====================
 
-Integration of the [**Geocoder**](http://github.com/geocoder-php/Geocoder)
-library into Symfony.
+Integration of the [**Geocoder**](http://github.com/geocoder-php/Geocoder) library into Symfony.
+
+Our documentation has the following sections:
+
+* [Index](index.md) (This page)
+* [Public services](services.md)
+* [Registering Your Own Provider](custom-provider.md)
+* [All about Cache](cache.md)
+* [Plugins](plugins.md)
+* [Doctrine support](doctrine.md)
+
+Table of contents
+-----------------
 
 * [Installation](#installation)
 * [Usage](#usage)
   * [Fake local ip](#fake-local-ip)
-  * [Registering Your Own Provider](#registering-your-own-provider)
-  * [Dumpers](#dumper)
   * [Cache](#cache-results)
+  * [Dumpers](#dumper)
   * [Custom HTTP clients](#custom-http-clients)
-* [Doctrine support](Resources/doc/doctrine.md)
-* [Public services](Resources/doc/services.md)
 * [Reference Configuration](#reference-configuration)
+* [Backwards compatibility](#backwards-compatibility)
 * [Testing](#testing)
 
 
@@ -132,22 +141,22 @@ bazinga_geocoder:
 If set, the parameter will replace all instances of "127.0.0.1" in your queries and replace them with the given one.
 
 
-### Registering Your Own Providers
+### Cache Results
 
-If you want to use your own provider in your application, create a service,
-and tag it as `bazinga_geocoder.provider`:
+Sometimes you have to cache the results from a provider. For this case the bundle provides
+simple configuration. You only need to provide a service name for you SimpleCache (PSR-16)
+service and you are good to go. 
 
-```xml
-<service id="acme_demo.geocoder.my_provider" class="Acme\Demo\Geocoder\Provider\MyProvider">
-    <tag name="bazinga_geocoder.provider" />
-</service>
+```yaml
+bazinga_geocoder:
+  providers:
+    acme:
+      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
+      cache: 'any.psr16.service'
+      cache_lifetime: 3600
 ```
 
-The bundle will automatically register your provider into the
-`Geocoder\ProviderAggregator` service. 
-
-If you want your provider to show up the web profiler you have to create a custom factory
-for your provider. 
+Read more about cache [here](cache.md).
 
 ### Dumpers
 
@@ -190,22 +199,6 @@ To register a new dumper, you must tag it with `bazinga_geocoder.dumper`.
 </service>
 ```
 
-### Cache Results
-
-Sometimes you have to cache the results from a provider. For this case the bundle provides
-simple configuration. You only need to provide a service name for you SimpleCache (PSR-16)
-service and you are good to go. 
-
-```yaml
-bazinga_geocoder:
-  providers:
-    acme:
-      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
-      cache: 'any.psr16.service'
-      cache_lifetime: 3600
-
-```
-
 ### Custom HTTP Client
 
 The HTTP geocoder providers integrates with [HTTPlug](http://httplug.io/). It will give you all
@@ -243,6 +236,8 @@ bazinga_geocoder:
             limit: 5
             locale: 'sv'
             logger: 'logger'
+            plugins: 
+                - my_custom_plugin
             aliases: 
                 - acme
                 - acme_geocoder

Resources/doc/plugins.md

@@ -0,0 +1,47 @@
+# Plugins
+
+*[<< Back to documentation index](Resources/doc/index.md)*
+
+Plugins lets you modify or take actions the `Query` or the result. There are a few plugins from the `geocoder-php/plugin` 
+package like `LimitPlugin`, `LoggerPlugin` and `CachePlugin`. Some of them are supported in the configuration. 
+
+```yaml
+# config.yml
+bazinga_geocoder:
+  fake_ip:
+    ip: '123.123.123.123' # Uses the FakeIpPlugin
+  providers:
+    acme:
+      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
+      cache: 'app.cache' # Uses the CachePlugin
+      limit: 5           # Uses the LimitPlugin
+      locale: 'sv'       # Uses the LocalePlugin
+      logger: 'logger'   # Uses the LoggerPlugin
+``` 
+
+To use a any other plugins you must first register them as a service. Say you want to add some data to each query. You
+may then use the `QueryDataPlugin`. 
+
+```yaml
+# services.yml
+sevices: 
+  app.query_data_plugin:
+    class: Geocoder\Plugin\Plugin\QueryDataPlugin
+    arguments: 
+      - ['foo': 'bar']
+      - true
+```
+
+```yaml
+# config.yml
+bazinga_geocoder:
+  providers:
+    acme:
+      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
+      plugins: 
+        - "app.query_data_plugin"
+``` 
+
+This will execute `$query = $query->withData('foo', 'bar');` on all queries executed by the acme provider.
+
+Read more about plugins at the [Geocoder's documentation](https://github.com/geocoder-php/Geocoder).