0

Considering the PHPCS warning:

phpcs: Hook implementations should not duplicate @param documentation

Is there any way to tell PHPCS that the function is an AJAX-callback (so that such warnings are generated)?

Or, Should we document all AJAX-callback parameters, with @param PHPDoc?


Background:

There was a discussion in our company about the below AJAX-callback function:

/**
 * Prevents popup's redirection from dashboard to another link.
 *
 * Users were redirected to another page as soon as the Event-creation
 * popup form was submitted, just added an AJAX handler to submit button
 * which prevents the redirect using ajax,
 * and when there is any error on the form, the message is sent to the popup.
 */
function _MYMODULE_popup_submit(array &$form, FormStateInterface $formState) {
  // ...
}

Where one developer insisted on adding @param PHPDoc comments to each AJAX-callback like:

/**
 * Prevents popup's redirection from dashboard to another link.
 *
 * Users were redirected to another page as soon as the Event-creation
 * popup form was submitted, just added an AJAX handler to submit button
 * which prevents the redirection using ajax,
 * and when there is any error on the form, the message is sent to the popup.
 *
 * @param array &$form
 *   All data of the form.
 * @param \Drupal\Core\Form\FormStateInterface $formState
 *   State of the form.
 *
 * @return \Drupal\Core\Ajax\AjaxResponse
 *   Returns the data back as AjaxResponse object.
 */
function _amt_dayview_popup_submit(array &$form, FormStateInterface $formState) {
  // ...
}

And the other considered it as understandable and that it should not be documented:

... remember that PHPCS will warn you every time we use @param on any hook, like "phpcs: Hook implementations should not duplicate @param documentation", and just because PHPCS can not differ AJAX-callback from normal functions it does not mean that we should do this ...


Edit: The feature request is created for this on Drupal.org.

  • 1
    Custom functions and code that have custom functionality like this should be commented like above. Six months from now no one will remember what it does or why, or that it’s specifically for an AJAX callback. As for the params, these are pretty standard for a form submit hook. They aren’t necessary here really, but most editors will just add it automatically. Verbose yes, but doesn’t hurt much. Perhaps you hire new dev interns someday - it’s helpful downstream. – Kevin Aug 7 '19 at 11:30
  • @Kevin, I found the docs about Callback definitions and implementation (which suggests "Implements callback_descriptive_name"), but the problem now is that there was nothing like callback_form_ajax in any *.api.php file !! – Top-Master Aug 7 '19 at 12:21
  • Is "./modules/custom/MYMODULE\MYMODULE.api.php" the right place for our own custom callback definitions? because PHPCS doesn't seem to recognize any of them. – Top-Master Aug 7 '19 at 12:31
  • Just checked and PHPCS even ignores "Implements callback_batch_finished" (which is in the "./core/lib/Drupal/Core/Form/form.api.php" file), so, this feature seems to be not yet supported by PHPCS for now. – Top-Master Aug 7 '19 at 12:38
  • 1
    OK, take your point. – Alfred Armstrong Aug 8 '19 at 8:31
1

Is there any way to tell PHPCS that the function is an AJAX-callback (so that such warnings are generated)?

Yes, it's as simple as implementing hooks except that instead of "Implements hook_", it starts with "Implements callback_".

The only problem is that currently (August 2019) it is not supported by Drupal's PHPCS standard and you don't get any warnings yet.

Or, Should we document all AJAX-callback parameters, with @param PHPDoc?

That too is an option, for your newly hired dev interns, but especially when there was no official definition in any existing *.api.php file and when you do not want to write your own *.api.php file.

Source:

In Drupal's Official-documentation of August 2019, we can find below Callback implementation:

/**
 * Implements callback_batch_finished().
 */
function _node_mass_update_batch_finished($success, $results, $operations) {
  // …
}

Note: Unlike hooks any callback starts with an underscore (i.e. it is "_MYMODULE_descreptive_name").


Callback definition example:

In our case, because Drupal's own *.api.php files did not cover AJAX-callbacks, we added our own *.api.php file to prevent copy/paste until Drupal's own *.api.php files cover that section as well, something like below:

<?php

/**
 * @file
 * Callbacks and hooks related to MYPROJECT system.
 */

/**
 * @addtogroup callbacks
 * @{
 */

use Drupal\Core\Ajax\AjaxResponse;
use Drupal\Core\Ajax\HtmlCommand;
use Drupal\Core\Form\FormStateInterface;

/**
 * Callback for AJAX events.
 *
 * AJAX callback functions can be used to update existing or
 * add new form fields, update values in form fields and more,
 * while users can still interact with the form.
 *
 * @param array &$form
 *   All data of the form.
 * @param \Drupal\Core\Form\FormStateInterface $formState
 *   State of the form.
 *
 * @return \Drupal\Core\Ajax\AjaxResponse
 *   Returns the data back as AjaxResponse object.
 */
function callback_form_ajax(array &$form, FormStateInterface $formState) {
  // Here we do something meaningful with the results.
  $response = new AjaxResponse();
  $response->addCommand(new HtmlCommand('#message-box', 'my message.'));
  return $response;
}

/**
 * @} End of "addtogroup callbacks".
 */

/**
 * @addtogroup hooks
 * @{
 */

/* Place any hook definitions here. */

/**
 * @} End of "addtogroup hooks"
 */

Callback implementation example:

/**
 * Implements callback_form_ajax().
 *
 * Prevents popup's redirection from dashboard to another link.
 *
 * Users were redirected to another page as soon as the Event-creation
 * popup form was submitted, just added an AJAX handler to submit button.
 * which prevents the redirect using ajax,
 * and when there is any error on the form, the message is sent to the popup.
 */
function _amt_dayview_popup_submit(array &$form, FormStateInterface $formState) {
  // ...
}

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.