In Drupal 7, the first parameter of a form builder function is $form.

When implementing a form builder function, one has the option of either adding stuff to this existing array and returning it, or creating a new $form array, discarding what was passed into the function. In my experience, both of these options usually work fine.

What's the point? Is there ever a case when this parameter is needed?

I think to vaguely remember that this is somehow relevant when a form is rebuilt, so this would be the old form.. but I would not really know what to do with it.

Note: The same question already exists for Drupal 8, but it seems to be a policy here that we need distinct questions for D7 and D8. I was going to answer it for D7, and I realize it would be off-topic in the D8 question.


At least for D7 there is one scenario where the passed-in $form parameter does make a difference.

With hook_forms(), it is possible to define a 'wrapper_callback' for a form definition for a specific form id.

From the hook documentation https://git.drupalcode.org/project/drupal/-/blob/7.69/modules/system/system.api.php#L1821:

 *   - wrapper_callback: (optional) Any callable to invoke before the form
 *     builder defined in 'callback' is invoked. This wrapper callback may
 *     prepopulate the $form array with form elements, which will then be
 *     already contained in the $form that is passed on to the form builder
 *     defined in 'callback'. For example, a wrapper callback could setup
 *     wizard-like form buttons that are the same for a variety of forms that
 *     belong to the wizard, which all share the same wrapper callback.

So if a wrapper callback was defined, then the $form array passed as a parameter may already be prepopulated.

I found some contrib modules where this is being used (simply grep for 'wrapper_callback'):

  • ctools does not set the wrapper callback in hook_forms(), instead it sets $form_state['wrapper_callback'] directly.
  • entity uses hook_forms() to set a wrapper callback to a form definition, but also sets it in $form_state['wrapper_callback'] directly.
  • media_bulk_upload does use hook_forms() to specify a wrapper callback.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.