[docs] Document use of legacyclasses.php

docs/apis/_files/classes-dir.tsx

@@ -21,6 +21,7 @@ import DefaultDescription from './classes-dir.mdx';
 
 export default (initialProps: Props): ComponentFileSummary => (
     <ComponentFileSummary
+        refreshedDuringPurge
         filepath="/classes/"
         summary="Autoloaded classes"
         defaultDescription={DefaultDescription}

docs/apis/_files/db-legacyclasses-php.mdx

@@ -0,0 +1,8 @@
+<!-- markdownlint-disable first-line-heading -->
+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.
+
+:::

docs/apis/_files/db-legacyclasses-php.tsx

@@ -0,0 +1,44 @@
+/**
+ * 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 <http://www.gnu.org/licenses/>.
+ */
+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',
+];
+`;
+
+export default (initialProps: Props): ComponentFileSummary => (
+    <ComponentFileSummary
+        refreshedDuringPurge
+        defaultExample={defaultExample}
+        defaultDescription={DefaultDescription}
+        filepath="/db/legacyclasses.php"
+        summary="Legacy classes"
+        examplePurpose="Legacy classes"
+        {...initialProps}
+    />
+);

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,

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';
 
 <DbRenamedclassesPHP />
 
+### db/legacyclasses.php
+
+<DbLegacyclassesPHP />
+
 ### classes/
 
 <ClassesDir />

docs/devupdate.md

@@ -27,6 +27,21 @@ Please note that the same limitations regarding access to the Database, Session,
 
 :::
 
+#### Autoloading legacy classes
+
+<Since version="4.4" issueNumber="MDL-81919" />
+
+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',
+];
+```
+
+See MDL-81919 for further information on the rationale behind this change.
+
 ## Reset course page
 
 The reset course page has been improved. The words "Delete", and "Remove" have been removed from all options to make it easier to focus on the type of data to be removed and avoid inconsistencies and duplicated information.

project-words.txt

@@ -192,6 +192,7 @@ langindex
 lastaccess
 lastname
 lastruntime
+legacyclasses
 locallib
 loglevel
 mainmenu