docs(readme): document what the parser returns

[danielebarbaro]

Problem

The README listed the methods and stopped there:

// Get placemarks (points of interest)
$placemarks = $parser->getPlacemarks();

It never said what comes back. The only way to find out the shape of a placemark, a style, or a GeoJSON feature was to run the parser and dd() it. There are no DTOs and no return-type information beyond array, so nothing else fills that gap either.

It also never said which parts of KML are actually handled. That was already a problem, and the recent work made it worse: MultiGeometry, LineStyle, PolyStyle and SchemaData/SimpleData all landed, and nobody reading the README would know. Meanwhile Folder, NetworkLink and the overlays still do nothing, and nobody would know that either. The failure mode is someone downloading the package, feeding it a file whose data quietly does not come back, and giving up.

What was added

• Supported KML elements table. Everything parsed, and everything ignored, in one place. Plus the note that ignored elements are ignored rather than rejected, so those documents still parse.
• The exact array shape of every getter, taken from real parser output rather than written from memory: getPlacemarks() for each geometry type, getStyles(), getStyleMaps(), toGeoJson().
• Accepted namespaces, and how to add one.
• Error handling, with a table of the three exception types and when each is thrown, plus the fact that everything extends KmlException so one catch covers it.
• KMZ section expanded, including the warning that extractAllFiles() writes whatever the archive holds.

The parts people get wrong

Called out explicitly, because each one is a plausible source of a bug in calling code:

• A MultiGeometry placemark has geometries, not coordinates. Reaching for $placemark['coordinates'] without checking type first is now an undefined index rather than a missing feature.
• An absent style key means the file said nothing, not that the value is the KML default. The parser does not fill defaults in.
• Colours are the raw KML aabbggrr string. Alpha first, blue before red. Handing that to a CSS colour function gives you the wrong colour, not an error.
• The facade binding is scoped, so a later KmlParser::getPlacemarks() does not necessarily see what an earlier separate call loaded. Chain the calls or hold the instance.

One inaccuracy found while writing this

altitude comes back as a float when the coordinate declares it and as an int 0 when it does not:

'altitude' => isset($parts[2]) ? (float) $parts[2] : 0,

The docblock on parsePointCoordinates() claims altitude: float. The README documents the current behaviour (0, not 0.0) rather than the intended one. Not fixed here to keep this PR to documentation. Small follow-up.

CONTRIBUTING.md

The README has linked to CONTRIBUTING.md since the first release and the file has never existed. Added, covering how to report a bug with a reproducing document, how to ask for a KML element, the three commands CI runs, and the request to write the failing test first and to call out array-shape changes since those break callers without breaking tests.

Verification

Every shape in the README was produced by running the parser on a document exercising all of it, not written from memory. Claims about requirements, config keys and composer scripts checked against composer.json and config/kml-parser.php. Suite still 62 passing.