[PP-1] Determine how to implement Form Alters with attributes.

Remember we can use named arguments now so to me a single #[FormAlter] attribute is easier.

Alter all forms:

#[FormAlter]

Alter one form:

#[FormAlter('node_form')]

Alter all forms, specify method:

#[FormAlter(method: 'alterForm')]

I don't see the method argument being used widely anyway when we can just apply the attribute to the methods themselves?

I forgot about named arguments, that makes it much cleaner, you can even use it to help with targeting base form vs form id so we can help identify it for documentation!

I'm not even sure we need to tell the difference between base form IDs and form IDs, we don't do that at the moment with hooks except in the docblock - I'm not sure what it would gain us.

The order they are called from comes from the name. #Hook has to pass the hook name still so that is preserved. We probably want to preserve that for any child Attribute too.

It's also useful for documentation to know which hook is being called.

A bit confused about the order discussion. hook_form_BASE_FORM_ID_alter() and hook_form_FORM_ID_alter() has the same structure, there is no explicit order in hook definition. It's the same pattern, it's purely documentation thing. The order is defined by the hook invocation order: the form system will first call the hook for the base form id and then form_id, but your hook function might match both if there are conflicting form ids and base ids:

There is no "base" in this alter definition:

  /**
   * Implements hook_form_BASE_FORM_ID_alter().
   */
  #[Hook('form_node_form_alter')]
  public function formNodeFormAlter(&$form, FormStateInterface $form_state, $form_id) : void {

So, having both FormAlterById and BaseFormAlter would purely be a documentation thing about what your intention is, but the resulting hook string would be the same. looking at the example above, given that we have the intention to remove the requirement to have a Implements hook_..() docblock that might not be a bad thing to have that annotated somehow, but fairly minor difference.

I was convinced I was missing something in #5/#6, so thanks @berdir because I was thinking exactly along those lines.

your hook function might match both if there are conflicting form ids and base ids

This was a problem before, and it's still a problem now, but I don't think that is for this issue to solve.

For me I think we should just implement

#[FormAlter] === hook_form_alter
#[FormAlter('node_delete_confirm')] === hook_FORM_ID_alter or hook_BASE_FORM_ID_alter

Maybe we could have #[BaseFormAlter(...)] to identify base forms, and perhaps that will help us solve name collisions in the future, but at least to start with I think they should be treated identically - at least until we remove procedural hooks, because there is no way of identifying (except via an optional comment) which is a base form and which is not.

> This was a problem before, and it's still a problem now, but I don't think that is for this issue to solve.

Certainly, I just mentioned that to point out how similar those two hooks really are.

I think that simplifies this.

We add implements still.
Use FormAlter with an optional form id if that is provided we specify hffia.

Some future date we either add type, add a base form attribute, or deprecate base form and just leave it ambiguous.

When I started working on this I realized we can't have separate IMPLEMENTS if we have only one child attribute.

@ghost helpfully reminded me that this is also about api finding the form alters.

He suggested we add a PREFIX and SUFFIX const we can set to form and alter then pass the id in conditionally.

I'll push that up then update the IS.

This is ready for review, I think this covers all bases and will likely work for api to pick up implementations.

I think @ghost will review the api side.

I added some more comments to the MR, would like to get this in so we can start adding other attribute classes. It's unfortunate enough that they aren't in 11.1, because it means contrib can't really depend on them, as the BC system doesn't work for them (we have legacyhooks, but if you use FormAlter instead of Hook then your module is broken in 11.1, which is awkward).

I will move the entity discussion to a separate issue.

because it means contrib can't really depend on them, as the BC system doesn't work for them (we have legacyhooks, but if you use FormAlter

Do you mean for 11.1.0?

Addressed your feedback!

@nicxvan:

> Yes, we haven't even addressed the main question around form alter though. Should we validate that first?

I'm not sure I know what the main question is? The general structure with form id and base form id? IMHO we agreed on that in #11-14.

> Do you mean for 11.1.0?
Yes, that's what I Mean. I don't see how we could add this in a BC compatible way, so modules will only be able to use specific hook classes once the require the core version and until, need to stick to using Hook classes.

adding needs change record tag to add one that explains the prefix/suffix concept and how to add hook classes and the specific ones that were added here. Maybe we can do an aggregated change record that similar to plugin conversions that lists which minor version added which hook attribute class?

Do we also create a follow-up to update all form alters to use the new ones, or will we update as we go? Not sure it's worth going through them all just because.

I also created 📌 Implement Entity hook attribute Active

For the CR

The CR says it is from 11.2+, but I think the problem explained in #24 deserves an explicit mention that this attribute class can only be used if a module requires 11.2 since LegacyHook doesn't work for this.

This doesn't only introduce the specific Formalter attribute but also the concept of hook attribute classes for dynamic hooks? I'd suggest we add a second CR that focuses on how to define your own Hook attribute classes, specifically when it contains dynamic parts such as form ids or entity types.

Oh sorry about that!

Yes, that's what I Mean. I don't see how we could add this in a BC compatible way, so modules will only be able to use specific hook classes once the require the core version and until, need to stick to using Hook classes.

Unless they get backported, but yeah eventually that will become a problem.

adding needs change record tag to add one that explains the prefix/suffix concept and how to add hook classes and the specific ones that were added here. Maybe we can do an aggregated change record that similar to plugin conversions that lists which minor version added which hook attribute class?

Missed that one, we can also just attach more issues as we go.

Do we also create a follow-up to update all form alters to use the new ones, or will we update as we go? Not sure it's worth going through them all just because.

Either I think.

Applied your suggestions and added that CR.

Seems the Change Record is now lin place.

Rebased.

nicxvan → changed the visibility of the branch 11.x to hidden.

Added a few minor edits to the CR. See the revision log for details.

I am going to revert those CR changes, that CR is explicitly about the PREFIX and SUFFIX constants, a themer might consume the attribute, but only a module would create a or implement one.

Also I'm not sure the note about it still being a hook makes sense here since it's a constant on the Hook Attribute.

I'll see if I can clarify what this CR is for.

Had 1 question in slack around #[Alter but @nicxvan cleared it up and added a new CR.

Looking at the MR seems all threads have been addressed, suppose after this lands some follow ups could be opened to convert others. May be good first time contribution items for DrupalCon coming up!

Believe this one is good.

Please do not force api module to chase an entire chain of ancestors, always define both constants.

Thanks that's much better.

> Please do not force api module to chase an entire chain of ancestors, always define both constants.

I don't know how complex that would be, didn't look at the code. But either we enforce that or we'll need to support it (or live with hook documentation/discovery in api.module not working). People will extend hook classes and expect that to work because it works for actual discovery.

If that really is a considerable complexity and we want to enforce it, we need to make those classes final. Which I very well know how much you dislike that. And then Alter maybe shouldn't exist in the first place, my suggestion for adding that (here in this issue specifically) was exactly so it can be a base class.

It's still not clear to me if the expectation is that eventually all hooks should have a custom Hook attribute class (and we use it to document said hook) or just common/frequently used ones.

Quick driveby review. A few pedantic nits for now. Haven’t finished, but this is all I could do from my phone while eating lunch with the other hand. 😂

Is that answer acceptable?

The Needs Review Queue Bot → tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide → to find step-by-step guides for working with issues.

Rebased

Thanks! Overall, this looks really good and clean. But (as usual) I've got some concerns and nits on the MR. 😅

Initial pass at saving credits.

Ok, huge WTF, I injected comment.manager and getFieldUIPageTitle does not exist, did a quick search, it was removed 10 years ago.
#2228763: Create a comment-type config entity and use that as comment bundles, require selection in field settings form →

Can we safely just delete these? These alters can't have done anything in years.

I created an issue to track that and removed the change from this issue: 🐛 Determine what to do about comment module form alters calling getFieldUIPageTitle Active
I converted contact form alters instead so we can validate.

The Needs Review Queue Bot → tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide → to find step-by-step guides for working with issues.

Fix bot line length warnings

NR bot hopefully appeased.

Humans are smarter than bots. 😂 I still have questions and concerns. But we're really close now.

Thanks!
-Derek

Looks like we need a few follow-ups here:

• Something to document how to put form submit callbacks into Hook classes
• Fixing Hook to use NULL for both of its optional parameters, instead of '' for $method vs NULL for $module

Otherwise, I think this is RTBC.

Created the follow ups, I think it's safe to RTBC based on that.

The Needs Review Queue Bot → tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide → to find step-by-step guides for working with issues.

Is it weird that the bot is picking up PHPCS issues that the build is not?

> Is it weird that the bot is picking up PHPCS issues that the build is not?

No, this is just a very new rule, was not enforced before.

Thanks for opening those followups. Resolved my open threads. I'll let @nicxvan apply the phpcs suggestion, then it's RTBC to me.

Thanks!
-Derek

Basically, the bot runs checks using the new rules, this needs to be rebased to see the new rules.

It was a clean rebase, just new 80 character limit for FormAlter which was missed in the earlier rebase.

cspell failed on the latest. Added another MR suggestion to fix it. So very close! 😅

Whoops, I must have had an old pipeline run open cause it was green.

Just gonna set to needs review this time.

Thanks! Pipeline is green. I’ve read the diff many times now. Nothing left to improve to my eyes, other than the follow-ups. 😉 let’s get this in.

Thanks for your patience and persistence!

No, this is just a very new rule, was not enforced before.

Oh, interesting. I could've sworn the 80-character limit for comments was an old rule, but good to know.

Sorry folks, but we need to get the change records right on this.

I agree with @berdir in #24 that the change records for this should follow the established pattern used for the plugin conversion from annotation to attributes. Since this issue is implementing the new feature then it should not refer to https://www.drupal.org/node/3499788 → . And if more implementations are planned then we should have a CR for that work, similar to https://www.drupal.org/node/3229001 →

I can update the crs to be more explicit.

https://www.drupal.org/node/3499788 → refers to both issues because neither have landed, whichever lands first the other reference will be removed.

I'll update the crs shortly.

I think my feedback from #24 was mostly addressed already. I did a pass of https://www.drupal.org/node/3499495 → , I put the multiple before/after together used php tags for slightly better formatting and used a real form_id. That is easier to read and understand IMHO.

Not sure yet about doing a grouped change record yet. FormAlter is quite special and worth mentioning on its own. So is Preprocess from [#3499788] I currently don't expect we're going to add a dozen others in 11.2. We should IMHO first do an issue to figure out how we want to approach that exactly, if all hooks should get one or or only dynamic/common ones (see also questions in related entity issue). That doesn't block this issue IMHO, no question that it makes sense for FormAlter or Preprocess.

I also did a pass of https://www.drupal.org/node/3499788 → . I found the "pattern" part confusing, it wasn't really clear IMHO if that was referring to the prefix/suffix or the dynamic part inbetween. All Hooks have at least a suffix, so they all "have a pattern". I also removed Alter from that, those examples did not represent what the code now actually looks like.

What has _not_ been addressed IMHO is #39. Alter right now is quite confusing. I suggested that earlier with the idea that we would support inheritance of the constants, which we don't. I find that a bit sad, but as mentioned in #39, I can not comment on the complexity of that so I'll accept that. However, in that case, I propose that we focus only on FormAlter here and do not introduce Alter. Then we can also delete that change record.

Ok I think I addressed everything.
I made on small tweak in the CR, all of your other changes look great.

I simplified this MR significantly by only adding FormAlter and converting one example.

I also created a follow up here and moved the CR there: 🐛 [pp-1] Create generic Alter Attribute Active

I tagged this as 11.2.0 release priority because it adds the SUFFIX/PREFIX constants that are also needed by 📌 Handle module preprocess functions Active , getting this in first will make it easier to review and commit that.

This was RTBC before was set back to needs work for change record improvements, they now look good I think. The MR was also simplified by removing the alter attribute class and leftovers in the comment module (see comment #46/#47, it was dead code that was removed elsewhere but added back here when rebasing later on I guess)

Opened 📌 Move altered submit callbacks from contact.module into src/Hook/ContactFormHooks.php Active to resolve one of my own MR threads. Very minor comment nit is the only open thread, but leaving at RTBC since this is ready with or without that fix.