Where my confusion comes in is when I go to specify parameters or document the function. What parameters does the function take? What hook does it implement?
Preprocess hooks are only provided a single parameter: $variables
. The hook that you're implementing is literally hook_preprocess_HOOK
. The HOOK
part of it is the identifier for the theme entry, as defined in a hook_theme()
implementation somewhere.
So if you have this:
function MODULE_theme() {
return [
'foo' => [
'variables' => [],
],
];
}
Then, by convention, you can implement hook_preprocess_hook
like so:
/**
* Implements hook_preprocess_HOOK() for foo templates
*/
function MODULE_preprocess_foo(&$variables) {
// ...
}
Note the docblock; the convention is to use for THEMEXXX templates, where THEMEXXX is a description of the aforementioned identifieritem being preprocessed. If you search for implements hook_preprocess in the theme entrycore folder, you'll find a lot of these as examples.
So, once I have written a hook implementation (i.e. my_theme_preprocess_block or my_theme_preprocess_page__user__edit), how can I definitively know what hook I have just implemented?
By definition, you already know :) You created the function with a certain name, and that name defines the for THEME part of the phrase in the docblock aboveso you know which theme entry you're preprocessing variables for.
like for the block - hook_preprocess_HOOK is very generic, how can I be sure I'm not implementing something more specific that I just missed in my Googling?
Because there can only ever be one theme entry for a given nameidentifier, you won't run into this problem.
In the case of the hook above, I'm able to find documentation for a template_preprocess_page function, and no such hook_preprocess_page function
something I should know about the difference between template_preprocess_whatever and hook_preprocess_whatever functions that if I knew that thing I wouldn't be confused
Hopefully, along with the above, this will clear things up:
template_process_HOOKtemplate_preprocess_HOOK
is, again by convention, used by the module implementing the theme entry, to provide the base variables. It's always run first, beforehook_preprocess_HOOK
is invoked, so it helps those defining theme entries to ensure important variables and processing are done up front before the rest of the system gets involved.hook_preprocess_HOOK
is essentially for other modules to preprocess the variables, rather than for the module implementing the theme. There's nothing to stop that module from implementinghook_preprocess_HOOK
as well (it's just a naming convention and no special checking is made), but it could be undesirable to do that if some initial processing needs to be done, a latemplate_preprocess_HOOK
.