API docs. Drupal functions that start with an underscore -- what does this mean?

By mwu on 22 Jun 2006 at 17:00 UTC

I am reading the Drupal api docs. I'm looking under functions. At the end there are a lot of functions that start with an underscore. Some of them (all?) seem to be something called "helper functions." I've looked in my php books, searched drupal.org and on Google for "helper functions" mixed with "underscore" and "php." Came up with no answers. What's special about the underscore and functions that start with it? What does the underscore mean?

Comments

Private

Heine commented 22 June 2006 at 17:20

Function names starting with an underscore are considered private and shouldn't be called by external functions. Be aware that it's a convention, there's nothing to enforce this.
--
The Manual | Troubleshooting FAQ | Tips for posting | Make Backups! | Consider creating a Test site.

Great answer

ashraf.hussain commented 16 May 2013 at 11:29

Thanks Heine, your answer is precise and to the point.

It's an indication of a "private" function

webchick

she/they

English

Vancouver 🇨🇦

commented 22 June 2006 at 17:21

While Drupal is not written in an object-oriented way, and PHP prior to version 5 didn't support the concept of private vs. public functions, an underscore preceding a function is a way to indicate that the intention is for this function to be "private" (can also be read as "internal") which means it should only be called by the module that declared it. In Drupal's case, it's simply a coding standard. You can call _forum_get_vid from the blahblah.module just fine.

Oops, too slow. ;)

webchick

she/they

English

Vancouver 🇨🇦

commented 22 June 2006 at 17:22

Oops, too slow. ;)

Is an included file considered private?

mlanning commented 12 May 2014 at 19:14

Is it acceptable to define the function in an included file (.inc) and call it in the module file (.module)?.. or should the call be defined within the same file only?

It's fine to do this, however

Jaypan commented 17 May 2014 at 08:08

It's fine to do this, however note that you'll need to include the .inc file using module_load_include() before the function can be used.

to add two things...

dman commented 22 June 2006 at 22:11

I'm surprised you couldn't google it, but this convention is common through a lot of programming languages, not just Drupal, and not just PHP.

Also, the implication for a programmer is that you should NOT call those functions from outside the module (that's what private means) as the interface (like, the order of arguments or the data structure being passed in) may change without warning. The collary is that non-private (public) functions are there for you to call whenever you want.
You are welcome to call other modules functions from your own whenever you want.
... in theory.

.dan.
http://www.coders.co.nz/

_{.dan. is the New Zealand Drupal Developer working on Government Web Standards}