Modules cannot reliably enhance or alter the node form anymore

I think what we need to do here is this:

1. Detach the form handlers from the actual buttons in $form.
2. Introduce custom form handler stacks in EntityFormController itself, which are attached to an entity operation.

To clarify what I mean, before/after code from a DX/module perspective probably works best:

Before

function mymodule_form_node_form_alter(&$form, &$form_state) {

  // Act upon preparation of submitted form values.
  // (AFTER #entity_builders have run, BEFORE preview/saving)
  // Note: This weirdness only exists for node_form() currently.
  $form['#submit'][] = 'mymodule_node_form_prepare_submit';

  // Act BEFORE the node is saved.
  array_unshift($form['actions']['submit']['#submit'], 'mymodule_node_form_post_submit');

  // Act AFTER the node has been saved.
  $form['actions']['submit']['#submit'][] = 'mymodule_node_form_post_submit';
}

After

function mymodule_form_node_form_alter(&$form, &$form_state) {
  $controller = $form_state['controller'];

  // Act upon preparation of submitted form values.
  $controller->appendSubmit('mymodule_node_form_prepare_submit');

  // Act BEFORE the node is saved.
  $controller->prependSave('mymodule_node_form_pre_save');

  // Act AFTER the node has been saved.
  $controller->appendSave('mymodule_node_form_post_save');

  // Essentially, this concept works for all available entity form actions;
  // i.e., for all dedicated action methods on the EntityFormController...:

  $controller->appendPreview('mymodule_node_form_post_preview');
  $controller->appendPublish('mymodule_node_form_publish');
  $controller->appendUnpublish('mymodule_node_form_unpublish');
  // etc...
}

Sleeping over this, I realized that we probably can't have dedicated methods for each operation though, since alas, modules should also be able to add custom operations.

Therefore, I think the signatures would change into generic:

$controller->prepend('preview', 'mymodule_node_form_pre_preview');

$controller->append('save', 'mymodule_node_form_save');

However, the main aspect stays the same: We effectively detach #submit from the buttons in the $form, and instead move the stack management and their invocation into the EntityFormController.

re: #6:

Err, nope — the stacks on the controller are not "buttons", but "actions"/"operations". Therefore, your code can prepend or append its handler to the "save" action/operation, and that action/operation may be used by button X, Y, Z, doesn't matter.

Multiple buttons can call into the same action/operation. This is essentially the case with the new publish/unpublish buttons already; the corresponding publish/unpublish actions are adjusting the $entity->status property only. Afterwards, the save action is invoked.

re: #8:

Essentially no change to now:

$form['submit'] = array(
  '#value' => t('Save'),
  '#validate' => array(
    array($this, 'validate'), // Triggers the 'validate' stack.
  ),
  '#submit' => array(
    array($this, 'submit'),   // Triggers the 'submit' stack.
    array($this, 'save'),     // Triggers the 'save' stack.
  ),
);
$form['delete'] => array(
  '#value' => t('Delete'),
  // No need to validate the form when deleting the entity.
  '#submit' => array(
    array($this, 'delete'),
  ),
);

// NodeFormController:

$form['publish'] = array(
  '#value' => t('Publish'),
  '#validate' => array(
    array($this, 'validate'),
  ),
  '#submit' => array(
    array($this, 'submit'),
    array($this, 'publish'),
    array($this, 'save'),
  ),
);
$form['unpublish'] = array(
  '#value' => t('Unpublish'),
  '#validate' => array(
    array($this, 'validate'),
  ),
  '#submit' => array(
    array($this, 'submit'),
    array($this, 'unpublish'),
    array($this, 'save'),
  ),
);

In short:

1. Buttons declare which actions/operations they invoke.
2. Modules no longer integrate with the buttons, but instead, with the actions/operations.

What would be the use case to hook into e.g. publish or unpublish vs. just submit?

Well, by hooking into the publish action, you do not have to care for checking whether the entity will be published. It will.

And, your code will be executed whenever the publish action is executed, regardless of button.

As things currently stand, the 'submit' action is only used for #entity_builders-alike stuff; i.e., munging/transforming submitted form values into values that are suitable for X. We most likely want to clean this up, too, since especially for the node form, a rather crazy amount of builders and handlers are declared and invoked from different spots, and I don't think I'm able to precisely describe how the exact flow looks like without looking at the code...

Let's also bear in mind that this is almost exclusively about modules that try to integrate with an entity form.

Honestly, I don't know yet. :) But I could imagine use-cases in workflow/revisioning modules as well as spam/moderation modules and so on. If the UI invokes a particular action processing stack, then there should be ways to integrate with that particular action stack. Otherwise, we're back to futzing with #properties on form buttons, but only on some; i.e., eek, inconsistency. ;)

Speaking of, this overall change on its own will introduce a relatively major inconsistency with regard to entity forms vs. non-entity forms. However, I think that's a bullet we need to bite.

The proposal still makes sense to me. The buttons in the node form are still problematic in HEAD. (stumbled over them again just recently)

Meanwhile, D8 introduced entity operations. But not sure whether operations are mapping to the concept of "buttons" or "actions" here. I assume neither of both, because e.g. there is no 'save' operation, and e.g. a 'publish' operation would implicitly save. Unless I'm mistaken, operations are rather meant as entry points (as opposed to exit points).

FWIW, I've the impression that the actions proposed here would be fairly similar to the concept of the Actions in core; i.e., each action has an identifier and performs a default operation, whereas modules can add further operations before/after the default, and the action can be triggered from any code. — …whereas this summary actually sounds like a description of the Event handler architecture. (?)

Hm. What if a form button would trigger one or more named events? (1. submit, 2. publish, 3. save) And form handlers and/or entity actions/operations would listen/subscribe to events?

The question of how to alter the #submit handlers on the node form came up in IRC today… $form['submit'] vs. $form['publish'], ugh.

The idea of (1) having action/operation stacks, (2) have a button trigger one of those stacks, and (3) possibly even converting "list of callbacks/handlers" into (prioritized) event listeners sounds sane to me.