Bitrix D7 Loader

When to use

• The user is wiring up autoloading for a module's namespaced classes or a custom module's classes — resolving a "class not found" that stems from a module not being loaded, or registering a class autoload map.
• The user needs to include a Bitrix module — Loader::includeModule('iblock') (D7) or the legacy CModule::IncludeModule() — before touching that module's classes, ORM, or functions.
• The user needs to know if a module is present before using it — checking availability, guarding an optional feature, or branching on whether sale, catalog, or a custom module is installed.

When NOT to use

• Do not use this skill to bootstrap the kernel, read the Request, or resolve Application/Context services — that is the kernel (main module) concern, not the Loader's job of including modules.
• Do not use this skill on a non-Bitrix PHP app (plain PHP, Laravel, Symfony); \Bitrix\Main\Loader and the module system do not exist outside 1C-Bitrix.

Core guidance

• Prefer the D7 Loader for new code — In new code use \Bitrix\Main\Loader::includeModule() rather than the legacy CModule::IncludeModule(); both include the module, but the D7 Loader is the namespaced, current API.

Quick recipe

1. At the top of the entry point call if (!\Bitrix\Main\Loader::includeModule('iblock')) { ... } and handle the false branch before any module class is referenced. (verify: A missing iblock module reaches the false branch instead of fataling later.)
2. In the false branch, throw a \Bitrix\Main\LoaderException when the module is required, or set a fallback and skip the feature when the module is optional. (verify: Required-module failures raise a named exception; optional ones return a fallback.)
3. Only after the guard passes, reference the module's namespaced classes (for example \Bitrix\Iblock\ElementTable); autoloading is now wired up. (verify: The module's classes resolve without a class-not-found error.)

Best practices

• Guard every Loader::includeModule('iblock') (or legacy CModule::IncludeModule) with a check on its boolean return, and bail out early when the module is missing
• When a module is required for the code to work at all, fail fast — throw a \Bitrix\Main\LoaderException or a \RuntimeException immediately after a false return — instead of continuing and letting a later call fatal
• Include a module once near the top of the entry point (controller, component, agent) that needs it, not repeatedly deep inside loops or helper functions; the Loader already caches the result, so scatter buys nothing and hides dependencies
• When a module powers only an optional feature, branch on the false return and degrade gracefully — hide the feature or use a fallback — rather than throwing
• For a custom module's classes that live outside the PSR-4 lib/ convention, map them with Loader::registerAutoLoadClasses('vendor.module', [...]) inside the module's include.php instead of hand-writing require calls

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Referencing module classes before the module is included — Using a module class such as \Bitrix\Iblock\ElementTable before Loader::includeModule('iblock') has run throws a fatal "class not found". Fix: Include the module first and check the boolean result; reference its classes only after a successful inclusion, returning a handled error otherwise.
2. Calling the Loader before the kernel is bootstrapped — In a standalone CLI script or cron entry, calling Loader::includeModule() before including the Bitrix kernel prologue fails because the Loader class itself is not yet defined. Fix: Require the kernel bootstrap (for example the site's prolog_before.php / DocumentRoot bootstrap) at the top of the script, then call the Loader.
3. Passing the wrong module identifier — includeModule silently returns false for a mistyped or wrong identifier — catalog vs sale, or a custom module's folder name vs its vendor.module id — so the module never loads and later class use fatals. Fix: Use the exact module identifier (the folder name under bitrix/modules, e.g. vendor.mymodule), and treat a false return as "not available" rather than assuming a typo cannot happen.

Version notes

• The D7 Loader supersedes CModule::IncludeModule — \Bitrix\Main\Loader::includeModule() is the current D7 way to include a module; the legacy CModule::IncludeModule() remains available as a thin compatibility wrapper over the same mechanism for older code.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/bitrix/d7-loader.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: bitrix/kernel-main-module
Related: bitrix/d7-events