egeloen/ivory-google-map — pull request #95 by egeloen (2014-10-19 20:54:58+00:00)
Title: [2.0] Refactor core

# Here we are!

The 2.0 version is not only on my computer but is on GitHub too. It is fully working and fixes #46, #53, #86, #87, #89 and probably #88 :) All I have still some parts to tweak but the major changes have already be applied.

# What is new?

Basically, there is not many new features but this release fixes some architecture problems which does not allow to archive some simple use case such as rendering multiple maps on the same page... Additionally, some parts have been refactored in order to ease further feature additions. Anyway, there is some new features such as:

* Debugging mode
* Code indentation
* Native Symfony2 container support
* Automatic coordinate no wrap.
* InfoBox/InfoWindow in the same map.

Additionally, no google map features have been dropped.

# What are the changes?

## Dependencies

The Symfony2 event dispatcher is now mandatory and the [`widop/http-adapter`](https://github.com/widop/http-adapter) has been replaced by the [`egeloen/http-adapter`](https://github.com/egeloen/ivory-http-adapter) which follows the [PSR-7 standard](https://github.com/php-fig/http-message).

Additionally, the Symfony2 dependency injection can be used natively and the library is still compatible with [`willdurand/geocoder`](https://github.com/geocoder-php/Geocoder) :)

## Model changes

### Places autocomplete

* The html container id now uses the javascript variable as default value.

### Map

* The html container id now uses the javascript variable as default value.
* The auto zoom have move from `Ivory\GoogleMap\Map::$autoZoom` to `Ivory\GoogleMap\Overlays\Overlays::$autoZoom`.
* The async mode has been dropped as for now, everything is loaded async by default (but I'm thinking to reintroduce it latter).

### Controls

* All controls have been moved from the map to a dedicated object (`Ivory\GoogleMap\Controls\Controls`) available through the map (`$map->getControls()`).
* All controls collection available through `ControlClass::get*()` have been dropped.
* The `Ivory\GoogleMap\Controls\ScaleControl::$controlPosition` has been dropped as it is no more supported.

### Overlays

* All overlays have been moved from the map to a dedicated object (`Ivory\GoogleMap\Overlays\Overlays`) available through the map (`$map->getOverlays()`).

### Layers

* All layers have been moved from the map to a dedicated object (`Ivory\GoogleMap\Layers\Layers`) available through the map (`$map->getLayers()`).

### Events

* The `Ivory\GoogleMap\Events\DomEvent` has been introduced in order to specialize the dom event instead of using an event. Accordingly, the `Ivory\GoogleMap\Events\Event::$capture` property has been dropped.

### Base

* The coordinate no wrap property is now automatically handled.

### Extends

* The extends have moved from `Ivory\GoogleMap\Base\Bound::extends` to `Ivory\GoogleMap\Overlays\Overlays::$extends`.

### Setter exceptions

All POPO setter's exception have been removed. All is documented, so, it is your responsibility to pass what is documented, so, no need to check everything, everywhere making lot of code duplication and not easily readable...

### Function prototypes

All `func_get_args` which allow to use multiple function prototypes have been dropped. For example, before you could do:

``` php
$map->setCenter(1.3, 2.4)
```

In this example, the map auto generates a coordinate object for you but it results to a lot of code duplication in all setters and make the code really not readable... Then, now, you will need to do:

``` php
$map->setCenter(new Coordinate(1.3, 2.4));
```

The same goes for all setter in all objects.

### Renaming

* The `Ivory\GoogleMap\Assets\AbstractJavascriptVariableAsset` has been renamed to `Ivory\GoogleMap\Assets\AbstractVariableAsset` and these getters/setters have been renamed accordingly.
* The `Ivory\GoogleMap\Overlays\MarkerImage` has been renamed to `Ivory\GoogleMap\Overlays\Icon` and all getters/setters in the library have been renamed accordingly.
* The `Ivory\GoogleMap\Events\EventManager` has been renamed to `Ivory\GoogleMap\Events\Events`.
* The `Ivory\GoogleMap\Layers\KMLLayer` has been renamed to `Ivory\GoogleMap\Layers\KmlLayer`.
* The `Ivory\GoogleMap\Services\Utils\XmlParser` has been renamed to `Ivory\GoogleMap\Services\XmlParser`.

## Helper changes

The helpers namespace has been totally rewritten... So, as you can understand, it is the main BC break. It has been rewritten for two reasons:

* Decouple the api rendering from the map/places autocomplete rendering. As spotted in #87 (not possible to use places autocomplete and map in the same page) or in #89 (not possible to use multiple maps on the same page) or it was not possible to use multiple places autocompletes on the same page, the api rendering should be decoupled from the map/places autocomplete rendering because the api rendering can't know there is an other elements to load when the first one is rendered...

* Allow to easily hook into the rendering in order to easily override or add some code where you want. #53 stopped the rendering was overkill with a very deep composition... Basically, as the graph object was pretty udge, each renderer constructor was insane...

In order to solve these first issue, I have decided to introduce an new helper allowing to render the api by passing the multiple maps, places autocomplete which are rendered in the page. Obviously, the api rendering has been removed from the other helpers. Then, the api rendering will be aware of all the google map elements which need to be loaded and so, the first main issue is fixed :)

For the second issue, it was a little bit more complicated (and long to implement...). How to allow to hook where you want in the rendering process? The Symfony2 event dispatcher to the rescue! Basically, all parts of the rendering process are represented by an event which are triggered by the helper. Then, an event allows you to add code or other resources (depending of the helper used). Then, you can hook where you want in the process, and it is really easy to add new features :)

In order to give you the helper configured with all the core subscribers, you will need to use the helper factory which can be either a plain php one or one using the symfony2 container.

## What is missing ?

- [ ] Apply some tweaks
- [ ] Review the code
- [ ] Update doc
- [ ] Update `UPGRADE.md`

Enjoy!