Explicitly register template_preprocess callbacks in hook_theme()

Created a merge request with a proof of concept, basic right now, but already covers BC by only looking for and registering template_ prefixed functions if initial preprocess is not defined.

MR is based on the referenced issue, only relevant changes is the currently last commit: https://git.drupalcode.org/project/drupal/-/commit/a955017c8e669d28297af....

Array key "initial preprocess" obviously up for discussion, I picked this to explain the difference to regular preprocess functions.

I copy pasted the invocation, we can for example use\Drupal\Core\Utility\CallableResolver to also support services.

This does make theme_registry_alter harder to maintain BC for contrib which is not a problem for the original issue, but I'm not sure how many people are moving template preprocess around, and I'm not sure this should be a blocker for this approach, just an observation.

Yes, it does. As discussed, the question is whether we want to/need to maintain BC. I'm arguing we don't. That we provide an alter hook for something doesn't mean that it has full BC (form_alter for example. form structures have zero BC, you can do whatever, but we do not guarantee anything around that. Or we could never improve a UI). But we need a framework manager decision.

If it's decided that this is the direction to go, I really think this should be done together with the other issue, this isn't too much more and if we pull out the template work in the other issue the changes are likely a wash complexity-wise.

I'm always surprised by just how opposite we sometimes think ;)

I really think those 3 issues should be kept separate. Each introduces its own concept. Reviewing and getting approval for changes is usually much harder than writing the code, and reducing scope helps with that. This requires that template_preprocess() is gone but this and #3495943: Handle module preprocess functions as OOP hooks can then be mostly parallel IMHO. If we all can agree on this being the way forward, your issue can be refactored to ignore template_* stuff entirely, #2340341: Move template_preprocess, _template_preprocess_default_variables into services already moves it out of the current $prefixes discovery loop. There will be a few conflict in Registry and ThemeHandler, but I'd expect them to be pretty easy to resolve.

I pushed an update to use the CallableResolver service, so this supports services now, converted template_preprocess_block() as an example.

The blocker is in, rebased.

This has a few remaining things (outlined in issue summary), but it needs architecture reviews on the concept and naming.

One thing to decide on is where those callbacks should live.

In my issue, as an example, I converted template_preprocess_container() to a static method directly on \Drupal\Core\Theme\ThemeCommonElements where it's also defined, And I converted template_preprocess_block() and put that on next to hook_theme in the block module, as a non-static method, so it's called as a service, but it's not a hook. I'm not sure if that's a good idea or not and what kind of patterns we want to adopt here.

Thoughts:
* As mentioned in the issue summary, there are a few issues that want to either define value objects for theme_hook definitions or convert the whole thing into plugin-like discovery with classes for each. If/Once we have the that, preprocess could just live on that. But no idea if that will ever happen
* Putting all the template_preprocesss_* callbacks of core include files into ThemeCommonElements wouldn't be a good fit. There are 11 in form.inc, they could be in a preprocess service in the form component. theme.inc has 20, from generic and low-level stuff like container, time and page to things that could live in their own component such as field, local task/action, breadcrumb and there's also some special maintenance stuff, that for example calls explicitly into template_preprocess_page()
* Should module template_preprocess callbacks be in the Hooks namespace? It's kind of nice to see them next to hook_theme(), but it's not really a hook, so kind of weird, especially considering all my complaining in #3495943: Handle module preprocess functions as OOP hooks about converting them to real hooks. Most modules only have a few of them, only a few have more than 5, by far most is views with 17. Maybe standardize on a preprocess service per module? And views and some complex cases could have separate ones.

Rebased.

Worked a bit more on this, introduced a ThemePreprocess service and moved a bunch of template_preprocess() callbacks into that, specifically those that use services, so we can see a bit more how that works with DI.

Doing all here is too much I think, especially since some of them should probably also live in different compoments, for example field templates could move to Drupal\Core\Field, either in a separate service or an existing one if something fits.

Also noticed a node dependency in template_preprocess_page(), that should probably move to node module, no reason for it to be there, but also kind of out of scope.

And, had to shuffle the bubbling stuff around a bit in ThemeManager, noticed while testing the installer that it wasn't called if there was only an initial preprocess and nothing else.

> let's convert enough in this issue to prove the concept,

Yes, that was the idea, convert a few different examples, including DI. One example more that could be considered would be one in an include file, so we can "prove" that we can remove and deprecate the file key then afterwards. but I think that's pretty obvious?

Remaining steps here:

1. Decide on BC. I removed them for now to make the review easier, but I think we want to keep at least the ones in theme.inc as a BC layer, there are a bunch of calls to them, for example the one in theme.inc about the maintenance (and then the install steps page chained). Not sure about the module ones, but there are far less than module hooks, so doesn't hurt too much to keep them. Plus, the BC layer is implicit and free, if there is an initial preprocess callback defined, we skip template_ discovery.

2. Remove references. Tons of twig files reference their template_preprocess_xy() function. We can either update them or remove them. I'm unsure what the value of that is and it's duplicated a lot and all the copy pasted templates into contrib/custom themes will be out of date now. So future changes might invalidate them again.

3. Change Record/documentation.

Oh, i hadn't seen that you already started a change record. I updated and extend it:

* Made it clear that this this is the new format and it replaces template_preprocess() (no "can"). Once this is committed, the old style is essentially deprecated and deprecations will be added once core is converted.
* Switched to block as example, because nobody except core will have to deal with the ThemeCommonElements and theme.inc stuff like that.
* Extended the example to include the hook_theme() definition in both cases
* Explained and linked the CallableResolver and what's supported and what not.
* Added example on how to provide BC with older core versions
* Adapted the breaking changes section, there is only a single template/initial preprocess (for a given theme hook, now that template_preprocess() is deprecated), you can't reorder them. while you could technically move them after other preprocess callbacks, I don't see a scenario for that, that would definitely cause problems. I strongly assume the main use case for that was just explicitly defining it for dynamically defined theme definitions.

I'd be ok with moving forward. there's still the question about the references in the template files. any preference in regards to updating or removing them? I'll try to ping Theme API maintainers over this issue in general and specifically this.

I added some docs, changed the theme.preprocess service, restored and deprecated the template_preprocess_HOOK() functions and also updated all @see references in templates for the converted ones. That blows up the diff stats quite a bit (64 files, + 688, − 394), since all the function docs are no longer removed.

Also had to reflow several comments due to the new enforced phpcs rules.

Pushed some docs improvements, I think that's sufficient? Since hook_theme() docs/example is non-OOP, I can't really put `static::class . ':preprocessList'` in there, but I mentioned in the docs above.

I moved date/time related preprocess to a separate class in the Datetime componen, that only needs the DateFormatter injected. Then we also have an example that we can build on for example for field templates. All other dependencies are for page and html templates, I don't think there's benefit in splitting that up.