From 658cecf5ca39a80810e7dc1fcfd7e6d1e4d0d98b Mon Sep 17 00:00:00 2001 From: broiniac Date: Sat, 17 Nov 2018 13:19:41 +0100 Subject: [PATCH] Doc fixes (#209) * doc: trim whitespaces * doc: fix "Back to documentation index" links * doc: fix code block opening tag --- Resources/doc/cache.md | 20 +++++++------- Resources/doc/custom-provider.md | 10 +++---- Resources/doc/doctrine.md | 6 ++--- Resources/doc/index.md | 46 ++++++++++++++++---------------- Resources/doc/plugins.md | 20 +++++++------- Resources/doc/services.md | 10 +++---- 6 files changed, 56 insertions(+), 56 deletions(-) diff --git a/Resources/doc/cache.md b/Resources/doc/cache.md index b114a4c3..11a3f09d 100644 --- a/Resources/doc/cache.md +++ b/Resources/doc/cache.md @@ -1,10 +1,10 @@ # Caching the geocoder response -*[<< Back to documentation index](Resources/doc/index.md)* +*[<< 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 +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. +by default in our configuration. ```yaml # config.yml @@ -18,17 +18,17 @@ bazinga_geocoder: ``` If you do a lot of reverse queries it can be useful to cache them with less precision. So if you are interested in only the city, -you don't want to query for every exact coordinate. Instead, you want to remove some precision of the coordinates. For example: -reversing `52.3705273, 4.891031` will be cached as `52.3705, 4.8910`. +you don't want to query for every exact coordinate. Instead, you want to remove some precision of the coordinates. For example: +reversing `52.3705273, 4.891031` will be cached as `52.3705, 4.8910`. 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. +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. +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 @@ -52,7 +52,7 @@ servies: ## Installing a PSR16 cache -You may use any adapter from [PHP-cache.com](http://www.php-cache.com/en/latest/) or `symfony/cache`. +You may use any adapter from [PHP-cache.com](http://www.php-cache.com/en/latest/) or `symfony/cache`. ## Using Symfony cache @@ -87,7 +87,7 @@ bazinga_geocoder: cache_precision: 4 ``` -For older Symfony version, you can use a bridge between PSR-6 and PSR-16. Install the +For older Symfony version, you can use a bridge between PSR-6 and PSR-16. Install the [bridge](https://github.com/php-cache/simple-cache-bridge) by: ```bash diff --git a/Resources/doc/custom-provider.md b/Resources/doc/custom-provider.md index da0c59bb..da856fbf 100644 --- a/Resources/doc/custom-provider.md +++ b/Resources/doc/custom-provider.md @@ -1,6 +1,6 @@ # Registering Your Own Providers -*[<< Back to documentation index](Resources/doc/index.md)* +*[<< 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`: @@ -12,7 +12,7 @@ If you want to use your own provider in your application, create a service, and ``` 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). +show up the the web profiler because it is not registered with the [PluginProvider](/Resources/doc/plugins.md). If you want your provider to show up the web profiler you have to create a custom factory for your provider. @@ -26,17 +26,17 @@ 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: diff --git a/Resources/doc/doctrine.md b/Resources/doc/doctrine.md index 0168ce24..c7a1a20f 100644 --- a/Resources/doc/doctrine.md +++ b/Resources/doc/doctrine.md @@ -1,12 +1,12 @@ # Doctrine annotation support -*[<< Back to documentation index](Resources/doc/index.md)* +*[<< Back to documentation index](/Resources/doc/index.md)* -Wouldn't it be great if you could automatically save the coordinates of a users +Wouldn't it be great if you could automatically save the coordinates of a users address every time it is updated? Wait not more here is the feature you been always wanted. -``` php +```php use Bazinga\GeocoderBundle\Mapping\Annotations as Geocoder; diff --git a/Resources/doc/index.md b/Resources/doc/index.md index f838b611..cc8b31fc 100644 --- a/Resources/doc/index.md +++ b/Resources/doc/index.md @@ -31,7 +31,7 @@ Installation ------------ To install this bundle you need to know how to [install the geocoder and providers](https://github.com/geocoder-php/Geocoder#installation) -and then you may just install the bundle like normal: +and then you may just install the bundle like normal: ```bash composer require willdurand/geocoder-bundle:^5.0 @@ -53,9 +53,9 @@ public function registerBundles() Usage ----- -The bundle helps you register your providers and to enable profiling support. To +The bundle helps you register your providers and to enable profiling support. To configure a provider you must use a `ProviderFactory`. See the following example -using Google Maps. +using Google Maps. ```yaml bazinga_geocoder: @@ -64,10 +64,10 @@ bazinga_geocoder: factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory ``` -This will create a service named `bazinga_geocoder.provider.acme` which is a +This will create a service named `bazinga_geocoder.provider.acme` which is a `GoogleMapsProvider`. -You can also configure **all ``ProviderFactories``** to adjust the behavior of the +You can also configure **all ``ProviderFactories``** to adjust the behavior of the provider. ```yaml @@ -77,14 +77,14 @@ bazinga_geocoder: factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory cache: 'any.psr16.service' cache_lifetime: 3600 - aliases: + aliases: - my_geocoder ``` -This will create a service named `my_geocoder` that caches the responses for one +This will create a service named `my_geocoder` that caches the responses for one hour. -**Most ``ProviderFactories``** do also take an array with options. This is usually +**Most ``ProviderFactories``** do also take an array with options. This is usually parameters to the constructor of the provider. In the example of Google Maps: ```yaml @@ -92,7 +92,7 @@ bazinga_geocoder: providers: acme: factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory - options: + options: httplug_client: '@httplug.client' # When using HTTPlugBundle region: 'Sweden' api_key: 'xxyy' @@ -177,7 +177,7 @@ If set, the parameter will replace all instances of "127.0.0.1" in your queries 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. +service and you are good to go. ```yaml bazinga_geocoder: @@ -234,10 +234,10 @@ To register a new dumper, you must tag it with `bazinga_geocoder.dumper`. ### Custom HTTP Client The HTTP geocoder providers integrates with [HTTPlug](http://httplug.io/). It will give you all -the power of the HTTP client. You have to select which one you want to use and how -you want to configure it. +the power of the HTTP client. You have to select which one you want to use and how +you want to configure it. -Read their [usage page](http://docs.php-http.org/en/latest/httplug/users.html), you +Read their [usage page](http://docs.php-http.org/en/latest/httplug/users.html), you may also be interested in checking out the [HTTPlugBundle](https://github.com/php-http/HttplugBundle). An example, if you want to use Guzzle6. @@ -251,16 +251,16 @@ Reference Configuration You'll find the reference configuration below: -``` yaml +```yaml # app/config/config.yml bazinga_geocoder: - profiling: + profiling: enabled: ~ # Default is same as kernel.debug fake_ip: enabled: true ip: null providers: - # ... + # ... acme: factory: ~ # Required cache: 'app.cache' @@ -269,9 +269,9 @@ bazinga_geocoder: limit: 5 locale: 'sv' logger: 'logger' - plugins: + plugins: - my_custom_plugin - aliases: + aliases: - acme - acme_geocoder options: @@ -290,15 +290,15 @@ Backwards compatibility ----------------------- The BazingaGeocoderBundle is just a Symfony integration for Geocoder-PHP and it -does not have any classes which falls under the BC promise. The backwards compatibility +does not have any classes which falls under the BC promise. The backwards compatibility of the bundle is only the configuration and its values (and of course the behavior of those values). The public service names (excluding the ones related to profiling/DataCollector) -falls under the backwards compatibility promise. +falls under the backwards compatibility promise. -Bottom line is, that you can trust that your configuration will not break and that -the services you use will still be working. +Bottom line is, that you can trust that your configuration will not break and that +the services you use will still be working. Testing ------- @@ -320,7 +320,7 @@ Traivs but if you want to run it locally you must do the following. composer require phpunit/phpunit:^5.7 --no-update composer update --prefer-source wget https://phar.phpunit.de/phpunit-5.7.phar -php phpunit-5.7.phar --testsuit doctrine +php phpunit-5.7.phar --testsuit doctrine ``` **Important:** this command must be run with `--prefer-source`, otherwise the diff --git a/Resources/doc/plugins.md b/Resources/doc/plugins.md index 30037151..c6d39d95 100644 --- a/Resources/doc/plugins.md +++ b/Resources/doc/plugins.md @@ -1,9 +1,9 @@ # Plugins -*[<< Back to documentation index](Resources/doc/index.md)* +*[<< 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. +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 @@ -17,17 +17,17 @@ bazinga_geocoder: 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`. +may then use the `QueryDataPlugin`. ```yaml # services.yml -sevices: +sevices: app.query_data_plugin: class: Geocoder\Plugin\Plugin\QueryDataPlugin - arguments: + arguments: - ['foo': 'bar'] - true ``` @@ -38,10 +38,10 @@ bazinga_geocoder: providers: acme: factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory - plugins: + 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). +Read more about plugins at the [Geocoder's documentation](https://github.com/geocoder-php/Geocoder). diff --git a/Resources/doc/services.md b/Resources/doc/services.md index 788f505c..38f0fa0d 100644 --- a/Resources/doc/services.md +++ b/Resources/doc/services.md @@ -1,12 +1,12 @@ # Public services -*[<< Back to documentation index](Resources/doc/index.md)* +*[<< Back to documentation index](/Resources/doc/index.md)* -This is a list of our public services. They are all part of [BC promise](Resources/doc/index.md#backwards-compatibility). +This is a list of our public services. They are all part of [BC promise](/Resources/doc/index.md#backwards-compatibility). ### Provider Factories -Here is a list of all provider factories and their options. +Here is a list of all provider factories and their options. | Service | Options | | ------- | ------- | @@ -15,7 +15,7 @@ Here is a list of all provider factories and their options. | `Bazinga\GeocoderBundle\ProviderFactory\ChainFactory` | services | `Bazinga\GeocoderBundle\ProviderFactory\FreeGeoIpFactory` | httplug_client, base_url | `Bazinga\GeocoderBundle\ProviderFactory\GeoIP2Factory` | provider, database_filename, user_id, license_key, webservice_options, locales, provider_service -| `Bazinga\GeocoderBundle\ProviderFactory\GeoipFactory` | +| `Bazinga\GeocoderBundle\ProviderFactory\GeoipFactory` | | `Bazinga\GeocoderBundle\ProviderFactory\GeoIPsFactory` | httplug_client, api_key | `Bazinga\GeocoderBundle\ProviderFactory\GeonamesFactory` | httplug_client, username | `Bazinga\GeocoderBundle\ProviderFactory\GeoPluginFactory` | httplug_client @@ -36,7 +36,7 @@ Here is a list of all provider factories and their options. ### Services -Except for the provider factories, here is a list of services this bundle exposes are: +Except for the provider factories, here is a list of services this bundle exposes are: * `Geocoder\ProviderAggregator` * `Geocoder\Dumper\GeoArray`