By shaharrt on
Hi,
All over drupal.org there are code snippets that are querying the database directly for table schemes of core/contributed modules. This seems like a bad thing to do since the scheme can be changed and then everything might break. If modules don't define a clean interface for their functionality then you have to resort to direct database queries.
For example - How can I load only blog entries which were created on the second week of last month?
what do you think about this issue?
Comments
You are quite right
Many of the snippets are 'bad practice' due to the way they get into the guts like that.
I went looking for some general-case answers, and found sticky code, so got a bit turned off.
I understand that the snippets are just there for quick-and-dirty examples.
I appreciate that in some cases a quick SQL select may in fact do a better job, simpler AND more powerfully that using the proper mechanism. ... But it breaks things!
The appropriate APIs DO actually exist in there somewhere, but they are hard to find unless you actually step through the code yourself. It's partly documentation, partly the ability to phrase exactly what you want to do, and find the right terminology to seach the docs for.
Usually it means selecting a bit more than you really wanted, then trimming down (or cross-referencing) by hand with a couple of loops. I don't have a simple answer to your query, but I agree with you, and I think the snippets repository would be better if it highlighted the proper use of existing API, and had big warnings next to anything that accessed 'private' code.
.dan.
.dan. is the New Zealand Drupal Developer working on Government Web Standards
Module APIs
I don't see an official way for a module to publish its own API. The rules, as I understand them, are:
modulename_functionname() = presumed to be a hook call; don't code anything in this namespace that isn't a documented hook.
_modulename_functionname() = presumed to be private to the module in question.
Am I'm missing something obvious? I suppose a module developer could document a private function to be publicly available.
The author of a contributed module generally takes the straightest line to his/her goal and doesn't consider that others might want a ride. Often I see code inlined in a horrendously long all-purpose callback that might be really useful to other modules or snippets.
Yeah, just documentation
I think you are missing something -
modulename_hookname() are the hook implimentations you shouldn't mess with the interface of (although nothing should stop you calling them yourself if you want)
_modulename_privatefunctions() are indeed to be left alone if possible,
but that leaves
modulename_functionnames() as basically public. Do what thou wilt shall be the whole of the law. Try as much as possible to use the module-makers way of getting at stuff, but NOT by copy & paste.
The 'API' may not exactly be 'published', but it is public and available for use.
The documentation generation should support this, and does in some setups, but no, I haven't seen it enabled for the contributed modules. It really should be - currently clicking on 'documentation' in the module project pages just gets a readme. Should be much more like the PEAR repository, I think.
.dan.
.dan. is the New Zealand Drupal Developer working on Government Web Standards
But ...
As far as I can see, that works up until I write a module defining modulename_foo() and then six months later the core hook system gets an interesting extension named hook_foo(). If that's really, really rare, then perhaps I have little to worry about -- except to pay attention to the hooks that are already defined.
True enough
OK, you have a point, but I don't think you need to worry about that much. Even the 'hooks' are broken down into subcategories, and only called when really neccessary.
Many functions that may look like hooks (eg *_admin() : block_admin(), forum_admin(), path_admin()) are really just convention - you still have to call them by name yourself in the hook_menu, so
A: you can actually name them anything
B: they will not be called by accident
Use nice descriptive, specific function names and the odds are really against it ever causing a problem. I predict that most extension development will be shaped more like an extra op to a nodeapi call (and similar - hook_block()) rather than top-level hook declaration.
If you are super-paranoid, modulename_modulename_functionname() will protect you, but please don't.
.dan.
.dan. is the New Zealand Drupal Developer working on Government Web Standards