Merge branch 'main' into sesskey

Author: andrewnicols

data/moodle-contributors.txt

@@ -469,6 +469,7 @@ Hunkler
 Hunt
 Huong
 Hutchinson
+Huynh
 Hämmerle
 Hübler
 ISHIKAWA
@@ -871,6 +872,7 @@ Pinto
 Pisarev
 Piton
 Platts
+Poder
 Poggenpohl
 Pollak
 Poltawski
@@ -1157,6 +1159,7 @@ Walker
 Wallis
 Wandachowicz
 Ward
+Warwicker
 Watson
 Webster
 Wedekind

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/apis/subsystems/check/index.md

@@ -55,7 +55,7 @@ Checks are broken down into types, which roughly map to a step in the life cycle
 
 Available from _/admin/environment.php_, environmental checks make sure that a Moodle instance is fully configured.
 
-This page is a potential candidate to move to the new Check API but it slightly more complex than the other checks so hasn't been tackled yet. It would be a deeper change and this is intrinsically part of the install and upgrade system. It is not as critical to refactor as it is already possible for a plugin to declare its own checks, via either declarative [Environment checking](https://docs.moodle.org/dev/Environment_checking) or programmatically with a custom check:
+This page is a potential candidate to move to the new Check API but it slightly more complex than the other checks so it hasn't been tackled yet. It would be a deeper change and this is intrinsically part of the install and upgrade system. It is not as critical to refactor as it is already possible for a plugin to declare its own checks, via either declarative [Environment checking](https://docs.moodle.org/dev/Environment_checking) or programmatically with a custom check:
 
 ### Configuration checks
 

docs/apis/subsystems/output/index.md

@@ -278,11 +278,11 @@ Please note that this function is a stripped version of the full `format_text()`
 
 Some interesting parameters for this function are:
 
-- `striplinks`: Set to `false` to remove all links after the text has been processed by filters. Used when we want to show the text inside menus, page titles, etc. (Default is `true`)
+- `striplinks`: Set to `false` to keep all links after the text has been processed by filters. Used when we want to show the text inside menus, page titles, etc. (Default is `true`)
 - `options`
   - `options->context`: Context (id or object) for applying filters. If context is not specified it will be taken from `$PAGE->context` and may potentially result in displaying the same text differently on different pages. For example, all module-related information should have module context even when it appears in course-level reports, all course-related information such as name and description should have course context even when they are displayed on the front page or system pages.
   - `options->escape`: Set to `false` if you do not want to escape HTML entities. (Default is `true`)
-  - `options->filter`: Set to `false` if you want to allow filters to process the text. This is ignored by `FORMAT_PLAIN` for which filters are never applied.  (Default to `true`)
+  - `options->filter`: Set to `false` if you do not want to allow filters to process the text. This is ignored by `FORMAT_PLAIN` for which filters are never applied. (Default is `true`)
 
 ### Simple elements rendering
 
@@ -346,6 +346,101 @@ In the standard Boost theme this method will output a span using the [Bootstrap
 <span class="sr-only">Contents</span>
 ```
 
+### Other
+
+#### Progress Bars
+
+There are two types of progress bars you can use in Moodle.
+
+##### Standard Progress Bars
+
+The first is the old standard progress bar which updates as the page loads (ie. the page won't fully load until the progress bar is finished). It can be used to render the current process on the page, or via cli to render the progress of a script.
+
+Example:
+
+```php
+<?php
+define('NO_OUTPUT_BUFFERING', true); // Required if not used via cli.
+require 'config.php';
+
+$PAGE->set_context(context_system::instance());
+$PAGE->set_url('/');
+
+echo $OUTPUT->header();
+
+$pb = new \core\output\progress_bar('bar', 500);
+$pb->create();
+$num_tasks = 500; // the number of tasks to be completed.
+for($cur_task = 0; $cur_task <= $num_tasks; $cur_task++)
+{
+    for ($i=0; $i<100000; $i++)
+    {
+        ;;;
+    }
+    $pb->update($cur_task, $num_tasks, 'this is'. $cur_task . 'h');
+}
+
+echo $OUTPUT->footer();
+```
+
+##### Stored Progress Bars
+
+The other type of progress bar you can use is a stored progress bar, which can be used to store and update the progress of a long-running task in the database, and render live updates to the web page via AJAX web service polling.
+
+It can be implemented into a CLI script. Example:
+
+```php
+<?php
+
+define('CLI_SCRIPT', true);
+
+require_once('config.php');
+require_once($CFG->libdir . '/clilib.php');
+
+$num_tasks = 5000; // the number of tasks to be completed.
+
+$progress = new \core\output\stored_progress_bar('example-cli-bar');
+$progress->start();
+
+for($cur_task = 0; $cur_task <= $num_tasks; $cur_task++)
+{
+    $progress->update($cur_task, $num_tasks, 'this is '. $cur_task . '/' . $num_tasks);
+}
+
+mtrace('DONE');
+```
+
+Or a scheduled or adhoc task, via a trait. Example:
+
+```php
+class stored_progress_scheduled_task_example extends \core\task\scheduled_task {
+
+    use \core\task\stored_progress_task_trait;
+
+    public function execute() {
+
+        // This simulates a specific count of iterations the task will do, e.g. x number of courses to loop through and do something.
+        $iterations = 100;
+
+        $this->start_stored_progress(); // This creates the stored progress record for the named task.
+
+        for ($i = 1; $i <= $iterations; $i++) {
+
+            // Here we just update and tell it which one we are on and it will work out % from those.
+            $this->progress->update($i, $iterations, 'i am at ' . $i  . ' of ' . $iterations);
+            sleep(1);
+
+        }
+
+        return true;
+
+    }
+
+}
+```
+
+With the stored progress bars, you can update the progress either via iterations, by passing in the total amount expected and then the current iteration, using `->update()`(see: previous example), this will calculate the percentage complete for you. Or you can use `->update_full()` to manually set the percentage complete.
+
 ## See also
 
 - [HTML Guidelines](https://docs.moodle.org/dev/HTML_Guidelines)

docs/devupdate.md

@@ -35,7 +35,7 @@ https://yourmoodlesite/badges/edit.php?courseid=x&mode=new
 
 #### `ABORT_AFTER_CONFIG`
 
-<Since version="4.4" issueNumber="MDL-80275" />
+<Since version="4.5" issueNumber="MDL-80275" />
 
 Prior to Moodle 4.5 only a small number of classes were compatible with scripts using the `ABORT_AFTER_CONFIG` constant.
 
@@ -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.
@@ -142,3 +163,11 @@ class core_renderer extends \core_renderer {
 </TabItem>
 
 </Tabs>
+
+### Refactoring BS4 features dropped in BS5 using a "bridge"
+
+<Since version="4.5" issueNumber="MDL-79917" />
+
+Some of the Bootstrap 4 classes will be deprecated or dropped in its version 5. To prepare for this, some of the current Bootstrap 4 classes usages have been replaced with version 5 compatible classes using a "bridge". This will help us to upgrade to Bootstrap 5 in the future.
+
+See more information in [Bootstrap 5 migration](./guides/bs5migration/index.md).

docs/guides/bs5migration/index.md

@@ -248,3 +248,33 @@ The `.no-gutters` grid class has been replaced with `.g-0`.
 ```
 
 </ValidExample>
+
+### Close button
+
+The `.close` class has been replaced with `.btn-close`.
+
+<InvalidExample title="Don't">
+
+```html
+<div class="alert alert-warning alert-dismissible" role="alert">
+  I'm an alert.
+  <button type="button" class="close" data-dismiss="alert" aria-label="Close">
+    <span aria-hidden="true">&times;</span>
+  </button>
+</div>
+```
+
+</InvalidExample>
+
+<ValidExample title="Do">
+
+```html
+<div class="alert alert-warning alert-dismissible" role="alert">
+  I'm an alert.
+  <button type="button" class="btn-close" data-dismiss="alert" aria-label="Close">
+    <span aria-hidden="true">&times;</span>
+  </button>
+</div>
+```
+
+</ValidExample>

general/development/policies/codingstyle/index.md

@@ -1936,7 +1936,21 @@ All functions and methods should have a complete docblock like this:
 
 You must include a description even if it appears to be obvious from the `@param` and/or `@return` lines.
 
-An exception is made for overridden methods which make no change to the meaning of the parent method and maintain the same arguments/return values. In this case you should omit the comment completely. Use of the `@inheritdoc` or `@see` tags is explicitly forbidden as a replacement for any complete docblock.
+An exception is made for overridden methods which make no change to the meaning of the parent method and maintain the same arguments/return values. In this case you should omit the comment completely, and apply the `#[\Override]` attribute. This can safely be applied in older versions of PHP before the attribute was supported. Use of the `@inheritdoc` or `@see` tags is explicitly forbidden as a replacement for any complete docblock.
+
+<ValidExample>
+
+```php
+class example implements templatable {
+
+    #[\Override]
+    public function export_for_template(renderer_base $output) {
+        return ['foo' => 'bar'];
+    }
+}
+```
+
+</ValidExample>
 
 ### Defines
 
@@ -2056,6 +2070,10 @@ To get the full list of exception types, search for the regular expression 'clas
 
 Where appropriate, you should create new subclasses of moodle_exception for use in your code.
 
+<Since version="4.5" issueNumber="MDL-81903" />
+
+If you create a custom exception class it *may* live in the `classes/exception/` directory, and be namespaced in `<plugin>/exception/`
+
 A few notable exception types:
 
 - `moodle_exception`: base class for exceptions in Moodle. Use this when a more specific type is not appropriate.

general/development/tools/behat/writing.md

@@ -113,7 +113,7 @@ In PhpStorm or IntelliJ you can install the behat extension. Then you get auto c
 
 Most of the steps requires values, there are methods to provide values to steps, the method depends on the step specification.
 
-- **A string/text** is the most common case, the texts are wrapped between double quotes (`"` character) you have to replace the info about the expected value for your value; for example something like **I press "BUTTON_STRING"** should become **I press "Save and return to course"**. If you want to add a string which contains a " character, you can escape it with \", for example **I fill the "Name" field with "Alan alias \"the legend\""**. You can identify this steps because they ends with **_STRING**
+- **A string/text** is the most common case, the texts are wrapped between double quotes (`"` character) you have to replace the info about the expected value for your value; for example something like **I press "BUTTON_STRING"** should become **I press "Save and return to course"**. If you want to add a string which contains a " character, you can escape it with a backslash `\"`, for example **I fill the "Name" field with "Alan alias \\"the legend\\""**. You can identify this steps because they ends with **_STRING**
 - **A number** some steps requires numbers as values, to be more specific an undetermined number of digits from 0 to 9 (Natural numbers + 0) you can identify them because the expected value info string ends with **_NUMBER**
 - **A table**; is a relation between values, the most common use of it is to fill forms. The steps which requires tables are easily identifiable because they finish with **:** The steps description gives info about what the table columns must contain, for example **Fills a moodle form with field/value data**. Here you don't need to escape the double quotes if you want to include them as part of the value.
 - **A PyString** is a multiline string, most commonly used to fill out forms when a newline is required. Like steps with tables, steps which require PyStrings will end with ":"

project-words.txt

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

versioned_docs/version-4.1/guides/javascript/modal/index.md

@@ -145,7 +145,7 @@ We highly recommend declaring the _template_ as a static property on the class t
 
 ```javascript title="mod/example/amd/src/my_modal.js"
 import Modal from 'core/modal';
-import ModalFactory from 'core/modal_factory';
+import ModalRegistry from 'core/modal_registry';
 
 export default class MyModal extends Modal {
     static TYPE = "mod_example/my_modal";