Skip to content

Load loadInclude() files even when the LoadIncludes rule is off - #1095

Closed
mglaman wants to merge 1 commit into
mainfrom
bug-741-load-includes-without-rules
Closed

mglaman wants to merge 1 commit into
mainfrom
bug-741-load-includes-without-rules

Conversation

@mglaman

@mglaman mglaman commented Nov 10, 2026

Copy link
Copy Markdown
Owner

Fixes #741.

Functions declared in a file loaded by ModuleHandlerInterface::loadInclude() were only known to PHPStan because the LoadIncludes rule ran require_once on the file. Without that rule, calls to them fail:

$this->moduleHandler->loadInclude('locale', 'inc', 'locale.fetch');
locale_translation_flush_projects();
Function locale_translation_flush_projects not found.

That happened in two cases:

  • A project includes only extension.neon. The README's manual installation section presents rules.neon as optional. This is what Drush hit, and they worked around it by registering LoadIncludes by hand.
  • A project sets drupal.rules.loadIncludes: false. Turning off a rule shouldn't add errors.

phpstan/extension-installer includes both files, so most projects never saw it.

Change

  • IncludeLoader resolves the module and file of a loadInclude() call, loads it with require_once, and keeps the result for each file. PHP won't run a file twice, so whichever caller runs first, the rule or the extension, the other gets the same result. Before, a file that threw while loading was only reported the first time.
  • ModuleHandlerLoadIncludeReturnTypeExtension is registered in extension.neon. PHPStan resolves the return type of every loadInclude() call, so the file is loaded whether or not the rule runs. The return type doesn't change.
  • LoadIncludes and ModuleLoadInclude use IncludeLoader. Their messages and identifiers are the same.
  • The README's loadIncludes toggle comment now says the include is loaded either way.

module_load_include() still only loads through its rule. It was removed in Drupal 11, so it only matters on Drupal 10, which reaches end of life next month.

Tests

  • New LoadIncludeWithoutRulesTest runs only PHPStan's CallToNonExistentFunctionRule on a call to a function from phpstan_fixtures.loader.inc. It fails on main with "Function phpstan_fixtures_function_from_load_include not found." It passes with the extension, and fails again with the extension untagged. The include file is only used by this test, so another test can't have loaded it first.
  • LoadIncludesRuleTest and ModuleLoadIncludeRuleTest pass unchanged.
  • php vendor/bin/phpunit (924 tests), phpcs and phpstan analyze pass.

Drush

Drush can drop the hand-registered LoadIncludes rule after this. Drush also excludes src/Commands/core/LanguageAddCommand.php with the note "Unclear why the phpstan-drupal rule is not working". That one isn't this bug: the failing call is drush_locale_translation_default_update_options(), which Drush defines in its own includes/legacy.inc. It needs scanFiles: [includes/legacy.inc].

🤖 Generated with Claude Code

Functions from a ModuleHandlerInterface::loadInclude() file were only
known because the LoadIncludes rule ran require_once on it. A project
that only includes extension.neon, or turns off
drupal.rules.loadIncludes, got "Function ... not found" for them.

- IncludeLoader resolves and loads the file once and keeps the result,
  so the rules and the extension report the same outcome.
- ModuleHandlerLoadIncludeReturnTypeExtension, in extension.neon, loads
  the file whenever the call is analyzed.
- LoadIncludes and ModuleLoadInclude use IncludeLoader. Their messages
  and identifiers don't change.

module_load_include() keeps loading through its rule only: it was
removed in Drupal 11.

Fixes #741.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mglaman

mglaman commented Nov 10, 2026

Copy link
Copy Markdown
Owner Author

Closing in favor of a README fix. #741 came from a manual setup that included only extension.neon. Documenting that rules.neon loads loadInclude() files fixes that without changing behavior. Moving the loading into extension.neon would also have removed the only way to stop include files from running, which turning off drupal.rules.loadIncludes gives today.

@mglaman mglaman closed this Nov 10, 2026
@mglaman
mglaman deleted the bug-741-load-includes-without-rules branch November 10, 2026 22:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ModuleHandler->loadInclude() call is not being processed

1 participant