Add documentation about OSM adapter or some examples

[MurzNN]

In PR https://github.com/phayes/geoPHP/pull/125 you've described the OSM adapter feature, can you please explain what it is and how to use it? I'm searching the way to convert OSM relation object (from Overpass reply with geom) to GeoJSON or WKT, to get boundary polygon - is it possible with your improvements? If not, can you recommend me other PHP libs, that can do this? Thanks!

[MurzNN]

Here https://github.com/tyrasd/osmtogeojson is JS library, that do this "magic", and it is used on Overpass Turbo frontend. Will be good to have same library on PHP language...

[MurzNN]

Now I've solved this task via launching Node.js script from PHP via subprocess:

use Symfony\Component\Process\Exception\ProcessFailedException;
use Symfony\Component\Process\Process;

  function osmToGeojson(object $element) {
    // Needs the `yarn global add osmtogeojson` system action.
    $process = new Process(['osmtogeojson']);
    $process->setInput(json_encode($element));

    try {
      $process->run();
      $output = $process->getOutput();
      $elementGeojson = json_decode($output);
    }
    catch (ProcessFailedException $exception) {
      throw new \Exception('Error converting OSM element to GeoJSON using osmtogeojson executable', 0, $exception);
    }
    return $elementGeojson;
  }

But this is disgusting solution :(

[BathoryPeter]

OSM adapter was an initial attempt, which I never completed. Beyond that I really like OSM, converting its data is full of difficulties. I mean for example the closed way conversion which depends on tagging.

Unfortunately I have less and less time for my OSS projects, but if someone would work on improving OSM adapter, I would happy to help.

I don't remember the details about the completeness, but I left comments in OSM.php:

This adapter is not ready yet. It lacks a relation writer, and the reader has problems with invalid multipolygons Since geoPHP doesn't support metadata, it cannot read and write OSM tags. (Note: since then I added metadata support, so we can extend the adapter with it.)

But you can give it a try. Just use the usual geoPHP::read($osmFile, 'osm') and geoPHP::write($geometry, 'osm') methods to load and create OSM files.