Merge pull request #1024 from andrewnicols/MDL-81919

[docs] Document use of legacyclasses.php

Author: andrewnicols

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,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 <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',
+
+    // 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 => (
+    <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

@@ -47,6 +47,27 @@ Please note that the same limitations regarding access to the Database, Session,
 
 :::
 
+#### Autoloading legacy classes
+
+<Since version="4.5" 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',
+
+    // 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.

project-words.txt

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