Looking for some opinions/advice on how hkit should be developed
moving forward.
One of my goals with hkit was always to make the interface (and here I
guess I'm primarily talking about the output from a parse) easy to use
for a php coder of pretty much any level. I can recall countless times
when I've downloaded some library or other only to find that so little
thought has gone into designing the interface that it's easier to
write my own version than to figure out how to use the library. Partly
that comes down to documentation and tutorials, but also it comes down
to design and using the simplest thing possible.
This is why hkit outputs a simple array structure, and not a bunch of
oblique objects. Any novice can print_r() the output and understand
what they're dealing with. The other advantage is that it becomes
trivial to convert that array into json - something that is essential
to maintain.
That said, as we add more features to the parser, it becomes more of a
challenge to keep the interface simple.
I'm trying to figure out the best way to present the @rel values that
accompany a URL. At present, when an A element with the class of URL
is found (primarily hCard) the value is represented as:
This is obviously very easy to consume. However, if there are
accompanying rel values we have nowhere to show those. Taking the next
leap, we could change the interface to represent URL as an array:
The downside here is that for simple cases where $result['url'] would
have done, $result['url']['value'] must be used.
Am I worrying too much? I think the tradeoff of the extra complexity
for simple cases is worth it for the added utility. As hkit users,
would you agree?
> Looking for some opinions/advice on how hkit should be developed > moving forward.
> One of my goals with hkit was always to make the interface (and here I > guess I'm primarily talking about the output from a parse) easy to use > for a php coder of pretty much any level. I can recall countless times > when I've downloaded some library or other only to find that so little > thought has gone into designing the interface that it's easier to > write my own version than to figure out how to use the library. Partly > that comes down to documentation and tutorials, but also it comes down > to design and using the simplest thing possible.
> This is why hkit outputs a simple array structure, and not a bunch of > oblique objects. Any novice can print_r() the output and understand > what they're dealing with. The other advantage is that it becomes > trivial to convert that array into json - something that is essential > to maintain.
> That said, as we add more features to the parser, it becomes more of a > challenge to keep the interface simple.
> I'm trying to figure out the best way to present the @rel values that > accompany a URL. At present, when an A element with the class of URL > is found (primarily hCard) the value is represented as:
> This is obviously very easy to consume. However, if there are > accompanying rel values we have nowhere to show those. Taking the next > leap, we could change the interface to represent URL as an array:
> The downside here is that for simple cases where $result['url'] would > have done, $result['url']['value'] must be used.
> Am I worrying too much? I think the tradeoff of the extra complexity > for simple cases is worth it for the added utility. As hkit users, > would you agree?
On Jan 15, 7:13 pm, "Jeff McNeill" <j...@jeffmcneill.com> wrote:
> Great effort here. I am wondering if both could be supported?
Both as an option, or only an array when rel values are present?
My concern there would in be making the interface predictable. If URL
can sometimes be just a value and sometimes an array with a 'value'
key, the user needs to write code that expects that (or fail to do so
and have their code break).
> On Jan 15, 7:13 pm, "Jeff McNeill" <j...@jeffmcneill.com> wrote:
> > Great effort here. I am wondering if both could be supported?
> Both as an option, or only an array when rel values are present?
> My concern there would in be making the interface predictable. If URL > can sometimes be just a value and sometimes an array with a 'value' > key, the user needs to write code that expects that (or fail to do so > and have their code break).
On 1/17/08, Drew McLellan <drew.mclel...@gmail.com> wrote:
> Does anyone have any further thoughts on this? Is it ok to change the > interface and potentially make it harder for current users to upgrade?
> I'm all for it at the moment, with a view to locking things down for > version 1.0.
That sounds sensible. With more eyes on the problem the interface is likely to want to change a little - but aiming for a stable API for a version 1.0 release is a good plan.
If this topic is still open, I would suggest supporting both, in a
predictable way. In the 'url' field, put an array with all the URLs as
you explained. If there happens to be just one, then also populate a
field 'single_url' with that URL. In many use cases, the caller will
know whether to expect just one, and can use the shortcut 'single_url'
if so. Callers who aren't certain that there will be just one can
consistently use 'url'.
