Add hook_captcha_placement_alter

Hi,

Cool! Thanks for the work. Also nice you thought to update the API documentation :)

One remark: you placed the hook_alter trigger after caching of the placement map (variable_set('captcha_placement_map_cache', $placement_map);). Any reason for this? Wouldn't it be better for performance to cache the altered placement map?

Note that I already provided place to put the hook:
around line 245 in captcha.inc:

 if ($placement_map === NULL) {
      // If second level cache missed: start from a fresh placement map.
      $placement_map = array();

      // This is the place to (pre)fill the placement map with some hard coded default entries.
      // However, probably all Drupal core forms are correctly handled with the best effort
      // guess based on the 'actions' element (see below). So not much to here at the moment.

      // TODO: provide a hook here so other modules can inject placements here?
      // TODO: also make the placement 'overridable' from the admin UI?
    }

Hi Sheldon, thanks for your reply.

About the caching: there is a button on the CAPTCHA settings page to flush the placement cache, precisely for this (see attachment).
The caching is there because CAPTCHA placement is not something that changes very often once a website is set up. It would be a waste to do all the form array traversing/processing every time for every CAPTCHA protected form, when the result is probably the same as last time.
Conceptually speaking, I think that the result of placement altering by other modules should be included in this caching.
You might have a point that cache invalidation is currently not optimal (only a button on the settings page). Alternatives: invalidate it when new modules are enabled/disabled, always invalidate it when there is CAPTCHA configuration activity (e.g. the CAPTCHA settings form is submitted), ...

Also, the hook I wrote modifies placement for a single form ID, whereas placing the hook in the location you suggested would require modifying the entire placement map. I think in practice people who want to have this kind of hook will likely only want to modify placement on one or two forms on their website, so modifying the $placement array rather than the $placement_map array seems to me like an easier hook to understand and implement.

I don't think there would be a lot of difference.
You propose:

function hook_captcha_placement_alter(&$placement, $form_id) {
  if ($form_id == 'appform_form') {
    $placement['path'][1] = 'fieldset3';
    $placement['key'] = 'submit';
    $placement['weight'] = NULL;
  }
  else if ($form_id == 'another_form') {
    // ...
  }
}

While I was thinking along the lines of

function hook_captcha_placement_map_alter(&$placement_map) {
  $placement_map['my_fancy_form'] = array(
    'path' => array('fieldset3'),
    'key' => 'submit',
    'weight' => NULL,
  );
  $placement_map['another_form'] = array(
    // ..
  );
}

Which looks even easier to me (no need for if's, just direct assignments).

(and here is the attachment)

Hi, I worked a bit on this and added a hook_captcha_placement_map() hook.

I also added clearing of the placement cache when a new module is enabled.

ok, decided to commit this one
will be in next release

Note. I had to disable then enable captcha after adding this hook. Normal drupal clear all cache (drush cc all) did not work.