Convention for naming contrib hooks?

[arthur-56]

Hi-

Forgive me if this question is answered elsewhere- I've not found a  
comprehensive answer thus far.

With contrib modules sprawling ever more, it's extremely hard to keep  
track of what modules implement what kinds of hooks. For example, I  
got caught by file_field's hook_file_delete() when I implemented  
media_mover_api_file_delete() which had nothing to do with this hook.  
While I renamed my function, it's challenging at best to know the  
terrain. Is there a central place where contrib developers can list  
their hooks, or a naming convention that is agreed to that would help  
with this (eg: hook_HOOKNAME_HOOKMODULE() or something)?

thanks,

arthur

[Aaron Winborn-2]

Yes, that same issue w/ filefield caught me once too -- I believe it was
implemented earlier this year as an attempt to backport part of the File
API from core d7 to contrib d6.

I use hook_HOOKMODULE_HOOKNAME(), and see other modules doing that as
well, though I imagine there are some that use your suggestion as well;
your idea might be less likely to cause conflicts.

I'm aware of at least two contrib API doxygen scraping sites out there:
http://drupalcontrib.org/ and http://api.lullabot.com/ (and probably
others).

I agree that we should come up with a standard naming convention (if
there isn't one already).

Aaron

arthur wrote:

> Hi-
>
> Forgive me if this question is answered elsewhere- I've not found a
> comprehensive answer thus far.
>
> With contrib modules sprawling ever more, it's extremely hard to keep
> track of what modules implement what kinds of hooks. For example, I
> got caught by file_field's hook_file_delete() when I implemented
> media_mover_api_file_delete() which had nothing to do with this hook.
> While I renamed my function, it's challenging at best to know the
> terrain. Is there a central place where contrib developers can list
> their hooks, or a naming convention that is agreed to that would help
> with this (eg: hook_HOOKNAME_HOOKMODULE() or something)?
>
> thanks,
>
> arthur

--
Aaron Winborn

Advomatic, LLC
http://advomatic.com/

Drupal Multimedia available in September!
http://www.packtpub.com/create-multimedia-website-with-drupal/book

My blog:
http://aaronwinborn.com/

[Larry Garfield]

There's no central canonical list, since hooks are fairly free-form.
It's generally good practice to prefix a hook with the name of your
module if you're not a core module (hook_yourmodulenamehere_hookname()),
but that's not universal unfortunately.

--Larry Garfield

arthur wrote:

> Hi-
>
> Forgive me if this question is answered elsewhere- I've not found a
> comprehensive answer thus far.
>
> With contrib modules sprawling ever more, it's extremely hard to keep
> track of what modules implement what kinds of hooks. For example, I got
> caught by file_field's hook_file_delete() when I implemented
> media_mover_api_file_delete() which had nothing to do with this hook.
> While I renamed my function, it's challenging at best to know the
> terrain. Is there a central place where contrib developers can list
> their hooks, or a naming convention that is agreed to that would help
> with this (eg: hook_HOOKNAME_HOOKMODULE() or something)?
>
> thanks,
>
> arthur

[Nancy Wichmann]

Larry Garfield wrote:
> It's generally good practice to prefix a hook with the name of your
> module if you're not a core module

Gosh, it's kind of my thoughts that if it can't be found with
module_invoke_all(), then it's not a "hook" (an API maybe). And
module_invoke_all() won't find the function unless it starts with the module
name (core or contrib).

[Jennifer Hodgdon]

Aaron Winborn wrote:
> I use hook_HOOKMODULE_HOOKNAME(), and see other modules doing that as
> well, though I imagine there are some that use your suggestion as well;
> your idea might be less likely to cause conflicts.

That is an excellent suggestion, but as has been noted in other
replies, not all modules follow this suggestion. For instance, besides
the FileField example in the original post in this thread, there was a
problem with hook_diff() from the Diff module conflicting with an
unrelated function named location_diff() in the Location module, about
a year ago.

> I'm aware of at least two contrib API doxygen scraping sites out there:
> http://drupalcontrib.org/ and http://api.lullabot.com/ (and probably
> others).

Those sites will only help you find contrib hook documentation if the
module developers have created API documentation headers/files for
their hooks. Most do not bother.

    --Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

[Ken Winters]

On Oct 15, 2009, at 2:07 PM, Nancy Wichmann wrote:

> Larry Garfield wrote:
>> It's generally good practice to prefix a hook with the name of your
>> module if you're not a core module
>
> Gosh, it's kind of my thoughts that if it can't be found with
> module_invoke_all(), then it's not a "hook" (an API maybe). And
> module_invoke_all() won't find the function unless it starts with  
> the module
> name (core or contrib).
>

I believe they mean the actual hook name, rather than the  
implementation.  So,
the implementation should look something like this:

mymodule_cck_dosomething()

Where CCK defines the hook cck_dosomething() rather than just  
dosomething().

- Ken Winters

[Larry Garfield]

On Thursday 15 October 2009 1:18:27 pm Ken Winters wrote:

> On Oct 15, 2009, at 2:07 PM, Nancy Wichmann wrote:
> > Larry Garfield wrote:
> >> It's generally good practice to prefix a hook with the name of your
> >> module if you're not a core module
> >
> > Gosh, it's kind of my thoughts that if it can't be found with
> > module_invoke_all(), then it's not a "hook" (an API maybe). And
> > module_invoke_all() won't find the function unless it starts with
> > the module
> > name (core or contrib).
>
> I believe they mean the actual hook name, rather than the
> implementation.  So,
> the implementation should look something like this:
>
> mymodule_cck_dosomething()
>
> Where CCK defines the hook cck_dosomething() rather than just
> dosomething().
>
> - Ken Winters

Yes, what Ken said.  See also: hook_views_data(), hook_panels_plugins(), etc.

Nancy, I actually agree that if it's not intended to be called with
module_invoke_all() then it's not a hook.  It's a magically named callback,
with more often than not is a design flaw.  module_invoke() is a bug. :-)

(But THAT's a debate I am putting off until Drupal 8...)

--
Larry Garfield
larry@...

[Earnie]

Quoting Nancy Wichmann <nan_wich@...>:

> Larry Garfield wrote:
>> It's generally good practice to prefix a hook with the name of your
>> module if you're not a core module
>
> Gosh, it's kind of my thoughts that if it can't be found with
> module_invoke_all(), then it's not a "hook" (an API maybe). And
> module_invoke_all() won't find the function unless it starts with the module
> name (core or contrib).
>
>

So I have a module foo implementing hook_foo_bar.  Module foo checks  
for any implementation of hook_foo_bar by calling  
module_invoke_all('foo_bar') in its foo_bar() function.

--
Earnie
-- http://r-feed.com/           -- http://for-my-kids.com/
-- http://www.4offer.biz/       -- http://give-me-an-offer.com/

[Nancy Wichmann]

Earnie Boyd wrote
>So I have a module foo implementing hook_foo_bar.  Module foo checks  
> for any implementation of hook_foo_bar by calling  
> module_invoke_all('foo_bar') in its foo_bar() function.

IMHO, that should be the standard practice. In all my modules, with the exception of Helpers, which acts as core extension (and I didn't intially write), that's the convention I follow.

It can look funny, though, if a module uses its own hook, which several of mine do. You can end up with "function foo_bar_foo_bar()".


Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King, Jr.

[Michael Favia-2]

On 10/16/2009 08:53 AM, Nancy Wichmann wrote:
> Earnie Boyd wrote
>    
>> So I have a module foo implementing hook_foo_bar.  Module foo checks
>> for any implementation of hook_foo_bar by calling
>> module_invoke_all('foo_bar') in its foo_bar() function.
>>      
> It can look funny, though, if a module uses its own hook, which several of mine do. You can end up with "function foo_bar_foo_bar()".
>    
I don't think it looks funny. In fact i appreciate when authors do this
as it helps me implement the hook in my own modules and helps the
developer keep in mind the needs of someone using the hooks. -mf

[Nancy Wichmann]

Larry Garfield wrote:
> module_invoke() is a bug. :-)
>(But THAT's a debate I am putting off until Drupal 8...)

Well, the good news, Larry, is that the D8 queues are open now, so put your
debating hat on let's get D8 done quickly.

Nancy E. Wichmann, PMP
Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King,
Jr.

[arthur-56]

Do people feel like we're moving toward consensus that the contrib  
hook standard ought to be hook_module_name_foo_bar()?

Secondly, do we want to identify a doxygen tag so that we can put  
together a list of contrib hooks?

a.


On Oct 16, 2009, at 9:57 AM, Michael Favia wrote:

> On 10/16/2009 08:53 AM, Nancy Wichmann wrote:
>> Earnie Boyd wrote
>>
>>> So I have a module foo implementing hook_foo_bar.  Module foo checks
>>> for any implementation of hook_foo_bar by calling
>>> module_invoke_all('foo_bar') in its foo_bar() function.
>>>
>> It can look funny, though, if a module uses its own hook, which  
>> several of mine do. You can end up with "function foo_bar_foo_bar()".
>>
> I don't think it looks funny. In fact i appreciate when authors do  
> this as it helps me implement the hook in my own modules and helps  
> the developer keep in mind the needs of someone using the hooks. -mf
>

[Karoly Negyesi]

http://drupal.org/node/548470

[Earnie]

Quoting Karoly Negyesi <karoly@...>:

> http://drupal.org/node/548470
>

Yea, that changes what we are discussing in about 2 years from now  
when D8 comes out by adding a required _hook_ string in the function  
name.  But for D6 and D7 what has been discussed is correct.

--
Earnie

[Jennifer Hodgdon]

arthur wrote:
> Do people feel like we're moving toward consensus that the contrib hook
> standard ought to be hook_module_name_foo_bar()?

That would be a good start.

> Secondly, do we want to identify a doxygen tag so that we can put
> together a list of contrib hooks?

Let's first at least say that module developers whose modules use
module_invoke or module_invoke_all to invoke a hook ought to document
the hook in the first place. My non-scientific sample* of a few found
zero that did.

* Go to drupalcontrib.org, find the module_invoke or module_invoke_all
function, and click through to some of the functions in contrib that
call those two functions. Then search for the name of the implied
hook. Find nothing. Of course, maybe drupalcontrib.org is not indexing
*.api.php files, or I'm missing something?

    --Jennifer


--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

[davereid]

Not all hooks are invoked by module_invoke or module_invoke_all. They can also be called manually with module_implements or by drupal_alter(). http://drupalcontrib.org/api/search/6/hook_ seems to display several pages of contrib module hooks (once the functions begin with 'hook_').

Dave Reid
dave@...

On Fri, Oct 16, 2009 at 1:05 PM, Jennifer Hodgdon <yahgrp@...> wrote:

arthur wrote:

Do people feel like we're moving toward consensus that the contrib hook standard ought to be hook_module_name_foo_bar()?

That would be a good start.

Secondly, do we want to identify a doxygen tag so that we can put together a list of contrib hooks?

Let's first at least say that module developers whose modules use module_invoke or module_invoke_all to invoke a hook ought to document the hook in the first place. My non-scientific sample* of a few found zero that did.

* Go to drupalcontrib.org, find the module_invoke or module_invoke_all function, and click through to some of the functions in contrib that call those two functions. Then search for the name of the implied hook. Find nothing. Of course, maybe drupalcontrib.org is not indexing *.api.php files, or I'm missing something?

  --Jennifer


--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal, WordPress, and custom Web programming

[Larry Garfield]

On Friday 16 October 2009 9:02:15 am Nancy Wichmann wrote:
> Larry Garfield wrote:
> > module_invoke() is a bug. :-)
> >(But THAT's a debate I am putting off until Drupal 8...)
>
> Well, the good news, Larry, is that the D8 queues are open now, so put your
> debating hat on let's get D8 done quickly.

No, there's a Drupal 8 issue version for stuff that we're not dealing with yet,
because marking everything as "postponed" only to have to reopen it again is a
PITA.  The code focus should still be Drupal 7 as we still have a lot of
usability and performance work to do.  (I'm sure some Drupal 8 meta
discussions will be starting soon anyway, they always do, and I'm sure I'll be
starting some of them, but the focus for now still really needs to be Drupal
7.)

--
Larry Garfield
larry@...

[Nancy Wichmann]

Larry Garfield wrote
> No, there's a Drupal 8 issue version for stuff that we're not dealing with
yet,

Oh, well, I wish I could be around to be part of it, but alas, apparently
not.