Problem/Motivation

Postponed on #3579629: Add procedural hooks to test theme to test collection and invoking legacy hooks so we can add some crucial testing back in.

There are no more functions I am aware of that must reside in .theme files, magic autoloading of .theme files can be the source of some very hard to find bugs.
There is a simple script to assist with converting the hooks in themes and remaining functions can almost just be copy pasted.
We should deprecate the .theme file extension
Important to note: This is not about deprecating the Extension type of themes, just the procedural .theme files.

Steps to reproduce

Proposed resolution

Check for .theme extension files during hook collection.
Add SuppressExtensionFileDeprecation attribute core and contrib can use to skip deprecations.
Emit deprecations for any .theme files without that attribute.

Remaining tasks

Review

Follow ups
Update general documentation:
https://www.drupal.org/docs/develop/theming-drupal
https://www.drupal.org/docs/develop/theming-drupal/drupal-theme-folder-s...
https://www.drupal.org/docs/8/theming-drupal-8/modifying-attributes-in-a...

Add requirements check: #3587107: Add requirements check for deprecated .theme file extensions
Test rector conversion:
https://github.com/palantirnet/drupal-rector/pull/325
https://gitlab.com/-/snippets/5975084

User interface changes

N/A

Introduced terminology

N/A

API changes

.theme files will no longer be autoloaded in Drupal 13.

Data model changes

N/A

Release notes snippet

CommentFileSizeAuthor
#55 3581218-nr-bot_4q5ndnjc.txt1.31 KBneeds-review-queue-bot
#47 3581218-nr-bot_rgwv154o.txt91 bytesneeds-review-queue-bot
#29 Screenshot 2026-04-24 at 11-03-07 Status report Drush Site-Install.png15.43 KBnicxvan

Issue fork drupal-3581218

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

nicxvan created an issue. See original summary.

nicxvan’s picture

nicxvan commented
Status: Active » Postponed

nicxvan changed the visibility of the branch 3581218-pp-1-deprecate-.theme to hidden.

nicxvan opened merge request !15190

nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Issue summary: View changes

Had a discussion in Slack with @berdir about this, he strongly thinks we should avoid doing it somewhere that gets hit on most requests or tests.

One potential is that we do it during install or in load ( I don't think that is often enough, though scanners can check no matter what )
We should add an ignore deprecation key to info.yml ignore_theme_file_deprecation

We should try to match what modules will need too since there are so many more modules when that finally drops too.

I think with this in mind, we add the key to info.yml
In Extension::load we set a flag for .theme files
Add a runtime_requirements hook that reports the list and triggers deprecations for ones that don't have ignore set

This obviously is runtime only, and only for installed themes, but @berdir contends that is enough.
We could explore checking the actual discovery result too, which would probably require adding the info yml key to the extension object even if just for a version or two.

Edit to add: I agree with @berdir where I have it now isn't quite right, I was just trying to see if tons of things blew up.

nicxvan’s picture

nicxvan commented
Issue summary: View changes
catch’s picture

catch
he/him
Primary language English
commented

Option #2 seems reasonable. I'm not sure how much we should worry about not installed themes, they're most likely to be on their way to being removed from a code base? Or installed in some other context when the warning will show.

nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Issue tags: +Needs release manager review, +Needs framework manager review

Tagging release manager and framework manager since this is the first time we've deprecated a file extension and I think we'll need feedback on when the removal is.

catch’s picture

catch
he/him
Primary language English
commented

I've been assuming we'd remove support in 13.0 so that we can also remove procedural hook discovery then.

nicxvan’s picture

nicxvan commented

Ok I converted this to the new approach and added the flag.

We may not need to postpone this actually.

nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Parent issue: » #3554670: [meta] Eliminate core .theme files
nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Title: [pp-1] Deprecate .theme file extension » Deprecate .theme file extension
Status: Postponed » Active
nicxvan’s picture

nicxvan commented

I took another look. I think doing the deprecation in ThemeHookCollectorPass will be difficult.

We don't have the info parameters we need.
@berdir and I briefly chatted in slack about skipping only if all functions are skipped in the collection, but that also ran into issues with tracking across themes. I think we can collect the info in THCP, but if we don't want the runtime we need somewhere else to actually throw the deprecations.

nicxvan’s picture

nicxvan commented

Looking at the kernel again and extension discovery the ignore_theme_file_deprecation should be available, I need to take another look.

Then we could properly deprecated in thcp.

nicxvan’s picture

nicxvan commented
Issue tags: +12.0.0 alpha blocker

I could be persuaded this isn't a blocker, but I think it fits the bill.

nicxvan’s picture

nicxvan commented

Ok I took another look:

We'd have to update ExtensionDiscovery to preserve the info parser info for themes to pass it into the kernel:

$type = $this->infoParser->parse($fileinfo->getPathname())['type'] ?? FALSE;
We need that so we can track the skipping.

This feels far too low level, we can adjust to the other plan and drop the manual way to skip and only skip if there are no procedural function not skipped in the theme. This feels like it defeats the purpose of having a skip though.

The thing is I think most people get notified about deprecations from upgrade status and tests. Maybe we do it in Extension::load? once we get the ThemeExtension in place?

berdir’s picture

berdir
Primary language German
Location Switzerland
commented

Agreed, .info.yml is not a good option.

For modules we could add another service parameter, won't work for themes. Adding support for services.yml in themes just for this seems overkill, although there _some_ use cases. \Drupal\default_admin\Settings really wants to be a service, it implements it's own singleton through the classResolver().

I'd prefer to avoid Extension::load() or anything at runtime/every request because of the overhead.

We could add another marker attribute like \Drupal\Core\Hook\Attribute\ProceduralHookScanStop, something like #AcknowledgeExtensionFileDeprecation. If we see that anywhere during parsing, we don't trigger the deprecation. And/Or we could also skip it if no functions are discovered as part of the scan. That would work for stable9.theme as only has two functions, both have the LegacyHook attribute. extra API functions could just slap that on too, doesn't hurt if someone cares. Or we could add support for the #Deprecated.

nicxvan changed the visibility of the branch main to hidden.

nicxvan opened merge request !15566

nicxvan changed the visibility of the branch 3581218-deprecate-theme-extension to hidden.

nicxvan’s picture

nicxvan commented

I hid the other branch, I think this is far more elegant, unfortunately we need another file cache for the deprecation suppression, but that feels small.

If this looks agreeable I will update the CR and the IS for the new approach.

Edit: we do still want a notice on the status report page, let me add that back.

nicxvan’s picture

nicxvan commented
StatusFileSize
new Screenshot 2026-04-24 at 11-03-07 Status report Drush Site-Install.png15.43 KB

Obsolete

.theme warning

nicxvan’s picture

nicxvan commented
Issue summary: View changes

Thinking about this further, I think this is the way to go, I'll update the IS and CR now.

nicxvan closed merge request !15190

nicxvan’s picture

nicxvan commented
Status: Active » Needs review
nicxvan’s picture

nicxvan commented

I created a follow up to discuss the requirements issue: #3587107: Add requirements check for deprecated .theme file extensions

nicxvan’s picture

nicxvan commented
nicxvan’s picture

nicxvan commented
Issue summary: View changes
berdir’s picture

berdir
Primary language German
Location Switzerland
commented
Status: Needs review » Needs work

Sorry for the nitpicks and back and forth, just trying to get this right as it's going to be a pretty big one once it lands.

nicxvan’s picture

nicxvan commented
Status: Needs work » Needs review

No worries!

nicxvan’s picture

nicxvan commented
Issue summary: View changes
nicxvan’s picture

nicxvan commented
Issue tags: +Needs subsystem maintainer review
berdir’s picture

berdir
Primary language German
Location Switzerland
commented
Status: Needs review » Reviewed & tested by the community

I think this is ready. See the open MR on whether or not we want to backport the deprecation to 11.4 or not. I think it can both ways. There's value in warning early, but there are also valid arguments on waiting for D12 Tooling isn't quite there yet still I think, might not want to push too hard yet on that just yet. Modules will definitely not happen in 11.4, we're not there yet in core despite making good progress on preparing core.

nicxvan’s picture

nicxvan commented
Issue summary: View changes
alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
commented
Status: Reviewed & tested by the community » Needs work

This looks great but I think the deprecation message can be improved.

nicxvan’s picture

nicxvan commented
Status: Needs work » Needs review

I think that's much clearer!

nicxvan’s picture

nicxvan commented

This is ready for review again.

smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

Feedback from 41 appears to be addressed and since it was previously RTBC going to move that direction too.

nicxvan’s picture

nicxvan commented
Issue tags: +11.5.0 release priority
needs-review-queue-bot’s picture

needs-review-queue-bot commented
Status: Reviewed & tested by the community » Needs work
StatusFileSize
new 3581218-nr-bot_rgwv154o.txt91 bytes

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.

nicxvan’s picture

nicxvan commented
Status: Needs work » Reviewed & tested by the community

Rebased, conflict was just the use statement for Settings.

nicxvan’s picture

nicxvan commented
Status: Reviewed & tested by the community » Needs work

Gotta handle the new theme files.

nicxvan’s picture

nicxvan commented
Status: Needs work » Needs review
berdir’s picture

berdir
Primary language German
Location Switzerland
commented
Status: Needs review » Reviewed & tested by the community

Update for the new test looks correct.

nicxvan changed the visibility of the branch 3581218-deprecate-theme-file-extension to hidden.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
commented
Status: Reviewed & tested by the community » Needs work

I think we should also improve:

  • the documentation for \Drupal\Core\Extension\ThemeHandlerInterface::themeExists() - there's no point in having the (without the .theme extension) anymore.
  • the documentation on \Drupal\Core\Extension\Theme::__construct() for $filename as this is basically deprecated (let's not trigger a deprecation but document somehow that this is not expected because at some point we're going to remove it.
  • the documentation on \Drupal\Core\Theme\ThemeManagerInterface::invoke() - there's no point in having the (without the .theme extension) anymore.

There is also \Drupal\system\Form\ThemeSettingsForm::buildForm() which includes .theme files (add theme-settings.php) and triggers a form alter :) - do we have an issue for OOifying that?

This would leave the following .theme references which imo are correct and should only be fixed once we no longer support .theme (ie. Drupal 13)

  • .gitattributes
  • core/.cspell.json
  • \Drupal\BuildTests\Command\GenerateThemeTest::testSimpleStarterkitTheme() tests that generate theme still works with themes with .theme
  • core/phpcs.xml
nicxvan’s picture

nicxvan commented
Status: Needs work » Needs review
Related issues: +#3580152: Deprecate theme-settings.php files

Good catch!

I've updated those three documentation points.

There is also \Drupal\system\Form\ThemeSettingsForm::buildForm() which includes .theme files (add theme-settings.php) and triggers a form alter :) - do we have an issue for OOifying that?

They are just hook_form_alters at the end of the day, they can already be OOP, there is #3580152: Deprecate theme-settings.php files for explicitly deprecating using that file though which is postponed on this issue.

This would leave the following .theme references which imo are correct and should only be fixed once we no longer support .theme (ie. Drupal 13)

I agree, I'm not sure when we clean up the .gitattributes, since we also have the .engine extension in there, but that can be a follow up.

needs-review-queue-bot’s picture

needs-review-queue-bot commented
Status: Needs review » Needs work
StatusFileSize
new 3581218-nr-bot_4q5ndnjc.txt1.31 KB

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.

nicxvan’s picture

nicxvan commented
Status: Needs work » Needs review

Missed a period.

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented
Issue tags: -Needs framework manager review

Agree with the deprecate in 12 remove in 13 timeline from a FM POV, removing the tag

nicxvan’s picture

nicxvan commented
Issue tags: -Needs subsystem maintainer review

Not sure why I added the subsystem maintainer tag.

berdir’s picture

berdir
Primary language German
Location Switzerland
commented
Status: Needs review » Needs work

needs work to possibly address the review, did reply to some points.

catch’s picture

catch
he/him
Primary language English
commented
Issue tags: -Needs release manager review

I'm not sure how much we need the attribute for themes but given we'll need it for modules and it makes sense to have parity between the two, seems fine to have it here. Everything apart from the attribute situation is pretty straightforward so removing the needs release manager review tag.

nicxvan’s picture

nicxvan commented
Status: Needs work » Needs review

Addressed the feedback, I think this is ready for review again.

smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

1 small question on the MR. It's small enough I'm not going to hold this up since it's got sign off on every level needed.

  • larowlan committed 62c7178d on main 
    task: #3581218 Deprecate .theme file extension

By: nicxvan
By: berdir...
larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented
Version: main » 11.x-dev
Status: Reviewed & tested by the community » Patch (to be ported)

Committed 62c7178 and pushed to main. Thanks!

Need a new MR for 11.5, setting to Patch (to be ported).

Published change record.

nicxvan opened merge request !16524

nicxvan opened merge request !16525

nicxvan’s picture

nicxvan commented

Are we backporting this? If we are we need to update the message on main.

11.x will require a fair bit more work since olivero and stable9 still have .theme files. I'm not sure if it's worth backporting.

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented

The 11.5.0 release priority tag you added made me think you were planning on it?

nicxvan’s picture

nicxvan commented

I forgot about that! :) yeah I think it's better to backport to be honest.

I'll add the ignore attribute to the themes since they are converted in 12.

nicxvan’s picture

nicxvan commented
Status: Patch (to be ported) » Needs review

I backported to 11.x and added the ignore tag to the three remaining .theme files since we've converted them all in main.
The only conflict was the test for deprecated themes since that had been removed in main and readded, but here it's just a new method.

I also opened a new MR against main for the deprecation version update.

smustgrave’s picture

smustgrave commented
Status: Needs review » Reviewed & tested by the community

Seems like a good backport. Congrats on landing this btw!

larowlan’s picture

larowlan
Location 🇦🇺🏝.au GMT+10
commented
Status: Reviewed & tested by the community » Fixed

Committed to 11.x and updated change record - thanks

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

  • larowlan committed 7298bd81 on 11.x 
    task: #3581218 Deprecate .theme file extension

By: nicxvan
By: berdir...

  • larowlan committed e83dee3a on main 
    task: #3581218 Deprecate .theme file extension

By: nicxvan
By: berdir...
quietone’s picture

quietone commented

I updated the change record but did not publish it as I have questions about it. I am going to ask in Slack first about it.

quietone’s picture

quietone commented
Status: Fixed » Needs work
Issue tags: +Needs change record updates

Changed my mind.

The questions are:

  1. what is the 'setting' that is referred to in the "Important Note" near the end of the change record
  2. Why is this mentioning changing 11.3.0?
  3. The script with the rector rule does not mention DDEV, why does the change record.
  4. Is there documentation on d.o about using #[SuppressExtensionFileDeprecation] ?
nicxvan’s picture

nicxvan commented
  1. The setting is the attribute. If you add the attribute it only silences the deprecation message.
  2. 11.3.0 is when OOP hook support was added to themes so that is when this was technically possible.
  3. It is a ddev script, I can update the gitlab rule to mention it's for ddev.
  4. There is no documentation on d.o about that attribute.
quietone’s picture

quietone commented
Status: Needs work » Fixed
Issue tags: -Needs change record updates

@nicxvan, thanks for the answers.

nicxvan and I also chatted in #core-development where I was still confused about the need to mention 11.3 in the change record. It comes down to me not knowing enough about themes and the whole converting to OO process. We also updated the change record making some small clarifications and the rector script was also changed to state that is it for DDEV.

I have published the change record.

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

ressa’s picture

ressa
he/him
commented

Thanks for the clean up. Under "Remaining tasks", there are links to a few doc pages in need of an update. I am not sure if some of these were tasks were done, and pages were created, but just not published yet?

There is a link in the Change Record .theme file extensions have been deprecated to a DDEV script, which may seem a bit complicated for some site builders ... so it would be nice if a new "Converting from .theme-file to an object oriented class" section was added on https://www.drupal.org/docs/8/theming-drupal-8/modifying-attributes-in-a..., which outlines how to convert the existing mytheme_preprocess_menu function to use the new method. Perhaps inspiration can be found in Hooks in themes can now be OOP?

Also, maybe a new documentation Page under https://www.drupal.org/docs/develop/theming-drupal could be created, documenting the new method for functions in themes, with a few examples? Hooks in themes can now be OOP could be an excellent starting point, which could be adjusted and expanded in this new doc page.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

nicxvan’s picture

nicxvan commented
Issue tags: +Needs release note, +11.5.0 release highlights