KML Docs, Examples, Tutorial, Schema & Classes

[TJ1]

I've recently created a comprehensive KML class for PHP that creates and manages KML XML documents, can output KML plain text or KMZ gzipped data. It supports sending data directly to the Google Earth client, or providing it for download from a web page as KML or KMZ.

Many people seem more interested in the associated KML Documentation, Examples, and Tutorial

The class provides each KML element with its own createXXXX() method, has composite buildXXX() methods for making common tag structures (Placemarks, NetworkLinks, etc.).

Most importantly it has internal consistency checking matrices to ensure that only legal parent-child relationships are permitted, so its impossible to inadvertently create a Placemark as the child of a Simple tag, for example.

A KML XML Schema is evolving from it, auto-generated (again by the class) as it gets more sophisticated

This means its hard to send the Google Earth client a KML file that will cause an error on loading, saving valuable time and enhancing user experience.

As a bonus, the internal modelling of the KML tag relationships means that in two lines of code the entire relationship can be displayed - *very* useful for developing valid KML quickly and making sure you make use of all the features.

KML Schema, DTD, and PHP classes

TJ

[TJ1]

I've now added the 'newly discovered' (well, for me anyhow!) MultiGeometry, MultiLineString, MultiPoint and MultiPolygon to the class.

[TJ1]

I've now added a DTD into the mix.

Both the Schema and the DTD are validating in the PHP 5.0.x XMLLIB2 parser and with XML Spy.

Both documents need some refinement, but they're solid right now and mainly its the Schema that needs its restrictions on data types tightening up.

TJ.

[TJ1]

I've updated my KML Reference with the new KML 2.0 tags, comprehensive examples and a tutorial KML file.

[xav]

TJ1

Your KML Reference is great!
This should be a separate Topic so that it can be found easier.

I found some minor bugs:

Documentation:
Just change "snippet" to "Snippet"

Examples:
1) The <NetworkLinkControl> tag is not closed (it ends with another opening tag)
2) The example that can be downloaded has "&" instead of "&amp;" at the end (The HTML page with the examples is correct)

Keep up the good work

xav.

[TJ1]

Thanks Xav. I wrote it mostly for myself to ensure that my KMLDocument classes can create and work to a avalid schema.

I've corrected those typing mistakes in the exmaples and tutorial download. I couldn't find the snippet reference you made - it is a simple tag so the convention is it begins with a lower-case letter.

Eventually I hope to have an example of every tag in the tutorial, too, but I've got real work going onas well so I only add to that for fun

[xav]

You are right that Snippet should begin with a lowercase letter, but it doesn't. See this post .

Snippet also has an attribute "maxLines", see this post


Try it: <snippet> doesn't work but <Snippet> does.

xav

[TJ1]

Well-spotted xav!

I guess it'll teach me that reading and believing the documentation is not going to get me top marks in the KML exams

I've updated my KML docs and my web-application's Snippets are suddenly working

[TJ1]

I'm looking for beta-testers for my KMLDocument PHP classes, based on the PHP DOMDocument class.

If you're working with KML in a PHP environment, my KMLDocument class allows you to create, manipulate, and output fully validated KML documents for inline or download use, in uncompressed (KML) or GZIP compressed (KMZ) formats.

It's fully object oriented with many time-saving convenience features, and more likely to be added based on feedback.

Initially I would like people who are accomplished programmers and know their way around PHP, but once the testing is done I intend to release the classes to a wider audience.

You can check out the auto-generated documentation here, but beware it might sometimes be missing because I'm having issues with phpDocumentor creating empty docs occassionally when it regenerates them.

[Jason_Birch]

Is this PHP5 only?

[TJ1]

Poosibly

I've developed on PHP 5.0.4 and 5.0.5 and from things I've seen I'm guessing I'm using constructs that aren't supported in earlier versions.

Most importantly, I've used PHP5's DOM (libxml2) rather than PHP4's DOM_XML for modelling. If PHP4 can support libxml2 then there's a chance it will run.

I've not specifically written it to break PHP 4.x but I've just no need to test against it for my own purposes.

If you want to give it a try on 4.x, you're welcome. It's only a minor part of my current project work so I don't have much driving me to install PHP 4.x just to test it on.

[TJ1]

I've just completed the next revision (0.9.4 beta) of the PHP classes after solving some major problems with PHP's DOM and class/object handling.

They're now elegant and naturally follow the DOM with no awkward kludges to get around holes in the PHP DOM implementation

There are now three classes:

KMLElement
KMLDocument
KMLSchema

Tested on PHP 5.05 and 5.1RC4. The updated docs are at KML PHP Class API Reference

If you'd like to beta-test them let me know.

[TJ1]

I've started adding convenience methods for creating complex constructs easily.

I've added drawRectangle() and buildCoordinates() and am starting on drawCircle(), drawEllipse(), and other similar functions.

If you have suggestions for what you'd like to see let me know now so it can be implemented in time for version 1.0 of the package being released in a week or so.

[TJ1]

Added support and updated KML reference for the new linkSnippet tag in client version 3.0.0739

[TJ1]

And as a special Sunday afternoon treat I've just completed KMLSchema.php's DTD dynamic generator.

It generated the first comprehensive W3C DTD based on the internally validating Schema, which I've subsequently converted to W3C XML Schema (XSD) and RelaxNG Schema with trang.

Find them at the usual place.

[TJ1]

I've added support for all three (both Schemas and DTD) to the KML Validator and moved it out of alpha-test so its ready to work with real-world KML documents.

If you use it, bear in mind the caveat that elements in the KML must be in the same order as specified in the Schemas or else it will fail to validate.

I'm working on ways to provide unordered definitions in the Schemas but its a complicated business because, except for Relax NG, they don't easily support the concept. The way around it is to provide repeated choices with a zero-or-one modifier but it makes generating the Schemas much more involved.

As a sneaky workaround I'm writing a new function for my KMLDocument class that will re-order the elements in the KMLDocument so they match the Schemas.

So, even with a valid KML document that fails validation, if you load it into KMLDocument and call the orderForValidation() method, it will then validate.

After thats proved I'll add internal functionality that ensures all elements added to KMLDocument are placed in validation-order (that means KMLElement->appendChild() will do an arbitary insertChild() at a location in the NodeList that matches the Schema.