search

sabre-io / xml

sabre/xml is an XML library that you may not hate.
http://sabre.io/xml/
BSD 3-Clause "New" or "Revised" License
516 stars 77 forks source link

namespaces vs. clark notations #65

Closed staabm closed 8 years ago

staabm commented 8 years ago

After using the lib with a few examples I am getting the feeling that the API is very solid and usable but I got stuck in a certain trap several times.

In some situation I need to pass in a clark notation in some others the namespace as a url. IMO we could improve the developer experience by adding some asserts which fast throw errors in case someone mixed those 2 strings up. Maybe we could make sure that we consistantly use a var convention which helps the dev to not mix those 2 things ($clark vs. $namespace or similar). We could even handle clark notations in a separate object, but this feels a step too much right now.

(to be honest, I learned clark notation by using the lib... its a term which IMO is not present to everyone therefore would be great to be described somewhere or at least if the docs would link to a article which describes what clark notation actually is)

just a few thoughts to make this lib even better. lets discuss what you guys think.

example: Service->write expects arg1 to be given in clark notation. In case you provide just a "name" without a namespace it silently generates a xml which misses a <xml> document tag

evert commented 8 years ago

This is a very fair criticism.

Maybe we could make sure that we consistantly use a var convention which helps the dev to not mix those 2 things ($clark vs. $namespace or similar).

One issue is that for functions such as write, writeElement, startElement, they also all support a 'plain name', in which case we fall back on the default XMLWriter behavior (a namespaceless element). That's why for all of those it's just $name.

I just added a bunch of docs that hopefully help a bit, both in the docblocks and here:

http://sabre.io/xml/clark-notation/

Maybe another idea is to switch to a different notation-style altogether. I don't love clark-notation and there might be some other way to make it better...

staabm commented 8 years ago

Thanks for the new docs, appreciate that.

Nit: syntax highlighting does look right at http://sabre.io/xml/clark-notation/

I am not against clark notation, since I get used to it while playing with the lib. What are the alternatives to clark notation?

evert commented 8 years ago

Well one thing I hate is that it's a bit hard to parse... I was kind thinking about this today a bit and realized that this syntax is also possible:

$writer->write('http://namespace localName')

the space is not allowed in either the namespace uri nor the localName, and that gives us the nice benefit that explode() can be used to get both parts. We can somewhat easily add this to the writer (because we can support more than 1 syntax) but unfortunately making it the default in the reader would mean a major BC break...

but yea I guess we can postpone that decision. Can this be closed or are there more tasks?

staabm commented 8 years ago

Do you think it makes sense to sanity check the elementMap, classMap and namespaces before doing read/write in the Service class? That way we could report 'config errors' to the dev..