Moodle API Guides

https://moodledev.io/docs/5.2/apis
Admin
Moodle API Guides provide comprehensive documentation for the core APIs available in Moodle,...
Tokens:321,284
Snippets:3,075
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Initial Course Query - PHP

Source: https://moodledev.io/docs/5.2/apis/subsystems/favourites

An example of a basic SQL query to retrieve course IDs and names from the database. This serves as the starting point before integrating favourite information.

```php
$sql = "SELECT c.id, c.name  

          FROM {course} c  

         WHERE c.category = :category";  
$params = ['category' => 3];  

$courses = $DB->get_records_sql($sql, $params);
```

--------------------------------

### Define Path Parameter with Example

Source: https://moodledev.io/docs/5.2/apis/subsystems/routing/parameters

Shows how to define a path parameter named 'themename' with a specific type and provide an example of its usage.

```php
new path_parameter(

    name: 'themename',

    type: param::ALPHANUMEXT,

    examples: [

        new \core\router\schema\example(

            name: 'The Boost theme',

            value: 'boost',

        ),

    ],

)
```

--------------------------------

### Example `lti_get_course_content_items` Implementation

Source: https://moodledev.io/docs/5.2/apis/plugintypes/mod/activitymodule

This is an example of how the `lti_get_course_content_items` callback can be implemented in core Moodle for LTI plugins.

```php
function lti_get_course_content_items(string $courseid):
    return [
        new 
        content_item_link(
            'lti',
            'lti_external',
            'LTI',
            new moodle_url('/mod/lti/view.php'),
            'An LTI tool'
        )
    ];
```

--------------------------------

### Full Example of Mapped Property Parameter

Source: https://moodledev.io/docs/5.2/apis/subsystems/routing/parameters

A comprehensive example demonstrating a mapped property parameter for courses. It includes name, type, description, and examples of correct usage, utilizing `get_schema_from_type` for detailed pattern descriptions.

```php
namespace core\router\parameters;  

use core\exception\not_found_exception;  
use core\param;  
use core\router\schema\example;  
use core\router\schema\parameters\mapped_property_parameter;  
use core\router\schema\referenced_object;  
use Psr\Http\Message\ServerRequestInterface;  
  
/**  
 * A Moodle parameter referenced in the path.  
 *  
 * @package    core  
 * @copyright  2023 Andrew Lyons <andrew@nicols.co.uk>  
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later  
 */  
class path_course extends \core\router\schema\parameters\path_parameter implements  

    referenced_object,  

    mapped_property_parameter  
{
    /**  
     * Create a new path_course parameter.  
     *  
     * @param string $name The name of the parameter to use for the course identifier  
     * @param mixed ...$extra Additional arguments  
     */  
    public function __construct(  

        string $name = 'course',

        ...$extra,

    ) {
        $extra['name'] = $name;

        $extra['type'] = param::RAW;

        $extra['description'] = <<<EOF  

        The course identifier.  

        This can be the id of the course, the idnumber of the course, or the shortname of the course.  

        If specifying a course idnumber, the value should be in the format `idnumber:[idnumber]`.  

        If specifying a course shortname, the value should be in the format `name:[shortname]`.  
        EOF;

        $extra['examples'] = [

            new example(  

                name: 'A course id',

                value: 54,  

            ),

            new example(  

                name: 'A course specified by its idnumber',

                value: 'idnumber:000117-physics-101-1',

            ),

            new example(  

                name: 'A course specified by its shortname',

                value: 'name:000117-phys101-0',

            ),

        ];  

        parent::__construct(...$extra);

    }

    /**  
     * Get the course object for the given identifier.  
     *  
     * @param string $value A course id, idnumber, or shortname  
     * @return object  
     * @throws not_found_exception If the course cannot be found  
     */  
    protected function get_course_for_value(string $value): mixed {
        global $DB;

        $data = false;

        if (is_numeric($value)) {

            $data = $DB->get_record('course', [

                'id' => $value,

            ]);

```

--------------------------------

### Example Moodle File Serving Callback Implementation

Source: https://moodledev.io/docs/5.2/apis/subsystems/files

An example implementation of the file serving callback for an activity module. It includes context and capability checks, and demonstrates how to extract itemid and filepath from arguments.

```php
/**
 * Serve the files from the myplugin file areas.
 *
 * @param stdClass $course the course object
 * @param stdClass $cm the course module object
 * @param stdClass $context the context
 * @param string $filearea the name of the file area
 * @param array $args extra arguments (itemid, path)
 * @param bool $forcedownload whether or not force download
 * @param array $options additional options affecting the file serving
 * @return bool false if the file not found, just send the file otherwise and do not return anything
 */
function mod_myplugin_pluginfile(
    $course,
    $cm,
    $context,
    string $filearea,
    array $args,
    bool $forcedownload,
    array $options = []
): bool {
    global $DB;

    // Check the contextlevel is as expected - if your plugin is a block, this becomes CONTEXT_BLOCK, etc.
    if ($context->contextlevel != CONTEXT_MODULE) {
        return false;
    }

    // Make sure the filearea is one of those used by the plugin.
    if ($filearea !== 'expectedfilearea' && $filearea !== 'anotherexpectedfilearea') {
        return false;
    }

    // Make sure the user is logged in and has access to the module (plugins that are not course modules should leave out the 'cm' part).
    require_login($course, true, $cm);

    // Check the relevant capabilities - these may vary depending on the filearea being accessed.
    if (!has_capability('mod/myplugin:view', $context)) {
        return false;
    }

    // The args is an array containing [itemid, path].
    // Fetch the itemid from the path.
    $itemid = array_shift($args);

    // The itemid can be used to check access to a record, and ensure that the
    // record belongs to the specifeid context. For example:
    if ($filearea === 'expectedfilearea') {
        $post = $DB->get_record('myplugin_posts', ['id' => $itemid]);
        if ($post->myplugin !== $context->instanceid) {
            // This post does not belong to the requested context.
            return false;
        }

        // You may want to perform additional checks here, for example:
        // - ensure that if the record relates to a grouped activity, that this
        //   user has access to it
        // - check whether the record is hidden
        // - check whether the user is allowed to see the record for some other
        //   reason.

        // If, for any reason, the user does not hve access, you can return
        // false here.
    }

    // For a plugin which does not specify the itemid, you may want to use the following to keep your code consistent:
    // $itemid = null;

    // Extract the filename / filepath from the $args array.
    $filename = array_pop($args); // The last item in the $args array.
    if (empty($args)) {
        // $args is empty => the path is '/'.
        $filepath = '/';
    } else {
        // $args contains the remaining elements of the filepath.
        $filepath = '/' . implode('/', $args) . '/';
    }

```

--------------------------------

### Test Default Datasource Setup

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder

Verify the default report setup by creating a category and course, then generating a report. Assert that the content has the expected number of rows and that the data is correctly ordered and formatted.

```php
    /**  
     * Test default datasource  
     */  
    public function test_datasource_default(): void {  
        $this->resetAfterTest();  
  
        $category = $this->getDataGenerator()->create_category(['name' => 'Zoo', 'idnumber' => 'Z01']);  
        $course = $this->getDataGenerator()->create_course(['category' => $category->id]);  
  
        /** @var core_reportbuilder_generator $generator */  
        $generator = $this->getDataGenerator()->get_plugin_generator('core_reportbuilder');  
        $report = $generator->create_report(['name' => 'My report', 'source' => categories::class, 'default' => 1]);  
  
        $content = $this->get_custom_report_content($report->get('id'));  
        $this->assertCount(2, $content);  
  
        // Default columns are name, idnumber, coursecount. Sorted by name ascending.  
        $this->assertEquals([  
            [get_string('defaultcategoryname'), '', 0],  
            [$category->get_formatted_name(), $category->idnumber, 1],  
        ], array_map('array_values', $content));  
    }  
```

--------------------------------

### Pluginskeleton Recipe Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/blocks

This is an example recipe file for Tool Pluginskel, used to generate a basic block plugin skeleton. It demonstrates how to specify component names and view file contents.

```yaml
## This is an example recipe file that you can use as a template for your own plugins.  

## See the list of all files it would generate:  

##  

##     php generate.php example.yaml --list-files  

##  

## View a particular file contents without actually writing it to the disk:  

##  

##     php generate.php example.yaml --file=version.php  

##  

## To see the full list of options, run:  

##  

##     php generate.php --help  

##  

---

## Frankenstyle component name.  

component: block_pluginname  


```

--------------------------------

### Activity Module Supports Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/mod

An example implementation of the `[modname]_supports` function, returning specific feature support statuses and the module's primary purpose.

```php
function [modname]_supports($feature) {

    return match ($feature) {

        FEATURE_GROUPS => true,

        FEATURE_GROUPINGS => true,

        FEATURE_MOD_INTRO => true,

        FEATURE_COMPLETION_TRACKS_VIEWS => true,

        FEATURE_GRADE_HAS_GRADE => true,

        FEATURE_BACKUP_MOODLE2 => true,

        FEATURE_SHOW_DESCRIPTION => true,

        FEATURE_MOD_PURPOSE => MOD_PURPOSE_COLLABORATION,

        default => null,

    };

}
```

--------------------------------

### Example: Set Preference and Retrieve All

Source: https://moodledev.io/docs/5.2/apis/core/preference

Shows setting one preference and then retrieving all current preferences for the user.

```php
set_user_preference('foo_showavatars', 'no');

// returns [
//     foo_nameformat  => "long",
//     foo_showavatars => "no",
// ];
get_user_preferences();

```

--------------------------------

### Example: Set and Retrieve a Preference

Source: https://moodledev.io/docs/5.2/apis/core/preference

Demonstrates setting a single preference and then retrieving its value.

```php
set_user_preference('foo_nameformat', 'long');

// Returns the string - "long"
get_user_preferences('foo_nameformat');

```

--------------------------------

### AI Provider Plugin Directory Layout Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/ai/provider

Illustrates the typical directory structure for an AI provider plugin, using OpenAI as a specific example.

```directory
.  
├── amd  │   ├── build  │   │      ├── modelchooser.min.js  │      └── modelchooser.min.js.map  │   └── src  ││      └── modelchooser.js  ├── classes  │   ├── abstract_processor.php  │   ├── aimodel  │   │      ├── gpt4o.php  │      └── o1.php  │   ├── form  │   │      ├── action_form.php  │      ├── action_generate_image_form.php  │      └── action_generate_text_form.php  │   ├── helper.php  │   ├── hook_listener.php  │   ├── privacy  │   │      └── provider.php  │   ├── process_generate_image.php  │   ├── process_generate_text.php  │   ├── process_summarise_text.php  │   └── provider.php  ├── db  │   └── hooks.php  ├── lang  │   └── en  ││      └── aiprovider_openai.php  ├── tests  │   ├── fixtures  │   │      ├── image_request_success.json  │      ├── test.jpg  │      └── text_request_success.json  │   ├── process_generate_image_test.php  │   ├── process_generate_text_test.php  │   ├── process_summarise_text_test.php  │   └── provider_test.php  └── version.php  
```

--------------------------------

### Example: Add and Update Preferences

Source: https://moodledev.io/docs/5.2/apis/core/preference

Illustrates adding new preferences and updating an existing one using `set_user_preferences()`.

```php
$preferences = [

    'foo_displaynum' => '100',

    'foo_nameformat' => 'short',

];

set_user_preferences($preferences);

// returns [
//     foo_nameformat  => "short",
//     foo_showavatars => "no",
//     foo_displaynum  => "100",
// ];
get_user_preferences();

```

--------------------------------

### Repository Plugin lib.php Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/repository

This example shows the structure of a lib.php file for a Moodle repository plugin. It defines user-specific options, global type options, and handles plugin initialization. Use this as a template for your repository plugin's lib.php file.

```php
<?php  

// This file is part of Moodle - http://moodle.org/  

//  

// 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/>.  

  

/**  

 * Plugin functions for the repository_pluginname plugin.  

 *  

 * @package   repository_pluginname  

 * @copyright Year, You Name <your@email.address>  

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later  

 */  

  
defined('MOODLE_INTERNAL') || die();  

  

require_once($CFG->dirroot . '/repository/lib.php');  

  

class repository_flickr_public extends repository {  

  

    // User specific settings.  

  

    /**  

     * Options names.  

     *  

     * Tell the API that the repositories have specific settings: "email address"  

     *  

     * @return string[] of options.  

     */  

    public static function get_instance_option_names() {  

        return ['email_address'];  

    }  

  

    /**  

     * Repository configuration form.  

     *  

     * Add an "email address" text box to the create/edit repository instance Moodle form  

     *  

     * @param moodleform $mform Moodle form  

     */  

    public static function instance_config_form($mform) {  

        $mform->addElement(  

            'text',  

            'email_address',  

            get_string('emailaddress', 'repository_flickr_public')  

        );  

        $mform->addRule(  

            'email_address',  

            get_string('required'),  

            'required',  

            null,  

            'client'  

        );  

    }  

  

    // Global repository plugin settings.  

  

    /**  

     * Repository global settings names.  

     *  

     * We tell the API that the repositories have general settings: "api_key"  

     *  

     * @return string[] of options.  

     */  

    public static function get_type_option_names() {  

        return array('api_key');  

    }  

  

    /**  

     * Repository global settings form.  

     *  

     * We add an "api key" text box to the create/edit repository plugin Moodle form (also called a Repository type Moodle form)  

     *  

     * @param moodleform $mform Moodle form  

     */  

    public function type_config_form($mform) {  

        //the following line is needed in order to retrieve the API key value from the database when Moodle displays the edit form  

        $api_key = get_config('flickrpublic', 'api_key');  

  

        $mform->addElement(  

            'text',  

            'api_key',  

            get_string('apikey', 'repository_flickr_public'),  

            ['value' => $api_key, 'size' => '40']  

        );  

        $mform->addRule(  

            'api_key',  

            get_string('required'),  

            'required',  

            null,  

            'client'  

        );  

    }  

  

    // Method called when the repostiroy plugin is installed.  

  

    /**  

     * Plugin init method.  

     *  

     * this function is only called one time, when the Moodle administrator add the Flickr Public Plugin into the Moodle site.  

     */  

    public static function plugin_init() {  

        //here we create a default repository instance. The last parameter is 1 in order to set the instance as readonly.  

        repository::static_function(  

            'flickrpublic',  

            'create',  

            'flickrpublic',  

            0,  

            context_system::instance(),  

            ['name' => 'default instance', 'email_address' => null],  

            1  

        );  

    }  

}  

```

--------------------------------

### Example Plugin Language File

Source: https://moodledev.io/docs/5.2/apis/plugintypes/format

An example of a language file for a Moodle plugin, defining various language strings. This file should be placed in the plugin's lang/en directory.

```php
<?php

// This file is part of Moodle - http://moodle.org/  

//  

// 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/>.  

  

/**  

 * Languages configuration for the format_pluginname plugin.  

 *  

 * @package   format_pluginname  

 * @copyright Year, You Name <your@email.address>  

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later  

 */  

  

$string['addsections'] = 'Add section';  
$string['currentsection'] = 'This section';  
$string['deletesection'] = 'Delete section';  
$string['editsection'] = 'Edit section';  
$string['editsectionname'] = 'Edit section name';  
$string['hidefromothers'] = 'Hide section';  
$string['newsectionname'] = 'New name for section {$a}';  
$string['pluginname'] = 'pluginname format';  
$string['privacy:metadata'] = 'The Sample format plugin does not store any personal data.';  
$string['sectionname'] = 'Section';  
$string['showfromothers'] = 'Show section';  

```

--------------------------------

### Availability Condition Plugin File Structure Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/availability

This example shows the typical file and directory layout for an availability condition plugin, specifically the 'grouping' condition.

```plaintext
 availability/condition/grouping  

├── classes  
│   ├── condition.php  
│   ├── frontend.php  
├── lang  
│   └── en  
│       └── availability_grouping.php  
├── version.php  
└── yui  
    ├── build  
    │   └── moodle-availability_grouping-form  
    │       ├── moodle-availability_grouping-form-debug.js  
    │       ├── moodle-availability_grouping-form-min.js  
    │       └── moodle-availability_grouping-form.js  
    └── src  
        └── form  
            ├── build.json  
            ├── js  
            │   └── form.js  
            └── meta  
                └── form.json  

```

--------------------------------

### Atto Plugin Directory Layout Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/atto

Illustrates the typical file and directory structure for an Atto plugin, such as atto_media.

```text
 lib/editor/atto/plugins/media  

 |-- db  
 |   └-- upgrade.php  

 |-- lang  
 |   └-- en  
 |       └-- atto_media.php  

 |-- yui  
 |   └-- src  
 |        └-- button  
 |           └-- atto_media.php  
 |           ├── build.json  
 |           ├── js  
 |           │   └── button.js  
 |           └── meta  
 |               └── button.json  

 |-- settings.php  
 
 └-- version.php  

```

--------------------------------

### Example Usage of Supports Function

Source: https://moodledev.io/docs/5.2/apis/plugintypes/fileconverter

Example of how to check if a file converter supports a specific conversion from jpg to pdf.

```php
if (\fileconverter_example::supports('jpg', 'pdf')) {  

    // ...  

}  

```

--------------------------------

### Enrolment Plugin Language File Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/enrol

This is a complete example of a language file for an enrolment plugin. It includes standard Moodle licensing, plugin metadata, and specific language strings for the 'Enrolment on payment' plugin.

```php
<?php  

// This file is part of Moodle - http://moodle.org/  

//  

// 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/>.  

  

/**  

 * Languages configuration for the enrol_pluginname plugin.  

 *  

 * @package   enrol_pluginname  

 * @copyright Year, You Name <your@email.address>  

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later  

 */  

  

$string['fee:config'] = 'Configure enrolment on payment enrol instances';  

$string['fee:manage'] = 'Manage enrolled users';  

$string['fee:unenrol'] = 'Unenrol users from course';  

$string['fee:unenrolself'] = 'Unenrol self from course';  

$string['pluginname'] = 'Enrolment on payment';  

$string['pluginname_desc'] = 'The enrolment on payment enrolment method allows you to set up courses requiring a payment. If the fee for any course is set to zero, then students are not asked to pay for entry. There is a site-wide fee that you set here as a default for the whole site and then a course setting that you can set for each course individually. The course fee overrides the site fee.';  

$string['privacy:metadata'] = 'The enrolment on payment enrolment plugin does not store any personal data.';  

```

--------------------------------

### Filesize Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for two-value filesize filters. Use constants like SIZE_UNIT_KILOBYTE for units and specify the size in 'value1'.

```php
'my:filesize_operator' => filesize::LESS_THAN,

'my:filesize_value1' => 50,

'my:filesize_unit' => filesize::SIZE_UNIT_KILOBYTE,

'my:filesize2_operator' => filesize::GREATER_THAN,

'my:filesize2_value1' => 1,

'my:filesize2_unit' => filesize::SIZE_UNIT_GIGABYTE,
```

--------------------------------

### Course Select Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for course selection filters. The 'values' key requires an array of database IDs for courses.

```php
'my:course_values' => [1, 4, 6],

'my:course2_values' => [42],
```

--------------------------------

### Simple API Route Example

Source: https://moodledev.io/docs/5.2/apis/subsystems/routing

This example demonstrates how to define a simple API route using the \core\router\route attribute. The route is associated with the 'api' route group, which provides a base URI prefix of '/api/rest/v2'. The fully qualified path for this route will be '/api/rest/v2/mod_example/example'.

```APIDOC
## POST /api/rest/v2/mod_example/example

### Description
A simple example route that returns an empty payload.

### Method
POST

### Endpoint
/api/rest/v2/mod_example/example

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
```json
{
  "example": "No request body expected for this simple example."
}
```

### Response
#### Success Response (200)
- **payload** (array) - An empty array representing the response payload.

#### Response Example
```json
{
  "payload": []
}
```
```

--------------------------------

### Repository Plugin Language File Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/repository

An example of a language file for a repository plugin, defining various string identifiers and their English translations. This file should not contain any file inclusion statements.

```php
<?php  

// This file is part of Moodle - http://moodle.org/  

//  

// 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/>.  

  

/**  

 * Languages configuration for the repository_pluginname plugin.  

 *  

 * @package   repository_pluginname  

 * @copyright Year, You Name <your@email.address>  

 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later  

 */  

  

$string['pluginname']= 'Example repository';  

$string['configplugin'] = 'Configuration for Example repository';  

$string['pluginname_help'] = 'A repository description';  



```

--------------------------------

### Example: Delete a Preference

Source: https://moodledev.io/docs/5.2/apis/core/preference

Demonstrates how to remove a user preference using `unset_user_preference()`.

```php
unset_user_preference('foo_showavatars');

// returns [
//     foo_nameformat  => "short",
//     foo_displaynum  => "yes",
// ];
get_user_preferences();

```

--------------------------------

### ML Backend Python Directory Layout

Source: https://moodledev.io/docs/5.2/apis/plugintypes/mlbackend

Example directory structure for an ML backend plugin, specifically the Python backend.

```text
lib/mlbackend/python  

├── classes  
│   ├── privacy  
│   │   └── provider.php  
│   └── processor.php  
├── lang  
│   └── en  
│       └── mlbackend_python.php  
├── phpunit.xml  
├── settings.php  
├── tests  
│   └── processor_test.php  
├── upgrade.txt  
└── version.php  


```

--------------------------------

### Setup and Render Admin Page

Source: https://moodledev.io/docs/5.2/apis/subsystems/output

This snippet demonstrates the complete process of setting up an admin page, including page properties, renderer instantiation, and rendering a custom renderable. It's used for building custom admin tools.

```php
<?php  

// Standard GPL and phpdocs  

require_once(__DIR__ . '/../../../config.php');  
require_once($CFG->libdir.'/adminlib.php');  

admin_externalpage_setup('tooldemo');  

// Set up the page.  
$title = get_string('pluginname', 'tool_demo');  
$pagetitle = $title;  
$url = new moodle_url("/admin/tool/demo/index.php");  
$PAGE->set_url($url);  
$PAGE->set_title($title);  
$PAGE->set_heading($title);  

$output = $PAGE->get_renderer('tool_demo');  

echo $output->header();  
echo $output->heading($pagetitle);  

$renderable = new \tool_demo\output\index_page('Some text');  
echo $output->render($renderable);  

echo $output->footer();  

```

--------------------------------

### Get Plugin String Example

Source: https://moodledev.io/docs/5.2/apis/commonfiles

Use the get_string API to retrieve a translated string identifier. Ensure the correct plugin type and name are used for the second argument.

```php
get_string('pluginname', '[plugintype]_[pluginname]');  
```

--------------------------------

### Example Delegated Transaction

Source: https://moodledev.io/docs/5.2/apis/core/dml

Demonstrates the typical usage of delegated transactions, including starting, committing, and rolling back in case of exceptions. Ensures data consistency for multiple operations.

```php
global $DB;
try {
     $transaction = $DB->start_delegated_transaction();
     $DB->insert_record('foo', $object);
     $DB->insert_record('bar', $otherobject);
  
     // Assuming the both inserts work, we get to the following line.
     $transaction->allow_commit();
  
} catch (Exception $e) {
     $transaction->rollback($e);
}

```

--------------------------------

### Example: Get Course Custom Field Metadata

Source: https://moodledev.io/docs/5.2/apis/core/customfields

This function retrieves all custom fields for a given course ID and formats them into a metadata array. It skips fields with empty values.

```php
function get_course_metadata($courseid) {
    $handler = \core_customfield\handler::get_handler('core_course', 'course');

    // This is equivalent to the line above.
    //$handler = \core_course\customfield\course_handler::create();

    $datas = $handler->get_instance_data($courseid);
    $metadata = [];

    foreach ($datas as $data) {
        if (empty($data->get_value())) {
            continue;
        }

        $cat = $data->get_field()->get_category()->get('name');
        $metadata[$data->get_field()->get('shortname')] = $cat . ': ' . $data->get_value();
    }

    return $metadata;
}
```

--------------------------------

### Default Date Range Filter Values

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for the DATE_RANGE filter. Use these to set default start and end timestamps for date range filters.

```php
'my:date_operator' => date::DATE_RANGE,

'my:date_from' => 1732593669,

'my:date_to' => 1732893669,
```

--------------------------------

### Declare Peer Dependencies

Source: https://moodledev.io/docs/5.2/apis/commonfiles/version.php

An optional array listing related plugins that this plugin depends on. Moodle core verifies these dependencies and prevents installation or upgrade if any are not met. For example, depending on specific versions of 'mod_forum' and 'block_foo'.

```php
$plugin->dependencies = [
    // Depend upon version 2022041900 of mod_forum.  
    'mod_forum' => 2022041900,  
  
    // Depend upon version 2022041900 of block_foo.  
    'block_foo' => 2022041900,  
]
```

--------------------------------

### Complete Menu and Toolbar Configuration

Source: https://moodledev.io/docs/5.2/apis/plugintypes/tiny

A comprehensive example demonstrating how to configure both the toolbar and the menubar. It uses helper functions to add specific buttons and menu items, merging them with the existing editor configuration.

```javascript
  

import {

    startdemoButtonName,

    startdemoMenuItemName,

} from './common';  

  

import {

    addMenubarItem,

    addToolbarButtons,

} from 'editor_tiny/utils';  

  

const getToolbarConfiguration = (instanceConfig) => {  

    let toolbar = instanceConfig.toolbar;  

    toolbar = addToolbarButtons(toolbar, 'content', [  

        startdemoButtonName,  

    ]);  

  

    return toolbar;  

};  

  

const getMenuConfiguration = (instanceConfig) => {  

    let menu = instanceConfig.menu;  

    menu = addMenubarItem(menu, 'file', [  

        startdemoMenuItemName,  

    ].join(' '));  

  

    return menu;  

};  

  

export const configure = (instanceConfig) => {  

    return {

        toolbar: getToolbarConfiguration(instanceConfig),

        menu: getMenuConfiguration(instanceConfig),

    };

};  

  
```

--------------------------------

### get_output_classname()

Source: https://moodledev.io/docs/5.2/apis/plugintypes/format

This method gets a relative output class path (for example, "content\section") and returns the correct output class namespace depending on if the format has overridden outputs or not. See overriding output classes section for more information.

```APIDOC
## get_output_classname()

### Description
Gets a relative output class path and returns the correct output class namespace, considering if the format has overridden outputs.

### Method
(Not specified, likely a class method)

### Parameters
None explicitly documented.

### Request Example
(Not applicable for this method)

### Response
- **string**: The correct output class namespace.
```

--------------------------------

### Start and Allow Commit of Delegated Transaction

Source: https://moodledev.io/docs/5.2/apis/core/dml/delegated-transactions

Use this pattern to start a delegated transaction and mark it to allow committing its changes. Perform your database operations between starting the transaction and allowing the commit.

```php
$transaction = $DB->start_delegated_transaction();  

// Perform some $DB stuff  

$transaction->allow_commit();  
```

--------------------------------

### Example of Hard-coded Default

Source: https://moodledev.io/docs/5.2/apis/plugintypes/qtype/newquestiondefaults

This is an example of a hard-coded default value in a form class before implementing the user preference feature.

```php
$mform->setDefault('shuffleanswers', 1);
```

--------------------------------

### Initialize and Get Full Course Module Information

Source: https://moodledev.io/docs/5.2/apis/core/conditionalactivities

Instantiates a condition_info object and retrieves all necessary course module information to determine availability conditions.

```php
$cm->id = $id;
$test = new condition_info($cm, CONDITION_MISSING_EVERYTHING);
$fullcm = $test->get_full_course_module();
```

--------------------------------

### Typical Placement Plugin Directory Structure

Source: https://moodledev.io/docs/5.2/apis/plugintypes/ai/placement

Illustrates the standard directory layout for a Placement plugin, including classes, database access, language files, and tests.

```text
. 
├── classes
│   ├── external
│   │   ├── generate_image.php
│   │   └── generate_text.php
│   ├── placement.php
│   ├── privacy
│   │   └── provider.php
│   └── utils.php
├── db
│   ├── access.php
│   └── services.php
├── lang
│   └── en
│   │   └── aiplacement_editor.php
├── tests
│   └── utils_test.php
└── version.php  

```

--------------------------------

### Duration Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for two-value duration filters. Use constants like DAYSECS for units.

```php
'my:duration_operator' => duration::DURATION_MAXIMUM,

'my:duration_value' => 10,

'my:duration_unit' => 1,

'my:duration2_operator' => duration::DURATION_MINIMUM,

'my:duration_value' => 42,

'my:duration_unit' => DAYSECS,
```

--------------------------------

### Starting and Committing a Delegated Transaction

Source: https://moodledev.io/docs/5.2/apis/core/dml/delegated-transactions

This snippet demonstrates the basic usage of starting a delegated transaction, performing database operations, and allowing the transaction to commit.

```APIDOC
## Starting and Committing a Delegated Transaction

### Description
This shows the basic usage of starting a delegated transaction, performing some database operations, and then allowing the transaction to commit.

### Method
```php
$transaction = $DB->start_delegated_transaction();

// Perform some $DB stuff

$transaction->allow_commit();
```

### Endpoint
N/A (This is an SDK/API usage example)
```

--------------------------------

### Document Third-Party Library Import Instructions

Source: https://moodledev.io/docs/5.2/apis/commonfiles

Create a readme_moodle.txt file to detail information about imported third-party libraries, such as download URLs and build instructions.

```text
readme_moodle.txt
```

--------------------------------

### Migrate Legacy Callback and Dispatch New Hook

Source: https://moodledev.io/docs/5.2/apis/core/hooks

Modify `lib/setup.php` to include legacy callback handling and dispatch the new hook. This ensures compatibility and allows for a smooth transition to the new hook system.

```php
  
// Allow plugins to callback as soon possible after setup.php is loaded.  
$pluginswithfunction = get_plugins_with_function('after_config', 'lib.php', true, true);  
foreach ($pluginswithfunction as $plugins) {  
    foreach ($plugins as $function) {  
        try {  
            $function();  
        } catch (Throwable $e) {  
            debugging("Exception calling '$function'", DEBUG_DEVELOPER, $e->getTrace());  
        }  
    }  
}
// Dispatch the new Hook implementation immediately after the legacy callback.  
\core\di::get(\core\hook\manager::class())->dispatch(new \core\hook\after_config());  

```

--------------------------------

### Cohort Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for cohort filters. The 'values' key requires an array of database IDs for cohorts.

```php
'my:cohort_values' => [1, 4, 6],

'my:cohort2_values' => [42],
```

--------------------------------

### Check ML Backend Readiness (PHP)

Source: https://moodledev.io/docs/5.2/apis/plugintypes/mlbackend

Implement the `is_ready` method to check if the machine learning backend is available for predictions. This is a basic interface method.

```php
/**  
 * Is it ready to predict?  
 *  
 * @return bool  
 */  
public function is_ready();  

```

--------------------------------

### User Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for single-value user filters. The 'value' key requires an array of user database IDs.

```php
'my:user_operator' => user::USER_SELECT,

'my:user_value' => [142, 4753],

'my:user2_operator' => user::USER_SELECT,

'my:user2_value' => [1],
```

--------------------------------

### Tags Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for single-value tag filters. The 'value' key should contain an array of tag database IDs.

```php
'my:tags_operator' => tags::EQUAL_TO,

'my:tags_value' => [142, 4753],

'my:tags2_operator' => tags::NOT_EQUAL_TO,

'my:tags2_value' => [1],
```

--------------------------------

### Define Course Overview Class with Dependency Injection

Source: https://moodledev.io/docs/5.2/apis/plugintypes/mod/courseoverview

Implement the `overview` class by extending `activityoverviewbase`. The constructor must accept `cm_info` and can include other dependencies like the database and clock interfaces, accessed via `$this->db` and `$this->clock` respectively.

```php
namespace mod_PLUGINNAME\courseformat;  
  
use core_course\activityoverviewbase;  
  
class overview extends activityoverviewbase {  

    public function __construct(  
        /** @var cm_info $cm the activity course module. */  
        cm_info $cm,  
        /** @var \moodle_database $db the database acces. */  
        protected readonly \moodle_database $db,  
        /** @var \core\clock $clock the clock interface */  
        protected readonly \core\clock $clock  
    ) {
        parent::__construct($cm);
    }

    // The rest of your code goes here. All methods must access the  
    // $this->db property to interact with the database instead of  
    // using the global $DB.  

    // Also, to handle timestamps, use $this->clock->time() instead.  
}

```

--------------------------------

### Autocomplete Filter Examples

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder/filtering

Examples of array key and value pairs for autocomplete filters. The 'values' key should contain an array of keys returned by the autocompletion element.

```php
'my:autocomplete_values' => [1, 4, 6],

'my:autocomplete2_values' => [42],
```

--------------------------------

### Setting up Message Pop-up Link

Source: https://moodledev.io/docs/5.2/apis/core/message

Example code demonstrating how to set up a JavaScript pop-up link for sending messages using `message_messenger_requirejs()` and `message_messenger_sendmessage_link_params()`.

```APIDOC
## Setting up the Message Pop-up Link

### Description
This section provides an example of how to create a link that, when clicked, initiates a message pop-up window for a specific user. It utilizes Moodle's messaging library and JavaScript requirements.

### Method
`message_messenger_requirejs()` and `message_messenger_sendmessage_link_params(userto_object)`

### Parameters
#### `message_messenger_requirejs()`
This function ensures that the necessary JavaScript libraries for the messenger are loaded.

#### `message_messenger_sendmessage_link_params(userto_object)`
- **userto_object** (object) - Required - The user object for whom the message pop-up is being set up.

### Request Example
```php
require_once('message/lib.php');
$userid = 2;
$userto = $DB->get_record('user', ['id' => $userid]);

message_messenger_requirejs();
$url = new moodle_url('message/index.php', ['id' => $userto->id]);
$attributes = message_messenger_sendmessage_link_params($userto);
echo html_writer::link($url, 'Send a message', $attributes);
```

### Response
This code generates an HTML link that triggers the message pop-up when clicked.
```

--------------------------------

### Get Analysable Elements Iterator

Source: https://moodledev.io/docs/5.2/apis/subsystems/analytics

Use get_analysables_iterator() for performance reasons to get a list of all analysable elements on the site. Models can then filter these based on their specific needs.

```php
/**  
 * Returns the list of analysable elements available on the site.  
 *  
 * A relatively complex SQL query should be set so that we take into account which analysable elements  
 * have already been processed and the order in which they have been processed. Helper methods are available  
 * to ease to implementation of get_analysables_iterator: get_iterator_sql and order_sql.  
 *  
 * @param string|null $action 'prediction', 'training' or null if no specific action needed.  
 * @return \Iterator  
 */  
public function get_analysables_iterator(?string $action = null)
```

--------------------------------

### Initialize Report Builder

Source: https://moodledev.io/docs/5.2/apis/core/reportbuilder

Implement the `initialise()` method to set up the main table, load entities, and define columns and filters for a system report.

```php
/**  
* Initialise report, we need to set the main table, load our entities and set columns/filters  
*/  
protected function initialise(): void {  
```

--------------------------------

### Repository Plugin File Structure Example

Source: https://moodledev.io/docs/5.2/apis/plugintypes/repository

Illustrates the typical directory layout for a Moodle repository plugin. Mandatory files like `version.php` and `lib.php` are included.

```plaintext
 repository/pluginname/  

 |-- db  
 |   `-- access.php  
 |-- lang  
 |   `-- en  
 |       `-- repository_pluginname.php  
 |-- lib.php  
 |-- pix  
 |   `-- icon.png  
 `-- version.php  

```

--------------------------------

### Valid Hook Names Examples

Source: https://moodledev.io/docs/5.2/apis/core/hooks

Examples of valid hook names following Moodle's naming conventions, including prefixes for before/after modifiers and subsystem-specific locations.

```php
\core_course\hook\before_course_visibility_changed
```

```php
\core_form\hook\before_form_validation
```

```php
\core_form\hook\after_form_validation
```

```php
\core\hook\navigation\before_render
```

--------------------------------

### Configure Editor Options

Source: https://moodledev.io/docs/5.2/apis/subsystems/form/usage/files

Set up options for the text editor, including file handling and context.

```php
$textfieldoptions = [
  
    'trusttext' => true,  

    'subdirs' => true,  

    'maxfiles' => $maxfiles,  

    'maxbytes' => $maxbytes,  

    'context' => $context,  

];  

```

--------------------------------

### Example Usage of repeat_elements()

Source: https://moodledev.io/docs/5.2/apis/subsystems/form/advanced/repeat-elements

This example demonstrates how to define elements to be repeated, configure options for them, and then use the repeat_elements function to add them to the form, including a delete button for each repeated item.

```APIDOC
$repeatarray = [
    $mform->createElement('text', 'option', get_string('optionno', 'choice')),
    $mform->createElement('text', 'limit', get_string('limitno', 'choice')),
    $mform->createElement('hidden', 'optionid', 0),
    $mform->createElement('submit', 'delete', get_string('deletestr', 'choice'), [], false),
];

if ($this->_instance){
    $repeatno = $DB->count_records('choice_options', ['choiceid' => $this->_instance]);
    $repeatno += 2;
} else {
    $repeatno = 5;
}

$repeateloptions = [
    'limit' => [
        'default' => 0,
        'disabledif' => array('limitanswers', 'eq', 0),
        'rule' => 'numeric',
        'type' => PARAM_INT,
    ],
    'option' => [
        'helpbutton' => [
            'choiceoptions',
            'choce',
        ]
    ]
];

$mform->setType('option', PARAM_CLEANHTML);
$mform->setType('optionid', PARAM_INT);

$this->repeat_elements(
    $repeatarray,
    $repeatno,
    $repeateloptions,
    'option_repeats',
    'option_add_fields',
    3,
    null,
    true,
    'delete'
);
```
Tokens:
Raw