diff --git a/docs/apis/_files/classes-dir.tsx b/docs/apis/_files/classes-dir.tsx index 7bacc979f6..ef801dddbd 100644 --- a/docs/apis/_files/classes-dir.tsx +++ b/docs/apis/_files/classes-dir.tsx @@ -21,6 +21,7 @@ import DefaultDescription from './classes-dir.mdx'; export default (initialProps: Props): ComponentFileSummary => ( +Details of legacy classes that have been moved to the classes directory to support autoloading but are not yet named properly. + +:::note + +Adding classes to `db/legacyclasses.php` is only necessary when the class is part of a _public_ API, or the class name cannot be changed. + +::: diff --git a/docs/apis/_files/db-legacyclasses-php.tsx b/docs/apis/_files/db-legacyclasses-php.tsx new file mode 100644 index 0000000000..e83e62e417 --- /dev/null +++ b/docs/apis/_files/db-legacyclasses-php.tsx @@ -0,0 +1,51 @@ +/** + * Copyright (c) Moodle Pty Ltd. + * + * Moodle is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Moodle is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Moodle. If not, see . + */ +import React from 'react'; +import { ComponentFileSummary } from '../../_utils'; +import type { Props } from '../../_utils'; +import DefaultDescription from './db-legacyclasses-php.mdx'; + +const defaultExample = ` +defined('MOODLE_INTERNAL') || die; + +$legacyclasses = [ + 'old_class_name' => 'path/within/classes/directory.php', + + // Examples: + \\coding_exception::class => 'exception/coding_exception.php', + \\moodle_exception::class => 'exception/moodle_exception.php', + + // Example loading a class from a different subsystem. + // This should typically only be used in core. + \\cache::class => [ + 'core_cache', // The name of the subsystem to load from. + 'cache.php', // The file name within that filesystem's classes directory. + ], +]; +`; + +export default (initialProps: Props): ComponentFileSummary => ( + +); diff --git a/docs/apis/_files/index.tsx b/docs/apis/_files/index.tsx index d106049452..76ac8c209f 100644 --- a/docs/apis/_files/index.tsx +++ b/docs/apis/_files/index.tsx @@ -26,6 +26,7 @@ import DbInstallPHP from './db-install-php'; import DbInstallXML from './install-xml'; import DbMessagesPHP from './db-messages-php'; import DbMobilePHP from './db-mobile-php'; +import DbLegacyclassesPHP from './db-legacyclasses-php'; import DbRenamedclassesPHP from './db-renamedclasses-php'; import DbServicesPHP from './db-services-php'; import DbTasksPHP from './db-tasks-php'; @@ -57,6 +58,7 @@ export { DbInstallXML, DbMessagesPHP, DbMobilePHP, + DbLegacyclassesPHP, DbRenamedclassesPHP, DbServicesPHP, DbTasksPHP, diff --git a/docs/apis/commonfiles/index.mdx b/docs/apis/commonfiles/index.mdx index c887bb2a23..f5749e95c9 100644 --- a/docs/apis/commonfiles/index.mdx +++ b/docs/apis/commonfiles/index.mdx @@ -17,6 +17,7 @@ import { DbInstallPHP, DbInstallXML, DbMessagesPHP, + DbLegacyclassesPHP, DbRenamedclassesPHP, DbServicesPHP, DbTasksPHP, @@ -99,6 +100,10 @@ import extraLangDescription from '../_files/lang-extra.md'; +### db/legacyclasses.php + + + ### classes/ diff --git a/docs/devupdate.md b/docs/devupdate.md index 2be79bf7bb..443ba32db3 100644 --- a/docs/devupdate.md +++ b/docs/devupdate.md @@ -47,6 +47,27 @@ Please note that the same limitations regarding access to the Database, Session, ::: +#### Autoloading legacy classes + + + +The Moodle class autoloader is now able to load legacy classes defined in the relevant `db/legacyclasses.php`. Files should only contain a single class. + +```php title="Example entry in lib/db/legacyclasses.php" +$legacyclasses = [ + // The legacy \moodle_exception class can be loaded from lib/classes/exception/moodle_exception.php. + \moodle_exception::class => 'exception/moodle_exception.php', + + // The legacy \cache class can be loaded from cache/classes/cache.php. + \cache::class => [ + 'core_cache', + 'cache.php', + ], +]; +``` + +See MDL-81919 for further information on the rationale behind this change. + ### SMS API A new SMS API was introduced. See the [SMS API documentation](./apis/subsystems/sms/index.md) for more information. diff --git a/project-words.txt b/project-words.txt index 5bd72af2c9..2516b16905 100644 --- a/project-words.txt +++ b/project-words.txt @@ -195,6 +195,7 @@ langindex lastaccess lastname lastruntime +legacyclasses locallib loglevel mainmenu