5 files changed, 92 insertions, 13 deletions
diff --git a/modules/block/block.api.php b/modules/block/block.api.php
index 96c92668e..cec99223b 100644
--- a/modules/block/block.api.php
+++ b/modules/block/block.api.php
@@ -192,7 +192,7 @@ function hook_block_view($delta = '') {
  *   - delta: The identifier for the block within that module, as defined within
  *     hook_block_info().
  *
- * @see hook_block_view_alter()
+ * @see hook_block_view_MODULE_DELTA_alter()
  * @see hook_block_view()
  */
 function hook_block_view_alter(&$data, $block) {
@@ -213,10 +213,6 @@ function hook_block_view_alter(&$data, $block) {
  * Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
  * specific block, rather than implementing hook_block_view_alter().
  *
- * Note that this hook fires before hook_block_view_alter(). Therefore, all
- * implementations of hook_block_view_MODULE_DELTA_alter() will run before all
- * implementations of hook_block_view_alter(), regardless of the module order.
- *
  * @param $data
  *   An array of data, as returned from the hook_block_view() implementation of
  *   the module that defined the block:
diff --git a/modules/block/block.module b/modules/block/block.module
index 93f4389e4..12b916ad0 100644
--- a/modules/block/block.module
+++ b/modules/block/block.module
@@ -762,9 +762,8 @@ function _block_render_blocks($region_blocks) {
         $array = module_invoke($block->module, 'block_view', $block->delta);
 
         // Allow modules to modify the block before it is viewed, via either
-        // hook_block_view_MODULE_DELTA_alter() or hook_block_view_alter().
-        drupal_alter("block_view_{$block->module}_{$block->delta}", $array, $block);
-        drupal_alter('block_view', $array, $block);
+        // hook_block_view_alter() or hook_block_view_MODULE_DELTA_alter().
+        drupal_alter(array('block_view', "block_view_{$block->module}_{$block->delta}"), $array, $block);
 
         if (isset($cid)) {
           cache_set($cid, $array, 'cache_block', CACHE_TEMPORARY);
diff --git a/modules/simpletest/tests/form.test b/modules/simpletest/tests/form.test
index 7ecfde9ac..40c7490da 100644
--- a/modules/simpletest/tests/form.test
+++ b/modules/simpletest/tests/form.test
@@ -210,6 +210,40 @@ class FormsTestCase extends DrupalWebTestCase {
 }
 
 /**
+ * Test form alter hooks.
+ */
+class FormAlterTestCase extends DrupalWebTestCase {
+  public static function getInfo() {
+    return array(
+      'name' => 'Form alter hooks',
+      'description' => 'Tests hook_form_alter() and hook_form_FORM_ID_alter().',
+      'group' => 'Form API',
+    );
+  }
+
+  function setUp() {
+    parent::setUp('form_test');
+  }
+
+  /**
+   * Tests execution order of hook_form_alter() and hook_form_FORM_ID_alter().
+   */
+  function testExecutionOrder() {
+    $this->drupalGet('form-test/alter');
+    // Ensure that the order is first by module, then for a given module, the
+    // id-specific one after the generic one.
+    $expected = array(
+      'block_form_form_test_alter_form_alter() executed.',
+      'form_test_form_alter() executed.',
+      'form_test_form_form_test_alter_form_alter() executed.',
+      'system_form_form_test_alter_form_alter() executed.',
+    );
+    $content = preg_replace('/\s+/', ' ', filter_xss($this->content, array()));
+    $this->assert(strpos($content, implode(' ', $expected)) !== FALSE, t('Form alter hooks executed in the expected order.'));
+  }
+}
+
+/**
  * Test form validation handlers.
  */
 class FormValidationTestCase extends DrupalWebTestCase {
diff --git a/modules/simpletest/tests/form_test.module b/modules/simpletest/tests/form_test.module
index e035eb721..a8a22abfa 100644
--- a/modules/simpletest/tests/form_test.module
+++ b/modules/simpletest/tests/form_test.module
@@ -10,6 +10,13 @@
  * Implements hook_menu().
  */
 function form_test_menu() {
+  $items['form-test/alter'] = array(
+    'title' => 'Form altering test',
+    'page callback' => 'drupal_get_form',
+    'page arguments' => array('form_test_alter_form'),
+    'access arguments' => array('access content'),
+    'type' => MENU_CALLBACK,
+  );
   $items['form-test/validate'] = array(
     'title' => 'Form validation handlers test',
     'page callback' => 'drupal_get_form',
@@ -142,6 +149,46 @@ function form_test_menu() {
 }
 
 /**
+ * Form builder for testing hook_form_alter() and hook_form_FORM_ID_alter().
+ */
+function form_test_alter_form($form, &$form_state) {
+  // Elements can be added as needed for future testing needs, but for now,
+  // we're only testing alter hooks that do not require any elements added by
+  // this function.
+  return $form;
+}
+
+/**
+ * Implements hook_form_FORM_ID_alter() on behalf of block.module.
+ */
+function block_form_form_test_alter_form_alter(&$form, &$form_state) {
+  drupal_set_message('block_form_form_test_alter_form_alter() executed.');
+}
+
+/**
+ * Implements hook_form_alter().
+ */
+function form_test_form_alter(&$form, &$form_state, $form_id) {
+  if ($form_id == 'form_test_alter_form') {
+    drupal_set_message('form_test_form_alter() executed.');
+  }
+}
+
+/**
+ * Implements hook_form_FORM_ID_alter().
+ */
+function form_test_form_form_test_alter_form_alter(&$form, &$form_state) {
+  drupal_set_message('form_test_form_form_test_alter_form_alter() executed.');
+}
+
+/**
+ * Implements hook_form_FORM_ID_alter() on behalf of system.module.
+ */
+function system_form_form_test_alter_form_alter(&$form, &$form_state) {
+  drupal_set_message('system_form_form_test_alter_form_alter() executed.');
+}
+
+/**
  * Form builder for testing drupal_validate_form().
  *
  * Serves for testing form processing and alterations by form validation
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 4f4fb9935..a0fc4c0f4 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -1241,7 +1241,11 @@ function hook_page_alter(&$page) {
  * altering a node form, the node object retrieved at from $form['#node'].
  *
  * Note that instead of hook_form_alter(), which is called for all forms, you
- * can also use hook_form_FORM_ID_alter() to alter a specific form.
+ * can also use hook_form_FORM_ID_alter() to alter a specific form. For each
+ * module (in system weight order) the general form alter hook implementation
+ * is invoked first, then the form ID specific alter implementation is called.
+ * After all module hook implementations are invoked, the hook_form_alter()
+ * implementations from themes are invoked in the same manner.
  *
  * @param $form
  *   Nested array of form elements that comprise the form.
@@ -1250,6 +1254,8 @@ function hook_page_alter(&$page) {
  * @param $form_id
  *   String representing the name of the form itself. Typically this is the
  *   name of the function that generated the form.
+ *
+ * @see hook_form_FORM_ID_alter()
  */
 function hook_form_alter(&$form, &$form_state, $form_id) {
   if (isset($form['type']) && $form['type']['#value'] . '_node_settings' == $form_id) {
@@ -1269,15 +1275,12 @@ function hook_form_alter(&$form, &$form_state, $form_id) {
  * rather than implementing hook_form_alter() and checking the form ID, or
  * using long switch statements to alter multiple forms.
  *
- * Note that this hook fires before hook_form_alter(). Therefore all
- * implementations of hook_form_FORM_ID_alter() will run before all implementations
- * of hook_form_alter(), regardless of the module order.
- *
  * @param $form
  *   Nested array of form elements that comprise the form.
  * @param $form_state
  *   A keyed array containing the current state of the form.
  *
+ * @see hook_form_alter()
  * @see drupal_prepare_form()
  */
 function hook_form_FORM_ID_alter(&$form, &$form_state) {