### Example upgrade.txt Entry Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1050935729 This example shows how to document new and modified methods in the upgrade.txt file. ```text === 20.0.0 === * Added a new method `\namespace\of\class::add()` - This method takes two parameters and adds them together. * Modified internal implementation of method `\namespace\of\class::add_twice()` to utilise the new `::add()` method. ``` -------------------------------- ### Install and start Maildev Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185852/Testing%2Bemail Commands to install the Maildev utility via npm and start the service. ```bash npm install -g maildev ``` ```bash maildev ``` -------------------------------- ### Install Node and Watchman Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121186992/Environment%2Bset-up Use Homebrew to install Node.js and Watchman on macOS. ```bash brew install node brew install watchman ``` -------------------------------- ### Example upgrade.txt file content Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187267/Deprecation%2Bguidelines This is an example of the upgrade.txt file format, used to record API changes and deprecations for developers. ```text This file describes API changes in Totara Connect Server, information provided here is intended for developers. === 19.1 === * create_something() the first argument is no longer used. Functionality has not changed. * some_class::some_method() has been deprecated, please call some_class::some_other_method() instead. === 19.0 === * create_function() added second argument $bar * some_class has been renamed to \totara\core\some_class, please update all uses. ``` -------------------------------- ### Install Node dependencies Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184498 Use this command to perform a clean installation of node_modules based on the package.json file. ```bash npm ci ``` -------------------------------- ### Install and Compile SCSS Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184812/Overwriting%2BCSS Commands to install dependencies and compile SCSS files within the server directory. ```bash npm ci ``` ```bash npm install ``` ```bash npx grunt css ``` -------------------------------- ### SCSS Frankenstyle Import Example Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121188217 Provides an example of using the system's component-based frankenstyle import path for SCSS files. ```scss @import 'theme_customtheme/oldstyles/totara/nav'; ``` -------------------------------- ### Install Composer Dependencies Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185178/Unit%2Btesting Execute this command within the Totara Learn source directory to install required dependencies. ```bash php composer.phar install ``` -------------------------------- ### Install Recommender Dependencies Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187677/Recommender%2Binstallation%2Band%2Bconfiguration Installs Python dependencies listed in requirements.txt using pip3. Ensure the system user running the script has access to these dependencies. ```bash sudo pip3 install -r extensions/ml_recommender/python/requirements.txt ``` -------------------------------- ### Plugin Version File Example Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121188024/Versioning Example of a plugin's version.php file, specifying its version, minimum required system version, component name, and dependencies. The version number format is YYYYMMDDXX, where XX is incremented for upgrades. ```php $plugin->version = 2022042609; // The current module version (Date: YYYYMMDDXX). $plugin->requires = 2022042600; // Requires this Totara version. $plugin->component = 'mod_facetoface'; ``` -------------------------------- ### Initialise site for testing Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1766129686/Unit%2Btesting%2Bin%2BTotara%2B20 Prepare the test environment, including downloading dependencies and setting up the database. ```bash cd test/phpunit php phpunit.php init ``` ```bash php phpunit.php parallel_init --processes=4 ``` ```bash installunit ``` ```bash installunit --processes=[Number of processes] ``` -------------------------------- ### Totara Cohort Test Case Class Naming Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185180/Unit%2Btesting%2Bin%2BTotara%2B13 Example of a test case class name adhering to the specified naming convention. It starts with the 'totara_cohort' prefix and ends with '_testcase'. ```php class totara_cohort_enrol_testcase extends advanced_testcase { public function test_role_updates() { // test goes here } } ``` -------------------------------- ### Setup Controller Context Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184478/Model-view-controller%2BMVC%2Bpattern Implement `setup_context()` to define the page's context, which is crucial for `require_login()` and access control. Ensure the correct context (e.g., course, module) is returned. ```php class my_controller extends \totara_mvc\controller { protected function setup_context(): context { $course_id = $this->get_required_param('course_id', PARAM_INT); return \context_course::instance($course_id); } public function action() { // Context is stored in context class property $context = $this->get_context(); // Once the context is set it should not be changed anymore // ... } } ``` -------------------------------- ### AJAX Script Template Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184802/Security Use this template as a starting point for new AJAX scripts. It includes necessary setup, parameter handling, context setting, authentication, capability checks, and JSON output. ```php define('AJAX_SCRIPT', true); // Update path to config if required. require_once(__DIR__ . '/../../config.php'); // Limit input params to INT and ACTION types. $id = required_param('id', PARAM_INT); $action = required_param('action', PARAM_ACTION); // If within a course, get $course and $cm, and use course or module context, otherwise get system context $context = context_system::instance(); $PAGE->set_context($context); $PAGE->set_url('/path/to/ajax/script.php'); // Include $course and $cm if relevant (see description of require_login() above) require_login(); require_sesskey(); // Implement access control checks. require_capability('somecapability', $context); $someclass->has_access($USER, $id); // Output headers echo $OUTPUT->header(); // Create results object $data = new stdClass(); $data->success = true; $data->result = $someclass->get_data(); // Output JSON encoded data echo json_encode($data); ``` -------------------------------- ### PHP Hello World Report Source Class Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184182/Hello%2BWorld%2BSource Define a simple report source by extending 'rb_base_source'. Ensure the class name matches the filename and starts with 'rb_source_'. This example defines a single column 'Course Fullname' from the '{course}' base table. ```php base = '{course}'; $this->joinlist = array(); $this->columnoptions = array( new rb_column_option( 'course', 'fullname', 'Course Fullname', 'base.fullname' ) ); $this->filteroptions = array(); $this->sourcetitle = "Example1"; parent::__construct(); } } ?> ``` -------------------------------- ### Execute an external command Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184073/Command%2Bexecution%2BAPI Demonstrates initializing an executable, adding arguments and switches, executing the command, and retrieving the output. ```php $exe = new \core\command\executable('/path/to/exe'); $exe->add_argument('key1', 123, PARAM_INT); $exe->add_switch('switch1'); $exe->execute(); if ($exe->get_return_status() === 0) { $output = $exe->get_output(); } ``` -------------------------------- ### Install Local Dependencies Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184824/Working%2BWith%2BLESS%2Bin%2BThemes Install local Node.js dependencies required for theme development within your Totara installation directory. Ensure you have Node and NPM installed first. ```bash npm install ``` -------------------------------- ### Initialize PHPUnit Environment Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185178/Unit%2Btesting Run this command to set up database structures and the data root directory required for testing. ```bash php server/admin/tool/phpunit/cli/init.php ``` -------------------------------- ### Configure PHPUnit environment Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185180/Unit%2Btesting%2Bin%2BTotara%2B13 Commands to prepare the test configuration file from the provided example. ```bash cd test/phpunit cp config.example.php config.php vi config.php ``` -------------------------------- ### Install pcov/clobber for PHPUnit 7 Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/572621076/Code%2Bcoverage Install the pcov/clobber package using Composer to add pcov support to PHPUnit 7. This command also installs the pcov binary and clobber. ```bash composer require pcov/clobber vendor/bin/pcov clobber ``` -------------------------------- ### Initiate Catalog Instance Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1088585794/Suggestions Initiates a new catalog instance for the current user's language preference. Ensure the catalog is ready before suggesting sentences. ```php static::for_language($language, $spelling) ``` -------------------------------- ### Sample upgrade.txt Header Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1050935729 This is a sample header for the upgrade.txt file, indicating API changes in core libraries and APIs. ```text This files describes API changes in core libraries and APIs, information provided here is intended especially for developers. === 19.1.0 === * hello::world() is now deprecated... ``` -------------------------------- ### Check Installed Aspell Dictionaries Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1088585794/Suggestions Command to list languages currently installed in the Aspell library. ```bash aspell dump dicts ``` -------------------------------- ### Initialize Tui theme components Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187198/Creating%2Bcustom%2Bthemes Run this command to generate the necessary client-side component files for the theme. ```bash npm run tui-init theme_mytheme vendor ``` -------------------------------- ### Example upgrade.txt file format Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187267 The upgrade.txt file should be placed in the plugin's root folder to document API changes and deprecations. ```text This file describes API changes in Totara Connect Server, information provided here is intended for developers. === 19.1 ===   * create_something() the first argument is no longer used. Functionality has not changed. * some_class::some_method() has been deprecated, please call some_class::some_other_method() instead.   === 19.0 === * create_function() added second argument $bar * some_class has been renamed to \totara\core\some_class, please update all uses.   ``` -------------------------------- ### Initialize flex_icons.php file Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184766 Commands to create the necessary directory and file structure for icon overrides within a theme. ```bash $ cd /path/to/totara/dirroot $ cd theme/kakapo $ mkdir pix $ touch pix/flex_icons.php ``` -------------------------------- ### API Error Response Examples Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187522/Enabling%2Bdebugging%2Bin%2BGraphQL%2BAPIs Examples of JSON error responses based on different debugging levels. ```json { "errors": [ { "debugMessage": "This is the specific error message", "message": "Internal server error", "extensions": { "category": "internal" },     "locations": [ { "line": 4, "column": 7 } ], "path": [ "core_user_users", "items", 0, "id" ] } ] } ``` ```json { "errors": [ { "message": "Internal server error", "extensions": { "category": "internal" },     "locations": [ { "line": 4, "column": 7 } ], "path": [ "core_user_users", "items", 0, "id" ] } ] } ``` ```json { "errors": [ { "debugMessage": "This is the specific error message", "message": "Internal server error", "extensions": { "category": "internal" },     "locations": [ { "line": 4, "column": 7 } ], "path": [ "core_user_users", "items", 0, "id" ], "trace": [ { "file": "/var/www/totara/src/main/server/totara/webapi/classes/default_resolver.php", "line": 91, "call": "core\\webapi\\resolver\\type\\user::resolve('id', instance of core\\entity\\user, array(1), instance of core\\webapi\\execution_context)" }, { "file": "/var/www/totara/src/main/server/totara/oauth2/classes/webapi/middleware/client_rate_limit.php", "line": 50, "call": "totara_webapi\\default_resolver::totara_webapi\\{closure}(instance of core\\webapi\\resolver\\payload)" }, { "file": "/var/www/totara/src/main/server/totara/webapi/classes/default_resolver.php", "line": 160, "call": "totara_oauth2\\webapi\\middleware\\client_rate_limit::handle(instance of core\\webapi\\resolver\\payload, instance of Closure)" }, ... ] } ] } ``` -------------------------------- ### Define search index table in INSTALL.xml Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184099/Full%2Btext%2Bsearch Example structure for a searchable table including fields, primary keys, and full text search indexes. ```xml
``` -------------------------------- ### Install pcov for PHP 8.3 Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/572621076/Code%2Bcoverage Installs the pcov extension on Ubuntu 24.04 to enable code coverage analysis. ```bash sudo apt install php8.3-pcov ``` -------------------------------- ### upgrade.txt Entry for Multiple Versions (main) Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1050935729 Example of an upgrade.txt entry for a change introduced in the main branch. ```text === 20.0.0 === * My new technical change ``` -------------------------------- ### Install spaCy language models Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185788/Recommendations%2Btext%2Bprocessing Command to install specific spaCy language models required for text processing. ```bash python -m spacy download [lang]_[type]_[genre]_[size] ``` -------------------------------- ### Initialize Totara Learn for Testing Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185178 Run this script to set up the necessary database structures, prepare the data root, and generally initialize your Totara Learn site for running PHPUnit tests. ```bash php server/admin/tool/phpunit/cli/init.php ``` -------------------------------- ### Define constants and usage Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121186878/Plugin%2Bconfig%2Babstraction Example of defining configuration constants and performing basic read/write operations using the custom config class. ```php // server/type/myplugin/classes/config.php namespace type_myplugin; use core\base_plugin_config; class config extends base_plugin_config { public const MAX_RESULTS = 50; private const DEFAULT_CLIENT_ID = 'some_value'; protected static function get_component(): string { return 'type_myplugin'; } public static function get_client_id() { return static::get('client_id', static::DEFAULT_CLIENT_ID); } public static function set_client_id(string $value) { static::set('client_id', $value); } } // Example usage: config::set_client_id('new_value'); $client_id = config::get_client_id(); $max = config::MAX_RESULTS; ``` -------------------------------- ### Install PSpell via PECL Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1088585794/Suggestions Command to install the PSpell PHP extension required for default spelling suggestions. ```bash pecl install pspell ``` -------------------------------- ### Upgrade.txt Entry for Multiple Versions Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1050935729/Guide%2Bto%2Bupgrade.txt Demonstrates how to document a single ticket's changes across multiple release versions in the upgrade.txt file, specifying the introduction version for each branch. ```text === 19.1.0 === * My new technical change ``` ```text === 19.0.1 === * My new technical change ``` ```text === 20.0.0 === * My new technical change ``` -------------------------------- ### Install pytest Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1188495424/Testing%2BMachine%2BLearning%2BService Install the pytest test runner using pip. This is required to run the tests for the ML service. ```bash pip install pytest ``` -------------------------------- ### Example JSON Data Structure Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184802/Security An example of a JSON data structure that could be rendered to HTML via a template. ```json { "searchterm": "animals", "results": [ {"url": "/cats", "name": "Cats"}, {"url": "/dogs", "name": "Dogs"}, {"url": "/fish", "name": "Fish"} } } ``` -------------------------------- ### Enable Performance Data in config.php Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187522 Add this line to your config.php file above setuplib.php to enable performance data collection. Ensure MDL_PERF is set to true and CFG->perfdebug is set to a value greater than 7. ```php define('MDL_PERF', true); $CFG->perfdebug = 15; // Any number greater than 7 will trigger the inclusion of performance data ``` -------------------------------- ### Basic Entry Format Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1050935729 Entries in upgrade.txt should be bullet points using an asterisk and a space. ```text * Removed deprecated completion_info::wipe_session_cache() ``` -------------------------------- ### Install Python 3 on Debian Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187677/Recommender%2Binstallation%2Band%2Bconfiguration Installs Python 3.7, pip, wheel, venv, and dev packages on Debian-based systems. ```bash sudo apt update sudo apt install -y python3.7 sudo apt install -y python3-pip sudo apt install -y python3-wheel sudo apt install -y python3-venv sudo apt install -y python3-dev ``` -------------------------------- ### SQL to Get Tenants a Member Participates In Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121186086/Multitenancy Illustrates how to query for all tenants a specific user is a member of by joining tenant and cohort_members tables. ```SQL SELECT t.id FROM {tenant} t JOIN {cohort_members} cm ON cm.cohortid = t.cohortid WHERE cm.userid = :userid ``` -------------------------------- ### Import Legacy Recommendations via CLI Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1188495410 Command to import recommendations for the legacy recommender system. ```bash php server/ml/recommender/cli/import_recommendations.php ``` -------------------------------- ### Install Project Dependencies Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185059 Install all project dependencies using npm. This includes the React Native dependencies and any other packages required by the app. ```bash $ npm install ``` -------------------------------- ### Install Global Grunt CLI Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184824/Working%2BWith%2BLESS%2Bin%2BThemes Install the Grunt command-line interface globally if you haven't already. This is a prerequisite for running Grunt tasks. ```bash npm install -g grunt-cli ``` -------------------------------- ### Instantiating Collections Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184067 Shows various ways to create a new collection instance from existing data or empty states. ```php $records = $DB->get_records('users'); // Pass any array $users = new collection($records); // There's also a shortcut method in case you need a fluent way of creating it $user_ids = collection::new($records)->pluck('id'); // You can also start from an empty collection and add items later $users = new collection(); foreach ($records as $record) { $users->append($record); } ``` -------------------------------- ### upgrade.txt Entry for Multiple Versions (main-19) Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/1050935729 Example of an upgrade.txt entry for a change introduced in the main-19 branch. ```text === 19.1.0 === * My new technical change ``` -------------------------------- ### Initialize Course Icons JavaScript Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185243/Hooks%2Bdeveloper%2Bdocumentation Sets up the icon picker JavaScript module for course icon management. ```php protected static function initialise_course_icons_js(edit_form_display $hook) { global $PAGE; $course = $hook->customdata['course']; // Icon picker. $PAGE->requires->string_for_js('chooseicon', 'totara_program'); $iconjsmodule = array( 'name' => 'totara_iconpicker', 'fullpath' => '/totara/core/js/icon.picker.js', 'requires' => array ``` -------------------------------- ### Altair Example Response: Language Strings Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187303 This is an example response for the core_lang_strings query, showing the identifier, component, and string for the requested language. ```json { "data": { "core_lang_strings": [ { "identifier": "totaralearn", "component": "totara_core", "string": "Totara Learn" } ] } } ``` -------------------------------- ### Example JSON Response Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121184300/Advanced%2Bfilter%2Boptions This is an example of a JSON response, likely from an API call, containing server duration and a request correlation ID. ```json {"serverDuration": 12, "requestCorrelationId": "f26ba81428e64d098685bd2e09b37d58"} ``` -------------------------------- ### Run single-step build process Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187524/Extending%2BAPI%2Bdocumentation Combines the PHP and Node.js build steps into a single command when both environments are available. ```bash cd extensions/api_docs; npm ci; php ../../server/totara/api/cli/prep_api_docs.php -q | xargs node build ``` -------------------------------- ### Install pcov using PECL Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/572621076/Code%2Bcoverage Install the pcov extension using the PECL package manager. This is a high-performance alternative to XDebug for code coverage. ```bash pecl install pcov ``` -------------------------------- ### Install Python 3 on Red Hat Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121187677/Recommender%2Binstallation%2Band%2Bconfiguration Installs Python 3.7, pip, wheel, venv, and devel packages on Red Hat-based systems. ```bash sudo yum update sudo yum install -y python3.7 sudo yum install -y python3-pip sudo yum install -y python3-wheel sudo yum install -y python3-venv sudo yum install -y python3-devel ``` -------------------------------- ### Full Chart Configuration Example Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121181381/Advanced%2Bsettings A complete configuration object including title, legend, tooltips, and axis definitions. ```json { "title": { "text": "Graph Title", "position": "top", "font": "Times New Roman", "fontSize": 22, "fontStyle": "bold", "color": "#ea22a9", "padding": 10 }, "legend": { "display": "true", "position": "top", "font": "Times New Roman", "fontSize": 16, "fontStyle": "italic", "color": "#ee22a9", "padding": 5 }, "tooltips": { "display": true, "backgroundColor": "#eaeaea", "font": "Times New Roman" "fontSize": 16 "fontStyle": "bold", "color": "#1f1f1f", "borderRadius": 5, "borderColor": "#ee22a9, "borderWidth": 1, }, "axis": { "x": { "display": false, "title": { "text": "Horizontal Axis", "font": "Times New Roman", "fontSize": 16, "fontStyle": "italic", "color": "#ea22a9", "padding": 10, }, "grid": { "display": true, "color": "#eaeaea", } }, "y": { "display": false, "title": { "text": "Vertical Axis", "font": "Times New Roman", "fontSize": 16, "fontStyle": "italic", "color": "#ea22a9", "padding": 10, }, "grid": { "display": true, "color": "#eaeaea", } } } } ``` -------------------------------- ### Install Composer Dependencies Source: https://totara.atlassian.net/wiki/spaces/DEV/pages/121185178 Execute this command within the Totara Learn source directory to install PHPUnit and other necessary dependencies managed by Composer. ```bash php composer.phar install ```