MoodleDocs - User contributions [en]

Callbacks

2023-12-08T19:14:20Z

Emerrill: Adding missing callbacks

Moodle does not have well-defined Hooks API but still allows plugins to hook into different processes by '''implementing callbacks'''. See also [[Communication Between Components]].

Some old APIs that were created before object-oriented programming use only callbacks. One of them is [[Activity modules]].
==Types of callbacks in Moodle==
=== Callback functions one-to-many ===
Core has a "hook point" where it allows plugins to execute some code, modify variables or return a result. Sometimes (especially for old callbacks) only plugins of a specific plugin type are allowed, however this is not recommended for the new callbacks because the list of callbacks is now cached and performance is not a constraint any more. If plugins want to implement the function for this callback they normally must place it in '''lib.php''' with the name '''pluginfullname_callbackname()'''. Here pluginname should be a full plugin name with a prefix, however activity modules can often omit the "mod_" prefix for historical reasons. Implementing this type of callback is optional and the "hook point" does not care how many and which plugins implement callback. Also "hook point" does not check if the plugin is enabled on this site, inside the callback plugins must check it themselves if it is important. Methods '''get_plugin_list_with_function()''' and '''get_plugins_with_function()''' are normally used in the "hook points" to find all plugins implementing a callback.

This document aims to cover ALL callbacks of this type that are present in Moodle core APIs or in standard Moodle plugins.
=== Callback functions one-to-one ===
Core API (or plugins such as blocks or reports) looks for and executes a method from the plugin/component that "owns" some entity, usually for checking permissions, pre-processing or providing the human-readable representation of this entity. Similar to one-to-many callbacks, the component/plugin must define a function with the name '''pluginfullname_callbackname()''' in lib.php . In some cases the function ''must'' be present or otherwise an exception is thrown or debugging message is displayed. Methods '''component_callback()''' and '''component_callback_exists()''' are normally used to find an implementation of a callback. Unlike one-to-many callbacks the implementing functions can exist not only in plugins but also in core components.

The list of one-to-one callbacks may not be 100% complete in this document, the aim is to cover the "magic" functions that are actually used despite IDE hints.
=== Other ===
* '''Files in the specific location'''. Core APIs may look for plugins that have a file with a specific file name, for example '''version.php''', '''settings.php''', '''styles.css''', '''module.js''', files in '''db/''' folder, etc. See [[Plugin files]]
* '''Event observers'''. Each plugin can implement event observers that execute code when event is triggered. See [[Events API#Event_dispatching_and_observers|Events API]] about how to listen to events. Event observers can not always substitute callbacks because they do not return any value and can only happen in case of event. Many "hook points" are necessary before something has happened or when nothing is happening at all, for example a report/summary is gathered. However if it is possible to achieve the desired outcome with event observer, Moodle will not accept requests for adding a "hook point".
* Callbacks that are specified in the db/* file, for example in '''db/service.php''' developers must specify callback responsible for implementing web service, in '''db/tags.php''' developers specify callback for finding tagged items, etc. These types of callbacks are not covered on this page, information about them can be found in the respective APIs.
== Callbacks and external / webservices / consumers (mobile / apps) support ==
=== The problem ===
Our external functions are able to [[Web service API functions|perform a lot of actions]] against core. Those external functions use to implement their functionality reusing [[Core APIs]]. And, those APIs can contain hook points/callbacks to customize Moodle behavior.

Of course, ultimately, those external functions are used by the [[Web_services| web services layer]] providing all the functionality over REST/XMLRCP/SOAP "protocols". All those "clients" consuming Moodle Webservices (integrations in general, mobile & desktop apps...) should work ok, and we must guarantee that all the code executed in those underlying external functions (that may include hook points/callbacks) is supported by them.

In the other side, some of those callbacks may be focussed entirely in the web version of Moodle and have no application outside from there. Also, sometime, there are callbacks which goal is incompatible with uses from web service consumers, mainly because the consumers don't support this or that Moodle functionality used by the callback implementations.

Imagine a callback that provides to the consumer with something that it's not able to manage (say a mustache template, or a moodle form, or any other stuff in general that only core is able to provide). It's a pretty "possible" case a we need a way to handle it in an organised way.
=== The solution ===
To be able advance with those "problematic" hooks (not being supported by web-service consumers), it has been agreed to proceed with the following points in order to allow them to work via web, avoiding them to impact to consumers and registering the need of introducing (future) viable solutions to enable consumers to work with them.

All the following points must be considered as real requirements in order to allow a new callback (called from externals/web services) to land to core.
# '''Create a linked MOBILE issue''' requesting the callback to be supported in the app (for the record and future reference). Clearly explaining which are the externals / web services affected, what should be supported and, ideally, a way to provide that.
# '''Clearly indicate in the issue''' introducing the new callback if the hook is supported or not via WebServices. Callbacks documentation (below in this page) '''must include the comment''' ''"Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-xxxx and MOBILE-xxxx for more info."''" (where the MDL and MOBILE issues are the related ones).
# '''Add manual tests''' in the issue for checking that the related functionality in the mobile / desktop app is not broken and everything continues working ok.
# Check that the '''modified code or APIs do not impact on the external / WebServices''' API. You can just check if the modified function is used by the external API just adding a debug message and then running WebServices.
# If you need to add code in an API already used by the external API, you can always '''use the WS_SERVER constant''' to check if the current request comes from the WS layer to '''avoid its execution'''. With links to the corresponding MDL-xxxx and MOBILE-xxxx issues.
# In any case, '''it's the responsibility of every plugin implementing a not compatible callback to prevent any action''' that may affect / impact the WS layer. Core (hook points) will always perform the calls to the callbacks, unconditionally.
== List of Moodle callbacks ==
=== List of one-to-many callbacks ===
To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.
{| class="wikitable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Navigation, see [[Navigation API]]'''
|-
| extend_navigation_course
| *
|
| before Moodle 3.0 was only supported by ''report'' and ''tool'' plugin types
|-
| extend_settings_navigation
| local, booktool
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation
| local
|
| ''Note, modules have a one-to-one callback with the same name, see below''
|-
| extend_navigation_user_settings
| *
| 3.0+
| before Moodle 3.0 was only supported by ''tool'' plugin types
|-
| extend_navigation_category_settings
| *
| 3.0+
|
|-
| extend_navigation_frontpage
| *
| 3.1+
|
|-
| extend_navigation_user
| *
| 3.1+
|
|-
| colspan=4 align=center | '''My profile, see [[My profile API]]'''
|-
| myprofile_navigation
| *
| 2.9+
|
|-
| colspan=4 align=center | '''Before-actions hooks'''
|-
| course_module_background_deletion_recommended
| *
| 3.2+
| see [https://github.com/moodle/moodle/blob/MOODLE_32_STABLE/lib/upgrade.txt#L142 upgrade.txt]
|-
| pre_block_delete
| *
| 3.1+
|
|-
| pre_course_category_delete
| *
| 3.1+
|
|-
|pre_course_category_delete_move
|*
|3.9+
|
|-
| pre_course_delete
| *
| 3.1+
|
|-
| pre_course_module_delete
| *
| 3.1+
|
|-
| pre_user_delete
| *
| 3.1+
|
|-
| colspan=4 align=center | '''[[Login_callbacks]]'''
|-
| [[Login_callbacks#after_config | after_config]]
| *
| 3.8+
| Triggered as soon as practical on every moodle bootstrap after config has been loaded. The $USER object is available at this point too.
|-
| [[Login_callbacks#after_require_login | after_require_login]]
| *
| 3.7+
| eg Add permissions logic across a site or course
|-
| [[Login_callbacks#check_password_policy | check_password_policy]]
| *
| 3.6+
|
|-
| [[Login_callbacks#print_password_policy | print_password_policy]]
| *
| 3.8+ (WIP)
|
|-
| [[Login_callbacks#pre_signup_requests | pre_signup_requests]]
| *
| 3.5
| eg to do actions before sign up such as acceptance of policies, validations, etc
|-
| [[Login_callbacks#extend_change_password_form | extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_set_password_form | extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_forgot_password_form | extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#extend_signup_form | extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Injecting form elements into the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_change_password_form | validate_extend_change_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the change password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_set_password_form | validate_extend_set_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the set password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_forgot_password_form | validate_extend_forgot_password_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the forgot password form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#validate_extend_signup_form | validate_extend_signup_form]]
| *
| 3.8+ (WIP)
| eg Adding additional validation to the signup form. Note: This hook is not compatible with the Webservices API or the Moodle mobile app. See MDL-66173 and MOBILE-3181 for more info.
|-
| [[Login_callbacks#post_change_password_requests | post_change_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user changes password.
|-
| [[Login_callbacks#post_set_password_requests | post_set_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user resets password.
|-
| [[Login_callbacks#post_forgot_password_requests | post_forgot_password_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user submits a password reset request.
|-
| [[Login_callbacks#post_signup_requests | post_signup_requests]]
| *
| 3.8+ (WIP)
| eg Fire additional actions after a user creates an account.
|-
| colspan=4 align=center | '''Page rendering, see [[Output_callbacks]]'''
|-
| [[Output_callbacks#add_htmlattributes | add_htmlattributes]]
| *
| 3.3+
| eg Add open graph xml namespace attributes
|-
| [[Output_callbacks#before_footer | before_footer]]
| *
| 3.3+
| eg injecting JS across the site, like analytics
|-
| [[Output_callbacks#before_http_headers | before_http_headers]]
| *
| 3.3+
| Setting http headers across the site like CSP
|-
| [[Output_callbacks#before_standard_html_head | before_standard_html_head]]
| *
| 3.3+
| A better API alternative to appending to $CFG->additionalhtmlhead
|-
| [[Output_callbacks#before_standard_top_of_body_html | before_standard_top_of_body_html]]
| *
| 3.3+
|
|-
| [[Output_callbacks#render_navbar_output | render_navbar_output]]
| *
| 3.2+
|
|-
| colspan=4 align=center | '''Course module edit form'''
|-
| coursemodule_edit_post_actions
| *
| 3.1+
|
|-
| coursemodule_standard_elements
| *
| 3.1+
| Takes parameters $formwrapper and $mform, allows manipulation of editing form, e.g. additional fields. See https://github.com/marcusgreen/moodle-local_callbacks
|-
|coursemodule_definition_after_data
|*
|3.11+
|
|-
| coursemodule_validation
| *
| 3.1+
|
|-
| colspan=4 align=center | '''Modules'''
|-
| check_updates_since
| mod
| 3.2+
| See [[NEWMODULE_Documentation]]
|-
| dndupload_register
| mod
|
|
|-
| colspan=4 align=center | '''Admin'''
|-
| bulk_user_actions
| *
| 3.9+
| Any plugin typically an admin tool can add new bulk user actions
|-
| colspan=4 align=center | '''Other'''
|-
| get_fontawesome_icon_map
| *
| 3.3+
| https://docs.moodle.org/dev/Moodle_icons#Font_awesome_icons
|-
| get_question_bank_search_conditions
| local
|
|
|-
| oauth2_system_scopes
| *
| 3.3+
|
|-
| rss_get_feed
| *
|
|
|-
| supports_logstore
| report
|
|
|-
| get_shortcuts
| ltisource
| 3.1+
|
|-
| before_launch
| ltisource
| 2.8+
|
|-
| [[Miscellaneous_callbacks#control_view_profile | control_view_profile]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#store_profiling_data | store_profiling_data ]]
| *
| 3.6+
|
|-
| [[Miscellaneous_callbacks#override_webservice_execution | override_webservice_execution]]
| *
| 3.6+
|
|-
|can_course_category_delete
|*
|3.9+
|Indicate if an empty course category can be deleted
|-
|can_course_category_delete_move
|*
|3.9+
|Indicate if a course category with content in it can have it's content moved to a selected new category, so it can be deleted.
|-
|get_course_category_contents
|*
|3.9+
|Provides content information to be displayed on the course category delete/move content page
|-
| colspan=4 align=center | '''Deprecated'''
|-
| cron
| *
|
| See [[Task API]]
|-
| delete_course
| mod,report,coursereport,format
|
| Replace with observer to course_contents_deleted event
|-
| print_overview
| mod
| up to 3.2
| New dashboard uses [[Calendar API]] to populate events on the timeline
|-
| report_extend_navigation
| coursereport
|
| Plugin type ''coursereport'' is deprecated, plugin type ''report'' should be used instead
|}
'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions
=== List of one-to-one callbacks ===
To implement one of these callbacks plugins must add a function '''pluginfullname_callbackname()''' in '''lib.php''' unless stated otherwise. The ''pluginfullname'' is the name of the plugin with the frankenstyle prefix. For activity modules it is acceptable to omit the ''mod_'' prefix. Refer to the linked documentation or search Moodle code by the callback name to find where it is called, what arguments are supplied and what return value is expected.
{| class="wikitable"
|-
! Callback
! Plugin type
! Version
! Comments
|-
| colspan=4 align=center | '''Comments support''', see [[Comment API]]
|-
| comment_add
| *
|
|
|-
| comment_display
| *
|
|
|-
| comment_permissions
| *
|
|
|-
| comment_template
| *
|
|
|-
| comment_url
| *
|
|
|-
| comment_validate
| *
|
|
|-
| colspan=4 align=center | '''Gradebook'''
|-
| export_%_settings_definition
| gradeexport
|
| % is a plugin name ''without'' prefix
|-
| import_%_settings_definition
| gradeimport
|
| % is a plugin name ''without'' prefix
|-
| report_%_profilereport
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| report_%_settings_definition
| gradereport
|
| % is a plugin name ''without'' prefix
|-
| colspan=4 align=center | '''Groups support''', see [[Groups API]]
|-
| allow_group_member_remove
| *
|
|
|-
| restore_group_member
| *
|
| For plugins that create their own groups
|-
| colspan=4 align=center | '''Installation and upgrade'''
|-
| xmldb_%_install
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_install_recovery
| *
|
| Located in db/install.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_uninstall
| *
|
| Located in db/uninstall.php , % refer to the full plugin name, in case of modules without prefix
|-
| xmldb_%_upgrade
| *
|
| Located in db/upgrade.php , % refer to the full plugin name, in case of modules without prefix
|-
| colspan=4 align=center | '''LTI source'''
|-
| add_instance_hook
| ltisource
|
|
|-
| ''messagetype''
| ltisource
|
| Callback name is the type of the message
|-
| colspan=4 align=center | '''Question bank support''', see [[Question API]]
|-
| question_pluginfile
| *
|
|
|-
| question_preview_pluginfile
| *
|
|
|-
| questions_in_use
| *
| since 3.7.5, 3.8.2 (previously only "mod")
|
|-
| colspan=4 align=center | '''Ratings support''', see [[Rating API]]
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_can_see_item_ratings
| *
| 2.9.2+
|
|-
| rating_get_item_fields
| *
|
|
|-
| rating_permissions
| *
|
|
|-
| rating_validate
| *
|
|
|-
| colspan=4 align=center | '''Themes'''
|-
| $THEME->csspostprocess
| theme
|
|
|-
| $THEME->extralesscallback
| theme
|
|
|-
| $THEME->lessvariablescallback
| theme
|
|
|-
| page_init
| theme
|
|
|-
| colspan=4 align=center | '''Modules: Calendar and dashboard'''
|-
| core_calendar_event_action_shows_item_count
| mod
| 3.3+
|
|-
| core_calendar_is_event_visible
| mod
| 3.3+
|
|-
| core_calendar_provide_event_action
| mod
| 3.3+
|
|-
| colspan=4 align=center | '''Modules: Course cache'''
|-
| cm_info_dynamic
| mod
|
|
|-
| cm_info_view
| mod
|
|
|-
| get_coursemodule_info
| mod
|
|
|-
| colspan=4 align=center | '''Modules: Course reset'''
|-
| reset_course_form_defaults
| mod
|
|
|-
| reset_course_form_definition
| mod
|
|
|-
| reset_userdata
| mod
|
|
|-
| colspan=4 align=center | '''Modules'''
|-
| delete_instance
| mod
|
|
|-
| dndupload_handle
| mod
|
|
|-
| export_contents
| mod
|
| Used in WS get_course_contents
|-
| extend_settings_navigation
| mod,booktool
|
|
|-
| extends_navigation
| mod
|
|
|-
| get_completion_active_rule_descriptions
| mod
| 3.3+
| Must be present for modules implementing custom completion rules
|-
| get_completion_state
| mod
|
|
|-
| get_extra_capabilities
| mod
|
|
|-
| get_file_areas
| mod
|
|
|-
| get_recent_mod_activity
| mod
|
|
|-
| get_shortcuts
| mod
| 3.1+
|
|-
| grade_item_update
| mod
|
|
|-
| grading_areas_list
| mod
|
|
|-
| print_recent_activity
| mod
|
|
|-
| print_recent_mod_activity
| mod
|
|
|-
| refresh_events
| mod
|
|
|-
| rescale_activity_grades
| mod
| 3.1+
|
|-
| scale_used_anywhere
| mod
|
|
|-
| update_grades
| mod
|
|
|-
| user_complete
| mod
|
|
|-
| user_outline
| mod
|
|
|-
| colspan=4 align=center | '''Glossary formats'''
|-
| glossary_print_entry_%
| for glossary formats
|
| Glossary formats is not a plugin type yet, however the list of formats is not hardcoded in the mod_glossary, instead the methods similar to callbacks are used for each subfolder in mod/glossar/format. % refer to the subfolder name, the functions are expected in lib.php
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| glossary_show_entry_%
| for glossary formats
|
| - " -
|-
| colspan=4 align=center | '''Other'''
|-
| global_db_replace
| block
|
|
|-
| inplace_editable
| *
|
| See [[Inplace editable]]
|-
| output_fragment_*
| *
| 3.1+
| see [[Fragment]]
|-
| page_type_list
| *
|
| Used when displaying page types in block configuration
|-
| params_for_js
| atto
|
|
|-
| pluginfile
| *
|
| Callback checking permissions and preparing the file for serving plugin files, see [[File API]]. Note, in case of ''block'' plugins the list of arguments is slightly different
|-
| restore_role_assignment
| *
|
| For plugins that create their own role assignments
|-
| strings_for_js
| atto
|
|
|-
| supports
| *
|
| Required for activity modules
|-
|h5p\canedit::can_edit_content
|*
|4.0+
|Plugins can implement this class&method to define, if required, any custom behaviour for deciding whether an H5P content used inside the plugin can be edited or not
|-
| colspan="4" align="center" |'''Deprecated'''
|-
| ajax_section_move
| format
| up to 2.3
| See [[Course formats]]
|-
| ajax_support
| format
| up to 2.3
| See [[Course formats]]
|-
| delete_course
| mod
| up to 3.1
| use event observer
|-
| display_content
| format
| up to 2.3
| See [[Course formats]]
|-
| get_post_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| get_section_name
| format
| up to 2.3
| See [[Course formats]]
|-
| get_section_url
| format
| up to 2.3
| See [[Course formats]]
|-
| get_types
| mod,ltisource
| up to 3.0
| Replaced with ''get_shortcuts'' in 3.1
|-
| get_view_actions
| mod,booktool
|
| Only called if legacy log is used on the site
|-
| load_content
| format
| up to 2.3
| See [[Course formats]]
|-
| scale_used
| mod
| up to 3.0
|
|-
| uses_sections
| format
| up to 2.3
| See [[Course formats]]
|-
| question_list_instances
| mod
| up to 3.8
| Use "questions_in_use" instead
|}
'''Notes:'''

if Moodle version is not specified, this means that callback existed for a long time and can be found in all [[Releases|currently supported]] Moodle versions
== Adding new callbacks to core ==
If you are preparing a patch for core which adds a new callback here are some things which should be considered.

TBA see https://tracker.moodle.org/browse/MDL-60510

Cache API

2022-06-11T03:42:30Z

Emerrill: MDL-42012 has been resolved in 3.8.6 and 3.9.3.

This document details the Cache API aka MUC aka Moodle's Universal Cache.
I've chosen to use a tutorial/example flow for this document always working with a theoretical module plugin called myplugin.
There is also a [[Cache API - Quick reference]] if you would rather read that.
==Basic usage==
It's very easy to get started with the Cache API. It is designed to be as easy and as quick to use as possible and is predominantely self contained.
All you need to do is add a definition for your cache and you are ready to start working with the Cache API.
===Creating a definition===
Cache definitions exist within the db/caches.php file for a component/plugin. 
In the case of core that is the moodle/lib/db/caches.php file, in the case of a module that would be moodle/mod/myplugin/db/caches.php.

The definition is used API in order to understand a little about the cache and what it is being used for, it also allows the administrator to set things up especially for the definition if they want.
From a development point of view the definition allows you to tell the API about your cache, what it requires, and any (if any) advanced features you want it to have. 
The following shows a basic definition containing just the bare minimum:
<syntaxhighlight lang="php">
// moodle/mod/myplugin/db/caches.php
$definitions = [
'somedata' => [
'mode' => cache_store::MODE_APPLICATION,
]
];
</syntaxhighlight>
This informs the API that the myplugin module has a cache called ''somedata'' and that it is an application (globally shared) cache.

When creating a definition thats the bare minimum, to provide an area ''(somedata)'' and declare the type of the cache application, session, or request.
* An application cache is a shared cache, all users can access it.
* Session caches are scoped to a single users session, but may not actually be stored in the session.
* Request caches you can think of as static caches, only available to the user owning the request, and only alive until the end of the request.
There are of course many more options available that allow you to really take the cache by the reigns, you can read about some of the important ones further on, or skip ahead to [[#The definition]] section which details the available options in full.

Please note that for each definition a language string with the name ''cachedef_'' followed by the name of the definition is expected. Using the example above you would have to define:
<syntaxhighlight lang="php">
// moodle/mod/myplugin/lang/en/mod_myplugin.php
$string['cachedef_somedata'] = 'This is the description of the cache somedata';
</syntaxhighlight>
===Getting a cache object===
Once your definition has been created you should bump the version number so that Moodle upgrades and processes the definitions file at which point your definition will be useable.

Now within code you can get a cache object corresponding to the definition created earlier.
<syntaxhighlight lang="php">
$cache = cache::make('mod_myplugin', 'somedata');
</syntaxhighlight>
The cache::make method is a factory method, it will create a cache object to allow you to work with your cache. The cache object will be one of several classes chosen by the API based upon what your definition contains. All of these classes will extend the base cache class, and in nearly all cases you will get one of cache_application, cache_session, or cache_request depending upon the mode you selected.
===Using your cache object===
Once you have a cache object (will extend the cache class and implements cache_loader) you are ready to start interacting with the cache.

Of course there are three basic basic operations. get, set, and delete.

The first is to send something to the cache.
<syntaxhighlight lang="php">
$result = $cache->set('key', 'value');
</syntaxhighlight>
Easy enough. The key must be an int or a string. The value can be absolutely anything your want that is [https://www.php.net/manual/en/function.serialize.php serializable].
The result is true if the operation was a success, false otherwise.

The second is to fetch something from the cache.
<syntaxhighlight lang="php">
$data = $cache->get('key');
</syntaxhighlight>
$data will either be whatever was being stored in the cache, or false if the cache could not find the key.

The third and final operation is delete.
<syntaxhighlight lang="php">
$result = $cache->delete('key');
</syntaxhighlight>
Again just like set the result will either be true if the operation was a success, or false otherwise.

You can also set, get, and delete multiple key=>value pairs in a single transaction.
<syntaxhighlight lang="php">
$result = $cache->set_many([
'key1' => 'data1',
'key3' => 'data3'
]);
// $result will be the number of pairs sucessfully set.

$result = $cache->get_many(['key1', 'key2', 'key3']);
print_r($result);
// Will print the following:
// array(
// 'key1' => 'data1',
// 'key2' => false,
// 'key3' => 'data3'
// )

$result = $cache->delete_many(['key1', 'key3']);
// $result will be the number of records sucessfully deleted.
</syntaxhighlight>
That covers the basic operation of the Cache API. 
In many situations there is not going to be any more to it than that.
==Ad-hoc Caches==
This is the alternative method of using the cache API. 
It involves creating a cache using just the required params at the time that it is required. It doesn't require that a definition exists making it quicker and easier to use, however it can only use the default settings and is only recommended for insignificant caches (rarely used during operation, never to be mapped or customised, only existsing in a single place in code).

Once a cache object has been retrieved it operates exactly as the same as a cache that has been created for a definition.

To create an ad-hoc cache you would use the following:
<syntaxhighlight lang="php">
$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'mod_myplugin', 'mycache');
</syntaxhighlight>
Really don't be lazy, if you don't have a good reason to use an ad-hoc cache you should be spending a extra 5 minutes creating a definition.
==The definition==
The above section illustrated how to create a basic definition, specifying just the area name (the key) and the mode for the definition. Those being the two required properties for a definition. 
There are many other options that will let you make the most of the Cache API and will undoubtedly be required when implementing and converting cache solutions to the Cache API.

The following details the options available to a definition and their defaults if not applied:
<syntaxhighlight lang="php">
$definitions = [
// The name of the cache area is the key. The component/plugin will be picked up from the file location.
'area' => [
'mode' => cache_store::MODE_*,
'simplekeys' => false,
'simpledata' => false,
'requireidentifiers' => ['ident1', 'ident2'],
'requiredataguarantee' => false,
'requiremultipleidentifiers' => false,
'requirelockingread' => false,
'requirelockingwrite' => false,
'maxsize' => null,
'overrideclass' => null,
'overrideclassfile' => null,
'datasource' => null,
'datasourcefile' => null,
'staticacceleration' => false,
'staticaccelerationsize' => null,
'ttl' => 0,
'mappingsonly' => false,
'invalidationevents' => ['event1', 'event2'],
'canuselocalstore' => false
'sharingoptions' => cache_definition::SHARING_DEFAULT,
'defaultsharing' => cache_definition::SHARING_DEFAULT,
],
];
</syntaxhighlight>
===Setting requirements===
The definition can specify several requirements for the cache. 
This includes identifiers that must be provided when creating the cache object, that the store guarantees data stored in it will remain there until removed, a store that supports multiple identifiers, and finally read/write locking.
The options for these are as follows:
; simplekeys : [bool] Set to true if your cache will only use simple keys for its items. Simple keys consist of digits, underscores and the 26 chars of the english language. a-zA-Z0-9_ If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes. It will be better for performance and possible only because we know the keys are safe.
; simpledata : [bool] If set to true we know that the data is scalar or array of scalar. If true, the data values will be stored as they are. Otherwise they will be serialised first.
; requireidentifiers : [array] An array of identifiers that must be provided to the cache when it is created.
; requiredataguarantee : [bool] If set to true then only stores that can guarantee data will remain available once set will be used.
; requiremultipleidentifiers : [bool] If set to true then only stores that support multiple identifiers will be used.
; requirelockingread : [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use this setting unless 100% absolutely positively required. Remember 99.9% of caches will NOT need this setting. This setting will only be used for application caches presently.
; requirelockingwrite : [bool] If set to true then a lock will be gained before writing to the cache store. As above this is not recommended unless truly needed. Please think about the order of your code and deal with race conditions there first. This setting will only be used for application caches presently.
===Cache modifiers===
You are also to modify the way in which the cache is going to operate when working for your definition. 
By enabling the static option the Cache API will only ever generate a single cache object for your definition on the first request for it, further requests will be returned the original instance. This greatly speeds up the collecting of a cache object. 
Enabling persistence also enables a static store within the cache object, anything set to the cache, or retrieved from it will be stored in that static array for the life of the request.
This makes the persistence options some of the most powerful. If you know you are going to be using you cache over and over again or if you know you will be making lots of requests for the same items then this will provide a great performance boost.
Of course the static storage of cache objects and of data is costly in terms of memory and should only be used when actually required, as such it is turned off by default.
As well as persistence you can also set a maximum number of items that the cache should store (not a hard limit, its up to each store) and a time to live (ttl) although both are discouraged as efficient design negates the need for both in most situations.
; staticacceleration : [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for this definition once, further requests will be given the original instance. Second the cache loader will keep an array of the items set and retrieved to the cache during the request. This has several advantages including better performance without needing to start passing the cache instance between function calls, the downside is that the cache instance + the items used stay within memory. Consider using this setting when you know that there are going to be many calls to the cache for the same information or when you are converting existing code to the cache and need to access the cache within functions but don't want to add it as an argument to the function.
; staticaccelerationsize : [int] This supplements the above setting by limiting the number of items in the caches persistent array of items. Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to offset calls to the cache store.
; ttl : [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and instead try to create an event driven invalidation system (even if the event is just time expiring, better not to rely on ttl). Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not.
; maxsize : [int] If set this will be used as the maximum number of entries within the cache store for this definition. Its important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit.
; canuselocalstore : [bool] This setting specifies whether the cache can safely be local to each frontend in a cluster which can avoid latency costs to a shared central cache server. The cache needs to be carefully written for this to be safe. It is conceptually similar to using $CFG->localcachedir (can be local) vs $CFG->cachedir (must be shared). Look at purify_html() in lib/weblib.php for an example.

===Overriding a cache loader===
This is a super advanced feature and should not be done. ever. Unless you have an very good reason to do so.
It allows you to create your own cache loader and have it be used instead of the default cache loader class. The cache object you get back from the make operations will be an instance of this class.
; overrideclass : [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the definition to take 100% control of the caching solution. Any class used here must inherit the cache_loader interface and must extend default cache loader for the mode they are using.
; overrideclassfile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.
===Specifying a data source===
This is a great wee feature, especially if your code is object orientated.

It allows you to specify a class that must inherit the cache_data_source object and will be used to load any information requested from the cache that is not already being stored.

When the requested key cannot be found in the cache the data source will be asked to load it. The data source will then return the information to the cache, the cache will store it, and it will then return it to the user as a request of their get request. Essentially no get request should ever fail if you have a data source specified.
; datasource : [string] A class to use as the data loader for this definition. Any class used here must inherit the cache_data_source interface.
; datasourcefile : [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.
GOTCHA: Note that, in Moodle versions prior to 3.8.6 and 3.9.3, if caching is disabled then *nothing* will be loaded through the data source which is probably not what you expect (rather than the data source being loaded every time but never cached). See also:

https://tracker.moodle.org/browse/MDL-42012
===Misc settings===
The following are stand along settings that don't fall into any of the above categories.
; invalidationevents :[array] An array of events that should cause this cache to invalidate some or all of the items within it. Note that these are NOT normal moodle events and predates the [[Events API]] . Instead these are arbitrary strings which can be used by cache_helper::purge_by_event('changesincoursecat'); to mark multiple caches as invalid at once without the calling code knowing which caches are affected.
; mappingsonly : [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one reason or another.
; sharingoptions : [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options.
; defaultsharing : [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very specific reason not to use the system default.
==The loader==

== Localized stores for distributed high performance caching ==
Most cache definitions are simple in that the code expects to be able to purge the cache, or update it, and for this to be universally available from then on to all code which loads from this cache again. But as you scale up having a single mega shared cache store doesn't work well for a variety of reasons, including extra latency between multiple front ends and the shared cache service, the number of connections the cache server can handle, the cost of IO between services, and depending on the cache definition issues with locking while writing.

So if you want very high performance caching then you need to write you code so that it can support being distributed, or localized, which means that each front end can have it's own independent cache store. But this architecture means that you have no direct way to communicate from code running in one place to invalidate the caches on all the other front ends. In order to achieve this you need to carefully construct cache keys so that if the content changes then it uses a new cache key, which will of course be a cache miss and then it will regenerate using fresh data. There are multiple ways to achieve this, a couple common example strategies are below.
=== When should you localize? ===
Not all caches are good candidates to localize and some can have a detrimental effect if localized for the wrong reasons.
[[File:When to localize cache.png|alt=When to localize a cache|none|thumb|683x683px|When to localize a cache]]
=== Revision numbers as key suffix ===
A simple method is storing a version number somewhere and appending that to your key. This is the most common method used in Moodle, simply store a number somewhere which is globally shared such as in a custom db field, or using set_config / get_config.

One small edge case with this approach is you now need to make sure that the incrementing code is atomic, which means you should use a DB transaction, or gain a lock, before bumping the version so you don't get two conflicting changes ending up on the same version with a race condition. However if you are anticipating high turnover rate of the cache you probably have a deeper issue, see 'Fast churning keys' below.

One potential benefit of a simple version number strategy if your cache misses are very expensive, is that you can check for the presence of a version, and if it doesn't exist it is easy to simply retrieve the previous version and use it in the mean time, while you could generate the new version asynchronously. This is an advanced concept and depends on the use case and has the obvious disadvantage of showing stale data.

An example of this strategy in Moodle is the theme versions cache (NOTE: this is not actually in MUC but the caching concepts are the same):

https://github.com/moodle/moodle/blob/master/lib/outputlib.php#L88-L100

It works best with a cache store that supports Least Recently Used garbage collection.
=== Revision numbers as value suffix instead of key suffix ===
This is conceptually the same as above but has two important differences. Firstly because the key itself is always the same then only a single version of some value will be stored on disk or in memory for any given cache store which makes it much more efficient in terms of storage. But secondly this comes with a higher coding complexity cost because it will no longer be guaranteed to be correct because a local cache could return a hit with a stale version. So if you need it to be correct you will need to parse out the revision from the value and then confirm the revision is correct before using the value. If it is invalid then you need to treat it as a miss and handle that. One way is to rebuild and set it, but this loses the advantage of primary and final caches (see below). A better way is to delete the local cache but not the final cache by passing a second param of false to delete, and then getting the value again which will repopulate the local cache from the shared cache:
$cache->delete('foo', false); // Delete the primary / local stale version
$cache->get('foo'); // Get the final / shared version (which may also be stale!)
But this also is imperfect if there are 3 layers of caching, see [https://tracker.moodle.org/browse/MDL-72837 MDL-72837] for a full discussion and a possible new api to handle this.

This method is how the course modinfo cache is localized.
=== Using time as a key suffix ===
Another common approach is to use a timestamp, this is how some of the core cache numbers work, see increment_revision_number() for some examples. This has the benefit of not needing any transaction or locking, but you do run the risk of two processes clashing if they happen to run in the same second.

It may look like Moodle theme-related caching uses this strategy, but actually if you look at [https://github.com/moodle/moodle/blob/df0e58adb140f90712bcd3229ad936d3b4bc15d9/lib/outputlib.php#L88 the code for theme_get_next_revision], you will see that it is actually guaranteeing to generate a unique new integer which mitigates the clashing mentioned above. It is just making that integer close to current time-stamp, to make it more self-documenting.

https://github.com/moodle/moodle/blob/master/lib/datalib.php#L1131-L1145

It works best with a cache store that supports Least Recently Used garbage collection.
=== Content hashes as keys ===
A great strategy is to use a digest or hash such as sha1 / sha256 of the content stored inside the cache, or in even more advanced scenarios a hash of the dependencies of the content in the cache. This guarantees that the key will be unique, and can be truly distributed without any synchronous communication between the front ends.

This strategy can work very well when building up large cache items from many smaller cache fragments in a nested tree structure, eg when caching a structure which is built of other cache items, eg 10 chunks of html to get combined into a large chunk to be cached, you would append the 10 hashes of the 10 smaller chunks and then hash that to use as the key for the combined cache item. This means you can mutate a small part of a tree structure and quickly re-generate the whole tree without expensively regenerating all of the other branches and leaves in the tree.

This is known as 'Russian Doll' caching:

https://blog.appsignal.com/2018/04/03/russian-doll-caching-in-rails.html

This is a very common strategy is many distributed systems, outside of the context of caching, and is conceptually how git works internally which is why commits are a sha1 hash.

This strategy works well if you may periodically change back and forth to previous states which will still be present and so be immediate hits without re-warming. It works best with a cache store that supports Least Recently Used garbage collection.
=== Primary and Final caches ===
Because http requests are generally assigned randomly or round-robin to front ends, when a cache item version changes you will now effectively have an empty cache on every front end. As you get the same cache item again and again on each front end it will continue to be a cache miss on each local box until they are all warm, which can ironically mean that on average for a fast changing, but not often requested cache item, your cache hit rate will be very low and much worse than if you had a shared cache. The solution here is to have multiple levels of caches setup, a local cache backed by a shared cache. You do not need to do anything special in the code to support this if your cache is already localizable, the MUC manages this for you, ie if you request a key which is missing from the local cache it will then request it from the shared cache. If present it will copy it back to the local cache and then return the value. If it is not present in either then your fall back code will generate the item, and it will be written to both cache stores at the same time.

This is especially important if you are scaling up and down the number of frontends quickly. If you suddenly need more horizontal scale and create a bunch of new front ends with empty caches and no shared cache they will all consume even more resources warming up and loading the shared services such as the database and filesystem.

A good rule of thumb is to pair similar types of local and shared caches together. For instance it is very common to store the Moodle string cache in APCu because it is very heavily used, so an in-memory cache is the fastest and is well paired this a shared cache like Redis. coursemodinfo on the other hand is often very large so isn't as practical to store in Redis so it is usually cached on disk, so you could have a local file cache (which could often be very fast SSD) and pair it with a shared disk cache in dataroot (often much slower over NFS or Gluster etc).

As you scale even bigger, a new bottleneck can appear when purging a shared disk cache ie when you deploy a new version. A full purge needs to iterate over and remove and sync a very large number of files, which can take some time. See MDL-69088 for a proposed fix.
=== Beware fast churning keys ===
A big concern when designing a cache is how fast you anticipate it changing. If it contains very fast moving data but sparsely requested data (see above) then you can end up in a situation where you are effectively just using the shared final cache, and wasting latency and space and IO cloning data to the local cache where is may not be hit again very much. As always caching is a balancing act trading off between CPU, time and disk, and ultimately money.

Even if your cache is able to use a local store that doesn't mean it actually will be configured to be local (and your code can't tell either way). So a wasteful cache item will consume much more space storing all the previous versions of its items even if it isn't localized, and it will be much worse if it is.
=== Time-To-Live for distributed caches ===
Another consideration is the total size of your cache stores across all the front ends. As cache keys change they are never be invalidated or purged. So you should have in place some process to garbage collect stale items. This is more a concern for the cache store implementations and the configuration but worth considering. Some stores are deleted on upgrade, or have a Time-To-Live or a Least Recently Used strategy for deleting stale items.
==Using a data source==

==Developing cache plugins==
==Miscellaneous==
* Checkout important [https://moodle.org/local/chatlogs/index.php?q=cache discussion about the Cache API at the Moodle developer (Telegram) chat]

Output callbacks

2022-02-24T23:30:06Z

Emerrill: Fixing minor type

There are cases where we want any plugin to contribute to a chunk of the output of any given page. We want this to be loosely coupled so you don't have say an admin tool's code leaking into your theme. In the past many plugins had an installation step like "Copy this into your theme header" which is what we want to completely avoid.

There are a variety of [[Callbacks]] which enable any plugin to add or modify certain parts of the output and at certain stages in the rendering process. These callbacks are probably most useful for local plugins or admin tools which bring some functionality to the whole site instead of just certain pages. But they can also be used by any plugin to conditionally augment the output too.
= add_htmlattributes =
{{Moodle 3.3}}

This is used to append extra attributes into the html element of the page which are required elsewhere. An example might be a facebook block plugin which uses the opengraph js libraries which need the xml namespace to be setup. It should return an array of attribute key and values like this:
<syntaxhighlight lang="php">
function tool_facebook_add_htmlattributes() {
return array(
'xmlns:og' => 'http://ogp.me/ns#',
);
}
</syntaxhighlight>
Because multiple plugins can add extra attributes there is potential namespace clash issues. ie in the Facebook opengraph example stick with "xmlns:og" as specified by Facebook so that if multiple plugins declare the same key / value then they will match. Not that duplicates attribute keys are merged.
= before_footer =
{{Moodle 3.3}}

This enables you to easily inject a chunk of JS or CSS into every page, for instance an analytics tool like Google Analytics or Facebook pixel. It only has side effects and it's return value is ignored:
<syntaxhighlight lang="php">
function tool_mytool_before_footer() {
global $PAGE;
$PAGE->requires->js_init_code("alert('before_footer');");
}
</syntaxhighlight>
= before_http_headers =
{{Moodle 3.3}}

This enables you to easily inject a HTTP header into every page. It only has side effects and it's return value is ignored:
<syntaxhighlight lang="php">
function tool_headertest_before_http_headers() {
header("X-CustomHeader: SomeValue");
}
</syntaxhighlight>
Note that this is called after the page is generated and just prior to the headers being sent. So internal system state may have already been changed (eg adding events to the log) and the page generation may have been expensive and the student will be considered to have viewed the page.

You should generally not use this callback for things like redirecting away under some conditions, instead consider either the [[Login_callbacks#after_config|after_config]] or the [[Login_callbacks#after_require_login|after_require_login]] callbacks which fire earlier in the request lifecycle.
= before_standard_html_head =
{{Moodle 3.3}}

This is an API alternative to appending to $CFG->additionalhtmlhead and could be used for adding meta tags or similar to the page. It MUST return a string containing a well formed html chunk, or at minimum an empty string.
<syntaxhighlight lang="php">
function tool_headtag_before_standard_html_head() {
return "<meta name='foo' value='before_top_of_body_html' />\n";
}
</syntaxhighlight>
= before_standard_top_of_body_html =
{{Moodle 3.3}}

This enables a plugin to insert a chunk of html at the start of the html document. Typical use cases include some sort of alert notification, but in many cases the [[Notifications]] may be a better fit. It MUST return a string containing a well formed chunk of html, or at minimum an empty string.
<syntaxhighlight lang="php">
function tool_callbacktest_before_standard_top_of_body_html() {
return "<div style='background: red'>Before standard top of body html</div>";
}
</syntaxhighlight>
= render_navbar_output =
{{Moodle 3.2}}

TBA

Acceptance testing/Browsers/Working combinations of OS+Browser+selenium

2016-11-07T17:02:48Z

Emerrill: Typo in last change

= Working combinations of OS+Browser+selenium =
As OS, Browsers and Selenium keeps updating, some combination might fail on different Moodle releases.

Following combinations have been tested at the time of release of Moodle version and will be supported for that combination.
NOTE: Chromedriver >= 2.17 is required for behat to capture exceptions

== Moodle 3.2 and master ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
| Linux - Ubuntu 16.04
| Firefox 47.0.1
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]
| N/A
| N/A
|-
|Linux - Ubuntu 16.04
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&alt=media Chrome 53.0]
| [http://selenium-release.storage.googleapis.com/index.html?path=2.53/ 2.53.1] and [http://selenium-release.storage.googleapis.com/index.html?path=3.0-beta4/ 3.0.0-beta4]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.24/ 2.24]
| N/A
|-
| Linux - Ubuntu 16.04
| Phantomjs 2.1.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Chrome v53.0
| [http://selenium-release.storage.googleapis.com/index.html?path=2.53/ 2.53.1] and [http://selenium-release.storage.googleapis.com/index.html?path=3.0-beta4/ 3.0.0-beta4]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.24/ 2.24]
| N/A
|-
| MacOS X
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| MacOS X
| [http://www.slimjet.com/chrome/google-chrome-old-version.php Chrome v53.0]
| [http://selenium-release.storage.googleapis.com/index.html?path=2.53/ 2.53.1] and [http://selenium-release.storage.googleapis.com/index.html?path=3.0-beta4/ 3.0.0-beta4]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.24/ 2.24]
| N/A
|-
| MacOS X
| PhantomJS 2.1.1
| 2.53.1
| N/A
| N/A
|}

== Moodle 3.1 ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
| Linux - Ubuntu 16.04
| Firefox 47.0.1
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]
| N/A
| N/A
|-
|Linux - Ubuntu 16.04
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&alt=media Chrome 51.0]
| 2.53.1
| 2.22
| N/A
|-
| Linux - Ubuntu 16.04
| Phantomjs 2.1.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Chrome v51.0
| 2.53.1
| 2.22
| N/A
|-
| MacOS X
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| MacOS X
| Chrome v51.0
| 2.53.1
| 2.22
| N/A
|-
| MacOS X
| PhantomJS 2.1.1
| 2.53.1
| N/A
| N/A
|}

== Moodle 3.0 and lower ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
|Linux - Ubuntu 14.10
|Firefox 42.0
|2.47.1
| N/A
| N/A
|-
|Linux - Ubuntu 14.10
|Chrome 46.0
|2.47.1
| 2.19.346067
| N/A
|-
|Linux - Ubuntu 14.10
|Phantomjs 2.0.0
|2.47.1
| N/A
| N/A
|-
|Windows 7/10
|Firefox 41.0
|2.47.1
| N/A
| N/A
|-
|Windows 7/10
|Chrome 47.0
|2.47.1
| 2.20
| N/A
|-
|MacOS X
|Firefox 41.0
|2.47.1
| N/A
| N/A
|-
|MacOS X
|Chrome 46.0
|2.47.1
| 2.20
| N/A
|-
|MacOS X
|Chrome 48.0
|2.51.0
| 2.21
| N/A
|-
|MacOS X
|PhantomJS - 2.0.0 & 2.1.1
|2.48.2
| N/A
| N/A
|}

Acceptance testing/Browsers/Working combinations of OS+Browser+selenium

2016-11-07T17:01:52Z

Emerrill: Add link to old chrome bundles

= Working combinations of OS+Browser+selenium =
As OS, Browsers and Selenium keeps updating, some combination might fail on different Moodle releases.

Following combinations have been tested at the time of release of Moodle version and will be supported for that combination.
NOTE: Chromedriver >= 2.17 is required for behat to capture exceptions

== Moodle 3.2 and master ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
| Linux - Ubuntu 16.04
| Firefox 47.0.1
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]
| N/A
| N/A
|-
|Linux - Ubuntu 16.04
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&alt=media Chrome 53.0]
| [http://selenium-release.storage.googleapis.com/index.html?path=2.53/ 2.53.1] and [http://selenium-release.storage.googleapis.com/index.html?path=3.0-beta4/ 3.0.0-beta4]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.24/ 2.24]
| N/A
|-
| Linux - Ubuntu 16.04
| Phantomjs 2.1.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Chrome v53.0
| [http://selenium-release.storage.googleapis.com/index.html?path=2.53/ 2.53.1] and [http://selenium-release.storage.googleapis.com/index.html?path=3.0-beta4/ 3.0.0-beta4]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.24/ 2.24]
| N/A
|-
| MacOS X
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| MacOS X
| [http://www.slimjet.com/chrome/google-chrome-old-version.php/ Chrome v53.0]
| [http://selenium-release.storage.googleapis.com/index.html?path=2.53/ 2.53.1] and [http://selenium-release.storage.googleapis.com/index.html?path=3.0-beta4/ 3.0.0-beta4]
| [http://chromedriver.storage.googleapis.com/index.html?path=2.24/ 2.24]
| N/A
|-
| MacOS X
| PhantomJS 2.1.1
| 2.53.1
| N/A
| N/A
|}

== Moodle 3.1 ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
| Linux - Ubuntu 16.04
| Firefox 47.0.1
| [http://selenium-release.storage.googleapis.com/2.53/selenium-server-standalone-2.53.1.jar 2.53.1]
| N/A
| N/A
|-
|Linux - Ubuntu 16.04
|[https://www.googleapis.com/download/storage/v1/b/chromium-browser-snapshots/o/Linux_x64%2F386249%2Fchrome-linux.zip?generation=1460160957434000&alt=media Chrome 51.0]
| 2.53.1
| 2.22
| N/A
|-
| Linux - Ubuntu 16.04
| Phantomjs 2.1.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| Windows 7/10
| Chrome v51.0
| 2.53.1
| 2.22
| N/A
|-
| MacOS X
| Firefox 47.0.1
| 2.53.1
| N/A
| N/A
|-
| MacOS X
| Chrome v51.0
| 2.53.1
| 2.22
| N/A
|-
| MacOS X
| PhantomJS 2.1.1
| 2.53.1
| N/A
| N/A
|}

== Moodle 3.0 and lower ==
{| class="wikitable"
|OS
|Browser
|Selenium Server
|Chrome Driver
|IE Driver
|-
|Linux - Ubuntu 14.10
|Firefox 42.0
|2.47.1
| N/A
| N/A
|-
|Linux - Ubuntu 14.10
|Chrome 46.0
|2.47.1
| 2.19.346067
| N/A
|-
|Linux - Ubuntu 14.10
|Phantomjs 2.0.0
|2.47.1
| N/A
| N/A
|-
|Windows 7/10
|Firefox 41.0
|2.47.1
| N/A
| N/A
|-
|Windows 7/10
|Chrome 47.0
|2.47.1
| 2.20
| N/A
|-
|MacOS X
|Firefox 41.0
|2.47.1
| N/A
| N/A
|-
|MacOS X
|Chrome 46.0
|2.47.1
| 2.20
| N/A
|-
|MacOS X
|Chrome 48.0
|2.51.0
| 2.21
| N/A
|-
|MacOS X
|PhantomJS - 2.0.0 & 2.1.1
|2.48.2
| N/A
| N/A
|}

Search engines

2016-05-12T14:04:17Z

Emerrill: Update information about file indexing.

{{Search engine plugins}}
== Introduction ==

Search engines index big amounts of data in a structured way that allow users to query them and extract relevant data. There are many search engines with nice APIs to set data on and retrieve data from. We made Moodle's global search pluggable so different backends can be used, from a simple database table (ok for small sites but unusable for big sites) to open sourced systems like solr or elasticsearch (on top of Apache Lucene) or proprietary cloud based systems.

== Terms ==

'''Index''': You know what it means, but in this page we use '''index''' as the data container in your search engine. It can be an instance in your search engine server or a database table name if you are writing a search engine for mongodb (just an example)
'''Document''': A "searchable" unit of data like a database entry, a forum post... You can see it as one of the search results you might expect to get returned by a search engine.

== Writing your own search engine plugin ==

To write your own search engine you need to code methods to set, retrieve and delete data from your search engine. You will need to add a '''\search_yourplugin\engine''' class in '''search/engine/yourplugin/classes/engine.php''' extending '''\core_search\engine'''.

=== Search engine setup ===

Your search engine needs to be prepared to index data, you can have a script for your plugin users so they can easily create the required structure the search engine. Otherwise add instructions about how to do it.

You can get the list of fields Moodle needs along with some other info you might need like the field types calling '''\core_search\document::get_default_fields_definition()'''

=== Add contents ===

This method is executed when Moodle contents are being indexed in the search engine. Moodle iterates through all search areas extracting which contents should be indexed and assigns them a unique id based on the search area.
<code php>
public function add_document(array $doc, $fileindexing = false) {
// Use curl or any other method or extension to push the document to your search engine.
}
</code>

'''$doc''' will contain a document data with all required fields (+ maybe some optionals) and its contents will be already validated so a integer field will come with an integer value...
'''$fileindexing''' will be true the search area that generated the document supports attached files. Will be false if your plugin does not support file indexing

==== File indexing ====

If the engine supports file indexing, and $fileindexing is passed as true to add_document (indicating the area supports indexing), then the document sent will have all files associated with it attached as '''stored_file''' instances. They are retrieved from the document with get_files(), and it It is up to the engine to determine how these are to be indexed, including content extraction.

The files attached to a document for indexing represent the authoritative set of files for that document. This means the engine should ensure that when re-indexing a document, any files no longer attached to it are not in the index.

=== Retrieve contents ===

This is the key method, as search engine plugins have a lot of flexibility here.

You will get the search filters the user specified and the list of contexts the user can access and this function should return an array of \core_search\document objects.

<code php>
public function execute_query($filters, $usercontexts, $limit = 0) {
// Prepare a query applyting all filters.
// Include $usercontexts as a filter to contextid field.
// Send a request to the server.
// Iterate through results.
// Check user access, read https://docs.moodle.org/dev/Search_engines#Security for more info
// Convert results to '''\core_search\document''' type objects using '''\core_search\document::set_data_from_engine'''
// Return an array of '''\core_search\document''' objects, limiting to $limit or \core_search\manager::MAX_RESULTS if empty.
}
</code>

==== File indexing ====

When retrieving results based on a file hit, you can attach '''stored_file''' instances to the document to indicate what file(s) produced the match. This information is rendered as a part of the results page. Because of rendering considerations, this should be limited to a reasonable number of 'match files' for a given document. The search_solr limits to a maximum of 3 matching files.

==== Security ====

It is crucial that this function is checking '''\core_search\document::check_access''' results and do not return results where the user do not have access. Moodle already performs part of the required security checkings, but search areas always have the last word and it should be respected.

==== Getting enough results ====

Because in some cases many records may fail check_access(), engines should make provisions to make sure enough a full set of documents is returned, even if it must check many more documents. See MDL-53758 for a better discussion of this.

=== Record counts ===
get_query_total_count() must be implemented to return the number of results that available for the most recent call to execute_query(). This is used to determine how many pages will be displayed in the paging bar. For more discussion see MDL-53758.

<code php>
public function get_query_total_count() {
// Return an approximate count of total records for the most recently completed execute_query().
}
</code>

The value can be an estimate. The search manager will ensure that if a page is requested that is beyond the last page of actual results, the user will seamlessly see the last available page.

There are a number of ways to determine what value to return from get_query_total_count(). Note that if the method you choose requires you to process more than $limit valid documents, you still must only return $limit records from execute_query(). Some of the ways to do this are:

==== Return how many possible there are ====
This would mean how many results we have processed and passed (using check_access()), plus any candidate results that are left. Alternately it is the total count of records for the query, minus the ones we have rejected so far. search_solr uses this method.

'''User experience:''' User sees a full compliment of pages. If the pass-to-fail ration on check_access() is very high (and we generally expect it to be), then the number of pages should generally be accurate. This method will always error on the high side. It is possible that when clicking on a higher page there will be no results available, so the search manager will seamlessly show them the last actual page with actual results.

'''Pros:''' Free or very cheap with some engines - no need to check access/process records beyond the current page. Reasonable user experience.

'''Cons:''' Future page count is not perfect, so can result in page not being available when clicked (but the manager mitigates this).

==== Return the current count plus 1 ====
In this case, you would calculate all the records through $limit plus one. If the plus one exists, you would return that count, otherwise you would return the actual count.

'''User experience:''' User would only see up to the current page, plus one more, except when on the last page of results. Gmail search works similar to this in the way you can only navigate to the next page of results, not an arbitrary page.

'''Pros:''' Relatively cheap. Reasonable user experience.

'''Cons:''' User can’t jump to an arbitrary page even if they know what page a particular result is on

==== Calculate all results up to MAX_RESULTS ====
This would mean calculating the full set of results up to MAX_RESULTS, and returning the actual count of results.
'''User experience:''' The user will see the exact number of pages they should

'''Pros:''' cleanest user experience

'''Cons:''' Very expensive, as you are calculating up to MAX_RESULTS results on every page, even if you are only showing the first page

==== Just return MAX_RESULTS ====
'''User experience:''' User will always see 10 pages, except when they are on the last page of actual results.

'''Pros:''' Free

'''Cons:''' Worst user experience

=== Delete contents ===

<code php>
public function delete($areaid = false) {
if ($areaid === false) {
// Delete all your search engine index contents.
} else {
// Delete all your search engine contents where areaid = $areaid.
}
}
</code>

'''\core_search\document::check_access''' will return \core_search\manager::ACCESS_DELETED if a document returned from the search engine is not available in Moodle any more, you can use this to clean up the search engine contents with some kind of '''\search_yourplugin\engine::delete_by_id''' method. You can look at '''search/engine/solr/classes/engine.php''' '''execute_query''' method for an example of this.

=== Other abstract methods you need to overwrite ===

<code php>
public function file_indexing_enabled() {
// Defaults to false, overwrite it if your search engine supports file indexing.
return false;
}
</code>

<code php>
public function is_server_ready() {
// Check if your search engine is ready.
}
</code>

=== Other methods you might be interested in overwriting ===

<code php>
public function is_installed() {
// Check if the required PHP extensions you need to make the search engine work are installed.
}
</code>

<code php>
public function optimize() {
// Optimize or defragment the index contents.
}
</code>

These methods are called while the indexing process is running and allow search engine to hook the indexing process.

<code php>
public function index_starting($fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function index_complete($numdocs = 0, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_starting($searcharea, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_complete($searcharea, $numdocs = 0, $fullindex = false) {
return true;
}
</code>

== Adapting document formats to your search engine format ==

'''\core_search\document''' is the class that represents a document, depending on your search engine backend limitations or on how it stores time values you might be interested in overwriting this class in '''\search_yourplugin\document'''. The main functions you might be interested in overwriting are:

==== Format date/time fields ====

<code php>
public static function format_time_for_engine($timestamp) {
// Convert $timestamp to a string using the format used by your search engine.
}
</code>

By default, '''\core_search\document::format_time_for_engine''' returns a timestamp (integer).

==== Import date/time contents from the search engine ====

<code php>
public static function import_time_from_engine($time) {
// Convert the string returned from the search engine as a date/time format to a timestamp (integer).
}
</code>

By default, '''\core_search\document::import_time_from_engine''' returns a timestamp (integer).

==== Format string fields ====

<code php>
public static function format_string_for_engine() {
// Limit the string length, convert iconv if your search engine only supports an specific charset...
}
</code>

By default, '''\core_search\document::format_string_for_engine''' returns the string as it is.

[[Category:Search]]
[[Category:Plugins]]

Global search

2016-05-12T13:47:41Z

Emerrill: Update SSL info

= Installation =

To use Solr as Moodle's search engine you need the PHP Solr extension and a Solr server.

== PHP Solr extension ==

You need PHP Solr extension installed. You can download the official latest versions from [http://pecl.php.net/package/solr](http://pecl.php.net/package/solr) The minimum required version is PECL Solr 2.1 for PHP 5 branch and PECL Solr 2.4 for PHP 7 branch.

Basic installation steps (using apache web server):

=== Linux (Debian/Ubuntu) ===

sudo apt-get install libpcre3-dev libxml2-dev libcurl4-openssl-dev
sudo apt-get install php5-dev
sudo apt-get install php-pear
sudo pecl install solr
sudo service apache2 restart
sudo sh -c "echo 'extension=solr.so' > /etc/php5/apache2/conf.d/solr.ini"
sudo sh -c "echo 'extension=solr.so' > /etc/php5/cli/conf.d/solr.ini"

=== OSX using macports ===

sudo port install apache-solr4
sudo port install php54-solr

=== OSX using homebrew ===

brew install homebrew/php/php56-solr

=== Windows ===

Install the pecl package as usual. Sorry it has not been tested yet.

== Solr server ==

Moodle 3.1 supports Solr server from 4.0 onwards, although you can only use the Solr schema setup script that we provide with Moodle from Solr 5. The latest Solr 5 available version is the recommended one, same applicable to Solr 6 once it is released.

The following example snippet (feel free to copy & paste into a .sh script with execution permissions) will download Solr 5.4.1 (replace it with latest 5.x) in the current directory, start the solr server and create an index in it named '''moodle''' to add moodle data to it.

#!/bin/bash
set -e
SOLRVERSION=5.4.1
SOLRNAME=solr-$SOLRVERSION
SOLRTAR=$SOLRNAME'.tgz'
INDEXNAME=moodle
if [ -d $SOLRNAME ]; then
echo "Error: Directory $SOLRNAME already exists, remove it before starting the setup again."
exit 1
fi
if [ ! -f $SOLRTAR ]; then
wget http://apache.mirror.digitalpacific.com.au/lucene/solr/$SOLRVERSION/$SOLRTAR
fi
tar -xvzf $SOLRTAR
cd $SOLRNAME
bin/solr start
bin/solr create -c $INDEXNAME
# After setting it up and creating the index use:
# - "/yourdirectory/solrdir/bin/solr start" from CLI to start the server
# - "/yourdirectory/solrdir/bin/solr stop" from CLI to stop the server.

= Setup =

# Go to '''Site administration -> Plugins -> Search -> Manage global search'''
# Follow '''Search setup''' steps to complete the setup process. Basically you have to:
## Enable global search
## Set '''Solr''' as search engine and tick all search areas checkboxes
## Go to '''Site administration -> Plugins -> Search -> Solr''' and set '''Host name''' to localhost, '''Port''' to 8983 and '''Index name''' to 'moodle' (the name of the index in Solr)

== Solr 4 schema setup ==

As mentioned above you can not use the schema setup script when using a Solr 4 server. Here you can find the field types description below in case you really want to use Solr 4.x branch.

Extracted from search/classes/document.php

{| class="nicetable"
|-
! Field name
! Field type
! Stored
! Indexed
! Query field
|-
| id
| org.apache.solr.schema.StrField
| true
| false
| false
|-
| itemid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| title
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| content
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| contextid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| areaid
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| type
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| courseid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| owneruserid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| modified
| org.apache.solr.schema.TrieDateField
| true
| true
| false
|-
| userid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| description1
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| description2
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| solr_filegroupingid
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| solr_fileid
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| solr_filecontenthash
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| solr_fileindexstatus
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| solr_filecontent
| org.apache.solr.schema.TextField
| false
| true
| true
|}

== SSL Setup ==

If you are using Solr with SSL encryption, you will need to configure Moodle as such.

# You will need a separate key file and cacert file, both in pem format, located on your server Moodle, and readable by the PHP process.
# Go to ''Site administration > Plugins > Search > Solr''
# Set '''Secure mode''' to Yes
# '''SSL certificate''' to /path/to/certs/solr-ssl.cacert.pem
# '''SSL key''' to /path/to/certs/solr-ssl.key.pem
# '''SSL key Password''' to The password used to lock the SSL Key
# '''SSL CA certificates name''' to /path/to/certs/solr-ssl.cacert.pem
# Save
# On the search management page it should indicate it can connect to Solr.

= Indexing =

Once global search is enabled a new task will be running through cron, although you can force documents indexing by:

# Going to '''Reports -> Global search info'''
# Tick '''Index all site contents''' and press '''Execute'''

or

* Executing the following task from CLI

php admin/tool/task/cli/schedule_task.php --execute="\\core\\task\\search_index_task"

= Querying =

# Hover the search icon in the navigation bar, type your query and press '''Enter'''

or

# Add '''Global search''' block somewhere
# Type your query and press '''Search'''

Global search

2016-05-12T13:32:10Z

Emerrill: Add information about encrypting Solr connection

= Installation =

To use Solr as Moodle's search engine you need the PHP Solr extension and a Solr server.

== PHP Solr extension ==

You need PHP Solr extension installed. You can download the official latest versions from [http://pecl.php.net/package/solr](http://pecl.php.net/package/solr) The minimum required version is PECL Solr 2.1 for PHP 5 branch and PECL Solr 2.4 for PHP 7 branch.

Basic installation steps (using apache web server):

=== Linux (Debian/Ubuntu) ===

sudo apt-get install libpcre3-dev libxml2-dev libcurl4-openssl-dev
sudo apt-get install php5-dev
sudo apt-get install php-pear
sudo pecl install solr
sudo service apache2 restart
sudo sh -c "echo 'extension=solr.so' > /etc/php5/apache2/conf.d/solr.ini"
sudo sh -c "echo 'extension=solr.so' > /etc/php5/cli/conf.d/solr.ini"

=== OSX using macports ===

sudo port install apache-solr4
sudo port install php54-solr

=== OSX using homebrew ===

brew install homebrew/php/php56-solr

=== Windows ===

Install the pecl package as usual. Sorry it has not been tested yet.

== Solr server ==

Moodle 3.1 supports Solr server from 4.0 onwards, although you can only use the Solr schema setup script that we provide with Moodle from Solr 5. The latest Solr 5 available version is the recommended one, same applicable to Solr 6 once it is released.

The following example snippet (feel free to copy & paste into a .sh script with execution permissions) will download Solr 5.4.1 (replace it with latest 5.x) in the current directory, start the solr server and create an index in it named '''moodle''' to add moodle data to it.

#!/bin/bash
set -e
SOLRVERSION=5.4.1
SOLRNAME=solr-$SOLRVERSION
SOLRTAR=$SOLRNAME'.tgz'
INDEXNAME=moodle
if [ -d $SOLRNAME ]; then
echo "Error: Directory $SOLRNAME already exists, remove it before starting the setup again."
exit 1
fi
if [ ! -f $SOLRTAR ]; then
wget http://apache.mirror.digitalpacific.com.au/lucene/solr/$SOLRVERSION/$SOLRTAR
fi
tar -xvzf $SOLRTAR
cd $SOLRNAME
bin/solr start
bin/solr create -c $INDEXNAME
# After setting it up and creating the index use:
# - "/yourdirectory/solrdir/bin/solr start" from CLI to start the server
# - "/yourdirectory/solrdir/bin/solr stop" from CLI to stop the server.

= Setup =

# Go to '''Site administration -> Plugins -> Search -> Manage global search'''
# Follow '''Search setup''' steps to complete the setup process. Basically you have to:
## Enable global search
## Set '''Solr''' as search engine and tick all search areas checkboxes
## Go to '''Site administration -> Plugins -> Search -> Solr''' and set '''Host name''' to localhost, '''Port''' to 8983 and '''Index name''' to 'moodle' (the name of the index in Solr)

== Solr 4 schema setup ==

As mentioned above you can not use the schema setup script when using a Solr 4 server. Here you can find the field types description below in case you really want to use Solr 4.x branch.

Extracted from search/classes/document.php

{| class="nicetable"
|-
! Field name
! Field type
! Stored
! Indexed
! Query field
|-
| id
| org.apache.solr.schema.StrField
| true
| false
| false
|-
| itemid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| title
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| content
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| contextid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| areaid
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| type
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| courseid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| owneruserid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| modified
| org.apache.solr.schema.TrieDateField
| true
| true
| false
|-
| userid
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| description1
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| description2
| org.apache.solr.schema.TextField
| true
| true
| true
|-
| solr_filegroupingid
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| solr_fileid
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| solr_filecontenthash
| org.apache.solr.schema.StrField
| true
| true
| false
|-
| solr_fileindexstatus
| org.apache.solr.schema.TrieIntField
| true
| true
| false
|-
| solr_filecontent
| org.apache.solr.schema.TextField
| false
| true
| true
|}

== SSL Setup ==

If you are using Solr with SSL encryption, you will need to configure Moodle as such.

# You will need a separate key file and cacert file, both in pem format, located on your server Moodle, and readable by the PHP process.
# In the Moodle Solr config page:
## Enable Secure
## SSL certificate: /path/to/certs/solr-ssl.cacert.pem
## SSL key: /path/to/certs/solr-ssl.key.pem
## SSL key Password: The password used to lock the SSL Key
## SSL CA certificates name: /path/to/certs/solr-ssl.cacert.pem
# Save
# On the search management page it still indicates it can connect to Solr.

= Indexing =

Once global search is enabled a new task will be running through cron, although you can force documents indexing by:

# Going to '''Reports -> Global search info'''
# Tick '''Index all site contents''' and press '''Execute'''

or

* Executing the following task from CLI

php admin/tool/task/cli/schedule_task.php --execute="\\core\\task\\search_index_task"

= Querying =

# Hover the search icon in the navigation bar, type your query and press '''Enter'''

or

# Add '''Global search''' block somewhere
# Type your query and press '''Search'''

Search engines

2016-05-12T13:21:53Z

Emerrill: /* Retrieve contents */ Update limit discussion

{{Search engine plugins}}
== Introduction ==

Search engines index big amounts of data in a structured way that allow users to query them and extract relevant data. There are many search engines with nice APIs to set data on and retrieve data from. We made Moodle's global search pluggable so different backends can be used, from a simple database table (ok for small sites but unusable for big sites) to open sourced systems like solr or elasticsearch (on top of Apache Lucene) or proprietary cloud based systems.

== Terms ==

'''Index''': You know what it means, but in this page we use '''index''' as the data container in your search engine. It can be an instance in your search engine server or a database table name if you are writing a search engine for mongodb (just an example)
'''Document''': A "searchable" unit of data like a database entry, a forum post... You can see it as one of the search results you might expect to get returned by a search engine.

== Writing your own search engine plugin ==

To write your own search engine you need to code methods to set, retrieve and delete data from your search engine. You will need to add a '''\search_yourplugin\engine''' class in '''search/engine/yourplugin/classes/engine.php''' extending '''\core_search\engine'''.

=== Search engine setup ===

Your search engine needs to be prepared to index data, you can have a script for your plugin users so they can easily create the required structure the search engine. Otherwise add instructions about how to do it.

You can get the list of fields Moodle needs along with some other info you might need like the field types calling '''\core_search\document::get_default_fields_definition()'''

=== Add contents ===

This method is executed when Moodle contents are being indexed in the search engine. Moodle iterates through all search areas extracting which contents should be indexed and assigns them a unique id based on the search area.
<code php>
public function add_document(array $doc, $fileindexing = false) {
// Use curl or any other method or extension to push the document to your search engine.
}
</code>

'''$doc''' will contain a document data with all required fields (+ maybe some optionals) and its contents will be already validated so a integer field will come with an integer value...
'''$fileindexing''' will be true if file indexing if files should be indexed. Will be false if your plugin does not support file indexing

=== Retrieve contents ===

This is the key method, as search engine plugins have a lot of flexibility here.

You will get the search filters the user specified and the list of contexts the user can access and this function should return an array of \core_search\document objects.

<code php>
public function execute_query($filters, $usercontexts, $limit = 0) {
// Prepare a query applyting all filters.
// Include $usercontexts as a filter to contextid field.
// Send a request to the server.
// Iterate through results.
// Check user access, read https://docs.moodle.org/dev/Search_engines#Security for more info
// Convert results to '''\core_search\document''' type objects using '''\core_search\document::set_data_from_engine'''
// Return an array of '''\core_search\document''' objects, limiting to $limit or \core_search\manager::MAX_RESULTS if empty.
}
</code>

==== Security ====

It is crucial that this function is checking '''\core_search\document::check_access''' results and do not return results where the user do not have access. Moodle already performs part of the required security checkings, but search areas always have the last word and it should be respected.

==== Getting enough results ====

Because in some cases many records may fail check_access(), engines should make provisions to make sure enough a full set of documents is returned, even if it must check many more documents. See MDL-53758 for a better discussion of this.

=== Record counts ===
get_query_total_count() must be implemented to return the number of results that available for the most recent call to execute_query(). This is used to determine how many pages will be displayed in the paging bar. For more discussion see MDL-53758.

<code php>
public function get_query_total_count() {
// Return an approximate count of total records for the most recently completed execute_query().
}
</code>

The value can be an estimate. The search manager will ensure that if a page is requested that is beyond the last page of actual results, the user will seamlessly see the last available page.

There are a number of ways to determine what value to return from get_query_total_count(). Note that if the method you choose requires you to process more than $limit valid documents, you still must only return $limit records from execute_query(). Some of the ways to do this are:

==== Return how many possible there are ====
This would mean how many results we have processed and passed (using check_access()), plus any candidate results that are left. Alternately it is the total count of records for the query, minus the ones we have rejected so far. search_solr uses this method.

'''User experience:''' User sees a full compliment of pages. If the pass-to-fail ration on check_access() is very high (and we generally expect it to be), then the number of pages should generally be accurate. This method will always error on the high side. It is possible that when clicking on a higher page there will be no results available, so the search manager will seamlessly show them the last actual page with actual results.

'''Pros:''' Free or very cheap with some engines - no need to check access/process records beyond the current page. Reasonable user experience.

'''Cons:''' Future page count is not perfect, so can result in page not being available when clicked (but the manager mitigates this).

==== Return the current count plus 1 ====
In this case, you would calculate all the records through $limit plus one. If the plus one exists, you would return that count, otherwise you would return the actual count.

'''User experience:''' User would only see up to the current page, plus one more, except when on the last page of results. Gmail search works similar to this in the way you can only navigate to the next page of results, not an arbitrary page.

'''Pros:''' Relatively cheap. Reasonable user experience.

'''Cons:''' User can’t jump to an arbitrary page even if they know what page a particular result is on

==== Calculate all results up to MAX_RESULTS ====
This would mean calculating the full set of results up to MAX_RESULTS, and returning the actual count of results.
'''User experience:''' The user will see the exact number of pages they should

'''Pros:''' cleanest user experience

'''Cons:''' Very expensive, as you are calculating up to MAX_RESULTS results on every page, even if you are only showing the first page

==== Just return MAX_RESULTS ====
'''User experience:''' User will always see 10 pages, except when they are on the last page of actual results.

'''Pros:''' Free

'''Cons:''' Worst user experience

=== Delete contents ===

<code php>
public function delete($areaid = false) {
if ($areaid === false) {
// Delete all your search engine index contents.
} else {
// Delete all your search engine contents where areaid = $areaid.
}
}
</code>

'''\core_search\document::check_access''' will return \core_search\manager::ACCESS_DELETED if a document returned from the search engine is not available in Moodle any more, you can use this to clean up the search engine contents with some kind of '''\search_yourplugin\engine::delete_by_id''' method. You can look at '''search/engine/solr/classes/engine.php''' '''execute_query''' method for an example of this.

=== Other abstract methods you need to overwrite ===

<code php>
public function file_indexing_enabled() {
// Defaults to false, overwrite it if your search engine supports file indexing.
return false;
}
</code>

<code php>
public function is_server_ready() {
// Check if your search engine is ready.
}
</code>

=== Other methods you might be interested in overwriting ===

<code php>
public function is_installed() {
// Check if the required PHP extensions you need to make the search engine work are installed.
}
</code>

<code php>
public function optimize() {
// Optimize or defragment the index contents.
}
</code>

These methods are called while the indexing process is running and allow search engine to hook the indexing process.

<code php>
public function index_starting($fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function index_complete($numdocs = 0, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_starting($searcharea, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_complete($searcharea, $numdocs = 0, $fullindex = false) {
return true;
}
</code>

== Adapting document formats to your search engine format ==

'''\core_search\document''' is the class that represents a document, depending on your search engine backend limitations or on how it stores time values you might be interested in overwriting this class in '''\search_yourplugin\document'''. The main functions you might be interested in overwriting are:

==== Format date/time fields ====

<code php>
public static function format_time_for_engine($timestamp) {
// Convert $timestamp to a string using the format used by your search engine.
}
</code>

By default, '''\core_search\document::format_time_for_engine''' returns a timestamp (integer).

==== Import date/time contents from the search engine ====

<code php>
public static function import_time_from_engine($time) {
// Convert the string returned from the search engine as a date/time format to a timestamp (integer).
}
</code>

By default, '''\core_search\document::import_time_from_engine''' returns a timestamp (integer).

==== Format string fields ====

<code php>
public static function format_string_for_engine() {
// Limit the string length, convert iconv if your search engine only supports an specific charset...
}
</code>

By default, '''\core_search\document::format_string_for_engine''' returns the string as it is.

[[Category:Search]]
[[Category:Plugins]]

Search engines

2016-05-12T13:08:33Z

Emerrill: Formatting update, info from MDL-53758

{{Search engine plugins}}
== Introduction ==

Search engines index big amounts of data in a structured way that allow users to query them and extract relevant data. There are many search engines with nice APIs to set data on and retrieve data from. We made Moodle's global search pluggable so different backends can be used, from a simple database table (ok for small sites but unusable for big sites) to open sourced systems like solr or elasticsearch (on top of Apache Lucene) or proprietary cloud based systems.

== Terms ==

'''Index''': You know what it means, but in this page we use '''index''' as the data container in your search engine. It can be an instance in your search engine server or a database table name if you are writing a search engine for mongodb (just an example)
'''Document''': A "searchable" unit of data like a database entry, a forum post... You can see it as one of the search results you might expect to get returned by a search engine.

== Writing your own search engine plugin ==

To write your own search engine you need to code methods to set, retrieve and delete data from your search engine. You will need to add a '''\search_yourplugin\engine''' class in '''search/engine/yourplugin/classes/engine.php''' extending '''\core_search\engine'''.

=== Search engine setup ===

Your search engine needs to be prepared to index data, you can have a script for your plugin users so they can easily create the required structure the search engine. Otherwise add instructions about how to do it.

You can get the list of fields Moodle needs along with some other info you might need like the field types calling '''\core_search\document::get_default_fields_definition()'''

=== Add contents ===

This method is executed when Moodle contents are being indexed in the search engine. Moodle iterates through all search areas extracting which contents should be indexed and assigns them a unique id based on the search area.
<code php>
public function add_document(array $doc, $fileindexing = false) {
// Use curl or any other method or extension to push the document to your search engine.
}
</code>

'''$doc''' will contain a document data with all required fields (+ maybe some optionals) and its contents will be already validated so a integer field will come with an integer value...
'''$fileindexing''' will be true if file indexing if files should be indexed. Will be false if your plugin does not support file indexing

=== Retrieve contents ===

This is the key method, as search engine plugins have a lot of flexibility here.

You will get the search filters the user specified and the list of contexts the user can access and this function should return an array of \core_search\document objects.

<code php>
public function execute_query($filters, $usercontexts, $limit = 0) {
// Prepare a query applyting all filters.
// Include $usercontexts as a filter to contextid field.
// Send a request to the server.
// Iterate through results (respecting $limit or \core_search\manager::MAX_RESULTS if empty).
// Check user access, read https://docs.moodle.org/dev/Search_engines#Security for more info
// Convert results to '''\core_search\document''' type objects using '''\core_search\document::set_data_from_engine'''
// Return an array of '''\core_search\document''' objects.
}
</code>

==== Security ====

It is crucial that this function is checking '''\core_search\document::check_access''' results and do not return results where the user do not have access. Moodle already performs part of the required security checkings, but search areas always have the last word and it should be respected.

==== Getting enough results ====

Because in some cases many records may fail check_access(), engines should make provisions to make sure enough a full set of documents is returned, even if it must check many more documents. See MDL-53758 for a better discussion of this.

=== Record counts ===
get_query_total_count() must be implemented to return the number of results that available for the most recent call to execute_query(). This is used to determine how many pages will be displayed in the paging bar. For more discussion see MDL-53758.

<code php>
public function get_query_total_count() {
// Return an approximate count of total records for the most recently completed execute_query().
}
</code>

The value can be an estimate. The search manager will ensure that if a page is requested that is beyond the last page of actual results, the user will seamlessly see the last available page.

There are a number of ways to determine what value to return from get_query_total_count(). Note that if the method you choose requires you to process more than $limit valid documents, you still must only return $limit records from execute_query(). Some of the ways to do this are:

==== Return how many possible there are ====
This would mean how many results we have processed and passed (using check_access()), plus any candidate results that are left. Alternately it is the total count of records for the query, minus the ones we have rejected so far. search_solr uses this method.

'''User experience:''' User sees a full compliment of pages. If the pass-to-fail ration on check_access() is very high (and we generally expect it to be), then the number of pages should generally be accurate. This method will always error on the high side. It is possible that when clicking on a higher page there will be no results available, so the search manager will seamlessly show them the last actual page with actual results.

'''Pros:''' Free or very cheap with some engines - no need to check access/process records beyond the current page. Reasonable user experience.

'''Cons:''' Future page count is not perfect, so can result in page not being available when clicked (but the manager mitigates this).

==== Return the current count plus 1 ====
In this case, you would calculate all the records through $limit plus one. If the plus one exists, you would return that count, otherwise you would return the actual count.

'''User experience:''' User would only see up to the current page, plus one more, except when on the last page of results. Gmail search works similar to this in the way you can only navigate to the next page of results, not an arbitrary page.

'''Pros:''' Relatively cheap. Reasonable user experience.

'''Cons:''' User can’t jump to an arbitrary page even if they know what page a particular result is on

==== Calculate all results up to MAX_RESULTS ====
This would mean calculating the full set of results up to MAX_RESULTS, and returning the actual count of results.
'''User experience:''' The user will see the exact number of pages they should

'''Pros:''' cleanest user experience

'''Cons:''' Very expensive, as you are calculating up to MAX_RESULTS results on every page, even if you are only showing the first page

==== Just return MAX_RESULTS ====
'''User experience:''' User will always see 10 pages, except when they are on the last page of actual results.

'''Pros:''' Free

'''Cons:''' Worst user experience

=== Delete contents ===

<code php>
public function delete($areaid = false) {
if ($areaid === false) {
// Delete all your search engine index contents.
} else {
// Delete all your search engine contents where areaid = $areaid.
}
}
</code>

'''\core_search\document::check_access''' will return \core_search\manager::ACCESS_DELETED if a document returned from the search engine is not available in Moodle any more, you can use this to clean up the search engine contents with some kind of '''\search_yourplugin\engine::delete_by_id''' method. You can look at '''search/engine/solr/classes/engine.php''' '''execute_query''' method for an example of this.

=== Other abstract methods you need to overwrite ===

<code php>
public function file_indexing_enabled() {
// Defaults to false, overwrite it if your search engine supports file indexing.
return false;
}
</code>

<code php>
public function is_server_ready() {
// Check if your search engine is ready.
}
</code>

=== Other methods you might be interested in overwriting ===

<code php>
public function is_installed() {
// Check if the required PHP extensions you need to make the search engine work are installed.
}
</code>

<code php>
public function optimize() {
// Optimize or defragment the index contents.
}
</code>

These methods are called while the indexing process is running and allow search engine to hook the indexing process.

<code php>
public function index_starting($fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function index_complete($numdocs = 0, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_starting($searcharea, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_complete($searcharea, $numdocs = 0, $fullindex = false) {
return true;
}
</code>

== Adapting document formats to your search engine format ==

'''\core_search\document''' is the class that represents a document, depending on your search engine backend limitations or on how it stores time values you might be interested in overwriting this class in '''\search_yourplugin\document'''. The main functions you might be interested in overwriting are:

==== Format date/time fields ====

<code php>
public static function format_time_for_engine($timestamp) {
// Convert $timestamp to a string using the format used by your search engine.
}
</code>

By default, '''\core_search\document::format_time_for_engine''' returns a timestamp (integer).

==== Import date/time contents from the search engine ====

<code php>
public static function import_time_from_engine($time) {
// Convert the string returned from the search engine as a date/time format to a timestamp (integer).
}
</code>

By default, '''\core_search\document::import_time_from_engine''' returns a timestamp (integer).

==== Format string fields ====

<code php>
public static function format_string_for_engine() {
// Limit the string length, convert iconv if your search engine only supports an specific charset...
}
</code>

By default, '''\core_search\document::format_string_for_engine''' returns the string as it is.

[[Category:Search]]
[[Category:Plugins]]

Search engines

2016-05-12T01:42:17Z

Emerrill: Add details about get_query_total_count()

{{Search engine plugins}}
== Introduction ==

Search engines index big amounts of data in a structured way that allow users to query them and extract relevant data. There are many search engines with nice APIs to set data on and retrieve data from. We made Moodle's global search pluggable so different backends can be used, from a simple database table (ok for small sites but unusable for big sites) to open sourced systems like solr or elasticsearch (on top of Apache Lucene) or proprietary cloud based systems.

== Terms ==

'''Index''': You know what it means, but in this page we use '''index''' as the data container in your search engine. It can be an instance in your search engine server or a database table name if you are writing a search engine for mongodb (just an example)
'''Document''': A "searchable" unit of data like a database entry, a forum post... You can see it as one of the search results you might expect to get returned by a search engine.

== Writing your own search engine plugin ==

To write your own search engine you need to code methods to set, retrieve and delete data from your search engine. You will need to add a '''\search_yourplugin\engine''' class in '''search/engine/yourplugin/classes/engine.php''' extending '''\core_search\engine'''.

=== Search engine setup ===

Your search engine needs to be prepared to index data, you can have a script for your plugin users so they can easily create the required structure the search engine. Otherwise add instructions about how to do it.

You can get the list of fields Moodle needs along with some other info you might need like the field types calling '''\core_search\document::get_default_fields_definition()'''

=== Add contents ===

This method is executed when Moodle contents are being indexed in the search engine. Moodle iterates through all search areas extracting which contents should be indexed and assigns them a unique id based on the search area.
<code php>
public function add_document(array $doc, $fileindexing = false) {
// Use curl or any other method or extension to push the document to your search engine.
}
</code>

'''$doc''' will contain a document data with all required fields (+ maybe some optionals) and its contents will be already validated so a integer field will come with an integer value...
'''$fileindexing''' will be true if file indexing if files should be indexed. Will be false if your plugin does not support file indexing

=== Retrieve contents ===

This is the key method, as search engine plugins have a lot of flexibility here.

You will get the search filters the user specified and the list of contexts the user can access and this function should return an array of \core_search\document objects.

<code php>
public function execute_query($filters, $usercontexts, $limit = 0) {
// Prepare a query applyting all filters.
// Include $usercontexts as a filter to contextid field.
// Send a request to the server.
// Iterate through results (respecting $limit or \core_search\manager::MAX_RESULTS if empty).
// Check user access, read https://docs.moodle.org/dev/Search_engines#Security for more info
// Convert results to '''\core_search\document''' type objects using '''\core_search\document::set_data_from_engine'''
// Return an array of '''\core_search\document''' objects.
}
</code>

=== Record counts ===
get_query_total_count() must be implemented to return the number of results that available for the most recent call to execute_query(). This is used to determine how many pages will be displayed in the paging bar.

<code php>
public function get_query_total_count() {
// Return an approximate count of total records for the most recently completed execute_query().
}
</code>

The value can be an estimate. The search manager will ensure that if a page is requested that is beyond the last page of actual results, the user will seamlessly see the last available page.

There are a number of ways to determine what value to return from get_query_total_count(). Note that if the method you choose requires you to process more than $limit valid documents, you still must only return $limit records from execute_query(). Some of the ways to do this are:

==== Return how many possible there are ====
This would mean how many results we have processed and passed (using check_access()), plus any candidate results that are left. Alternately it is the total count of records for the query, minus the ones we have rejected so far. search_solr uses this method.

'''User experience:''' User sees a full compliment of pages. If the pass-to-fail ration on check_access() is very high (and we generally expect it to be), then the number of pages should generally be accurate. This method will always error on the high side. It is possible that when clicking on a higher page there will be no results available, so the search manager will seamlessly show them the last actual page with actual results.

'''Pros:''' Free or very cheap with some engines - no need to check access/process records beyond the current page. Reasonable user experience.

'''Cons:''' Future page count is not perfect, so can result in page not being available when clicked (but the manager mitigates this).

==== Return the current count plus 1 ====
In this case, you would calculate all the records through $limit plus one. If the plus one exists, you would return that count, otherwise you would return the actual count.

'''User experience:''' User would only see up to the current page, plus one more, except when on the last page of results. Gmail search works similar to this in the way you can only navigate to the next page of results, not an arbitrary page.

'''Pros:''' Relatively cheap. Reasonable user experience.

'''Cons:''' User can’t jump to an arbitrary page even if they know what page a particular result is on

==== Calculate all results up to MAX_RESULTS ====
This would mean calculating the full set of results up to MAX_RESULTS, and returning the actual count of results.
'''User experience:''' The user will see the exact number of pages they should
'''Pros:''' cleanest user experience
'''Cons:''' Very expensive, as you are calculating up to MAX_RESULTS results on every page, even if you are only showing the first page

==== Just return MAX_RESULTS ====
'''User experience:''' User will always see 10 pages, except when they are on the last page of actual results.
'''Pros:''' Free
'''Cons:''' Worst user experience

=== Security ===

It is crucial that this function is checking '''\core_search\document::check_access''' results and do not return results where the user do not have access. Moodle already performs part of the required security checkings, but search areas always have the last word and it should be respected.

=== Delete contents ===

<code php>
public function delete($areaid = false) {
if ($areaid === false) {
// Delete all your search engine index contents.
} else {
// Delete all your search engine contents where areaid = $areaid.
}
}
</code>

'''\core_search\document::check_access''' will return \core_search\manager::ACCESS_DELETED if a document returned from the search engine is not available in Moodle any more, you can use this to clean up the search engine contents with some kind of '''\search_yourplugin\engine::delete_by_id''' method. You can look at '''search/engine/solr/classes/engine.php''' '''execute_query''' method for an example of this.

=== Other abstract methods you need to overwrite ===

<code php>
public function file_indexing_enabled() {
// Defaults to false, overwrite it if your search engine supports file indexing.
return false;
}
</code>

<code php>
public function is_server_ready() {
// Check if your search engine is ready.
}
</code>

=== Other methods you might be interested in overwriting ===

<code php>
public function is_installed() {
// Check if the required PHP extensions you need to make the search engine work are installed.
}
</code>

<code php>
public function optimize() {
// Optimize or defragment the index contents.
}
</code>

These methods are called while the indexing process is running and allow search engine to hook the indexing process.

<code php>
public function index_starting($fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function index_complete($numdocs = 0, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_starting($searcharea, $fullindex = false) {
// Nothing by default.
}
</code>

<code php>
public function area_index_complete($searcharea, $numdocs = 0, $fullindex = false) {
return true;
}
</code>

== Adapting document formats to your search engine format ==

'''\core_search\document''' is the class that represents a document, depending on your search engine backend limitations or on how it stores time values you might be interested in overwriting this class in '''\search_yourplugin\document'''. The main functions you might be interested in overwriting are:

==== Format date/time fields ====

<code php>
public static function format_time_for_engine($timestamp) {
// Convert $timestamp to a string using the format used by your search engine.
}
</code>

By default, '''\core_search\document::format_time_for_engine''' returns a timestamp (integer).

==== Import date/time contents from the search engine ====

<code php>
public static function import_time_from_engine($time) {
// Convert the string returned from the search engine as a date/time format to a timestamp (integer).
}
</code>

By default, '''\core_search\document::import_time_from_engine''' returns a timestamp (integer).

==== Format string fields ====

<code php>
public static function format_string_for_engine() {
// Limit the string length, convert iconv if your search engine only supports an specific charset...
}
</code>

By default, '''\core_search\document::format_string_for_engine''' returns the string as it is.

[[Category:Search]]
[[Category:Plugins]]

Search engines

2016-05-11T06:49:58Z

Emerrill: Add limit to execute_query

Common unit test problems

2016-03-30T13:29:36Z

Emerrill: /* core_phpunit_advanced_testcase::test_locale_reset */ Marking which one works for Debian

== General Issues ==

=== Segfaults on Oracle ===

When I was running tests on oracle I was getting phpunit sefaulting.. --[[User:Dan Poltawski|Dan Poltawski]] 00:29, 16 May 2012 (WST)

'''Solution''' Set statement_cache_size in php.ini: <code>oci8.statement_cache_size = 0</code>

(More info: [https://bugs.php.net/bug.php?id=49803 PHP Bug #49803]).

=== Execution ends with "zend_mm_heap corrupted" error ===

This was happening with a standard XAMPP stack, running Moodle against Oracle.

# Verify that you are not using multiple PHP opcode accelerators together (APC, Opcode...). Also try disabling all them (they really don't help much in a phpunit execution).
# Set output_buffering in php.ini to 65536 (from default 4096).

=== Many random errors about "Warning: rmdir dataroot/cache/.../.... Directory not empty" ===

Use a different $CFG->phpunit_dataroot , completely apart from your current [LXMW]AMP stack, for example in windows 'C:\\Windows\\Temp\\dataroot'. For some reason, unknown at the time of writing this, using any directory within the [LXMW]AMP stack lead to randomly busy/locked (aka, non deletable) files.

== Specific failures ==

=== dml_testcase::test_unique_index_collation_trouble===

<code>Unique index is accent insensitive, this may cause problems for non-ascii languages. This is usually caused by accent insensitive default collation.</code>

'''Solution''' These tests should pass if you use the <code>utf8_bin</code> collation on your database for unit tests, but we recommend <code>utf8_unicode_ci</code> for actual live Moodle sites. Work is being done to resolve this issue, read more about the [[Database collation issue]] for further info.

=== dml_testcase::test_sql_binary_equal ===

<code>SQL operator "=" is expected to be case sensitive Failed asserting that 1 matches expected 2.</code>

'''Solution''' These tests should pass if you use the <code>utf8_bin</code> collation on your database for unit tests, but we recommend <code>utf8_unicode_ci</code> for actual live Moodle sites. Work is being done to resolve this issue, read more about the [[Database collation issue]] for further info.

=== grading_manager_testcase::test_tokenize===

<code>A test using UTF-8 characters has failed. Consider updating PHP and PHP's PCRE or INTL extensions (MDL-30494) Failed asserting that false is true.</code>

'''Solution''' These tests should pass if you use the <code>utf8_bin</code> collation on your database for unit tests, but we recommend <code>utf8_unicode_ci</code> for actual live Moodle sites. Work is being done to resolve this issue, read more about the [[Database collation issue]] for further info.

=== moodlesimplepie_testcase::test_getfeed ===

<code>Failed to load the sample RSS file. Please check your proxy settings in Moodle. %s</code>

'''Solution''' Your moodle needs network connectivity, please check proxy settings.

=== moodlesimplepie_testcase::test_redirect ===

<code>Failed asserting that 'cURL Error: Operation timed out after 2000 milliseconds with 0 bytes received' is null.</code>

'''Solution''' Your moodle needs network connectivity, please check proxy settings

=== collatorlib_testcase::test_asort_objects_by_method ===

<code>Collation aware sorting not supported, PHP extension "intl" is not available.</code>

'''Solution''' Install php intl extension.

Note that, on Windows, this extension does not seem to be included in the installer, but you can get it by downloading the zip, and copying the right DLLs across. If you Google, there are more detailed instructions on Stack Exchange.

=== moodlelib_testcase::test_fix_utf8 ===

<code>Failed asserting that false is identical to 'aaabbb'.</code>

'''Solution''' This problem indicates buggy iconv. See [http://tracker.moodle.org/browse/MDL-33007] for discussion. So this is a real problem, to be fixed in a future integration cycle

=== filestoragelib_testcase::test_get_file_preview ===

<code>Failed asserting that false is an instance of class "stored_file".</code>

'''Solution''' Unfortunately, the php GD extension is a requirement for this test (see MDL-36447).

Go to your Moodle directory and type <code>php admin/tool/phpunit/cli/util.php --drop</code>, then reinitialise PHPunit and run the test again.

===core_ddl_testcase::test_row_size_limits===

<code>Row size limit reached in MySQL using InnoDB, configure server to use innodb_file_format=Barracuda and innodb_file_per_table=1</code>

""Solution"" default InnoDB database tables in MySQL cannot handle more than 10 text columns, so innodb file format should be Barracuda (see MDL-46971)

Running <code>php admin/cli/mysql_compressed_rows.php</code> will solve the problem.

=== core_phpunit_advanced_testcase::test_locale_reset ===

Failed asserting that two strings are identical. Since 2.9, en_AU.UTF-8 locale is required to run phpunit.

'''Solution''' Install the AU locale on your server if you want to run phpunit. Here are sample commands for installing the en_AU locale:

* Debian/Centos: "sudo localedef -v -c -i en_AU -f UTF-8 en_AU.UTF-8"
* Ubuntu: "sudo locale-gen en_AU.UTF-8"

=== MSSQL failures with core_course_externallib_testcase===

On the MSSQL database driver, some problems occur with core_course_externallib_testcase, for example:

core_course_externallib_testcase::test_duplicate_course

unserialize(): Error at offset 24191 of 24192 bytes

'''Solution''' Ensure that the correct configuration is set in freedts.conf (from https://docs.moodle.org/26/en/FreeTDS), e.g.

<pre>text size = 20971520
client charset = UTF8</pre>

=== PHP Warning: include_once(PHPUnit/Extensions/Database/Autoload.php): failed to open stream ===

This occurs on Mac installs from experience. The reason this occurs is because DBUnit was not installed during the PHPUnit installation via PEAR.

'''Solution''' In terminal type: <code>sudo pear install -f phpunit/DbUnit</code>

=== !!! Error reading from database !!!!! Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier. ===

If running unit tests under FreeTDS, remember that without a valid FREETDS environment variable, PHP won't be able to find the freetds.conf file and will default to version 5.0 which has poor support for unicode collations.

'''Solution''' Ensure a FREETDS environment variable is set prior to running the automated tests, which points to a valid path that contains a freetds.conf file. Also ensure the tds version element is set to a recent enough version (8.0)

'''Solution2''' Under windows you can put the freetds.conf file in the disk root directory where php is being executed (for example C:\freetds.conf). That directory is always looked. Also ensure the tds version element is set to a recent enough version (8.0)

Note: Another potential solution may be to set TDSVER (http://freetds.schemamania.org/userguide/freetdsconf.htm)

[[Category:Unit testing]]

=== Errors running unit tests against Oracle, related with locales, decimal points and friends ===

Surely your PHP CLI (the one executing phpunit) is not aware of the expected Oracle NLS configuration. To enforce it, set at least these 2 env variables in your system (globally or for the current user):

- NLS_LANG to AMERICAN_AMERICA.AL32UTF8
- NLS_NUMERIC_CHARACTERS to ., (dot & comma)

=== The test file "evolution.test" should not contain section named "[lots of content]" ===

Likely that you've got git setting autocrlf set to true and its altered the line endings. Set autocrlf to false in your git config and reset your checkout following [https://help.github.com/articles/dealing-with-line-endings/#refreshing-a-repository-after-changing-line-endings this guide].

User:Eric Merrill/gradereports

2015-07-13T21:26:41Z

Emerrill:

== The problem ==
Right now, grades that need to be computed for display in reports are handled in multiple ways and in multiple locations. Reports get grade_grade::get_hiding_affected() and then each report uses it in a different way. Leading to different and inconsistent displays.

== Proposal ==
I am proposing moving the computation layer deeper into the API, so that all computations are done at the same point in the code.
New class *grade_report_grade*. This would be a sub-class grade_grade, but would represent the computed grade for display. You would specify when it is "computed" what the re-computation behavior, and the user visibility behavior is.

Possible methods:
* static compute_report_grades() - would recursively compute grade_report_grades based on a passed node, or user/courseid
* user_visible() - Should the item be visible to the user

User:Eric Merrill/gradereports

2015-07-13T21:18:25Z

Emerrill: Created page with "Test"

Test

Core APIs

2014-08-11T18:12:13Z

Emerrill: Fix typo in MUC update.

Moodle has a number of core APIs that provide tools for Moodle scripts.

They are essential when writing [[Plugins|Moodle plugins]].

==Most-used General APIs==

These APIs are critical and will be used by nearly every Moodle plugin.

=== Access API (access) ===

The [[Access API]] gives you functions so you can determine what the current user is allowed to do, and it allows modules to extend Moodle with new capabilities.

=== Data manipulation API (dml) ===

The [[Data manipulation API]] allows you to read/write to databases in a consistent and safe way.

=== File API (files) ===

The [[File API]] controls the storage of files in connection to various plugins.

=== Form API (form) ===

The [[Form API]] defines and handles user data via web forms.

=== Logging API (log) ===

The [[Event 2]] API allows you to log events in Moodle, while [[Logging 2]] describes how logs are stored and retrieved.

=== Navigation API (navigation) ===

The [[Navigation API]] allows you to manipulate the navigation tree to add and remove items as you wish.

=== Page API (page) ===

The [[Page API]] is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

=== Output API (output) ===

The [[Output API]] is used to render the HTML for all parts of the page.

=== String API (string) ===

The [[String API]] is how you get language text strings to use in the user interface. It handles any language translations that might be available.

=== Upgrade API (upgrade) ===

The [[Upgrade API]] is how your module installs and upgrades itself, by keeping track of it's own version.

=== Moodlelib API (core) ===

The [[Moodlelib API]] is the central library file of miscellaneous general-purpose Moodle functions. Functions can over the handling of request parameters, configs, user preferences, time, login, mnet, plugins, strings and others. There are plenty of defined constants too.

==Other General APIs==

=== Admin settings (admin) ===

The [[Admin settings]] API deals with providing configuration options for each plugin and Moodle core.

=== Availability (availability) ===

The [[Availability API]] controls access to activities and sections.

=== Backup API (backup) ===

The [[Backup API]] defines exactly how to convert course data into XML for backup purposes, and the [[Restore API]] describes how to convert it back the other way.

=== Cache API (backup) ===

The [[The Moodle Universal Cache (MUC)]] is the structure for storing cache data within Moodle. [[Cache_API]] explains some of what is needed to use a cache in your code.

=== Calendar API (calendar) ===

The [[Calendar API]] allows you to add and modify events in the calendar for user, groups, courses, or the whole site.

=== Comment API (comment) ===

The [[Comment API]] allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.

=== Data definition API (ddl) ===

The [[Data definition API]] is what you use to create, change and delete tables and fields in the database during upgrades.

=== Enrolment API (enrol) ===

The [[Enrolment API]] deals with course participants.

=== Events API (event) ===

The [[Event 2]] allows to define "events" with payload data to be fired whenever you like, and it also allows you to define handlers to react to these events when they happen. This is the recommended form of inter-plugin communication. This also forms the basis for logging in Moodle.

=== External functions API (external) ===

The [[External functions API]] allows you to create fully parametrised methods that can be accessed by external programs (such as [[Web services]]).

=== Lock API (lock) ===

The [[Lock API]] lets you synchronise processing between multiple requests, even for separate nodes in a cluster.

=== Message API (message) ===

The [[Message API]] lets you post messages to users. They decide how they want to receive them.

=== Media API (media) ===

The [[Media embedding]] API can be used to embed media items such as audio, video, and Flash.

=== Preference API (preference) ===

The [[Preference API]] is a simple way to store and retrieve preferences for individual users.

=== Portfolio API (portfolio) ===

The [[Portfolio API]] allows you to add portfolio interfaces on your pages and allows users to package up data to send to their portfolios.

=== Rating API (rating) ===

The [[Rating API]] lets you create AJAX rating interfaces so that users can rate items in your plugin. In an activity module, you may choose to aggregate ratings to form grades.

=== RSS API (rss) ===

The [[RSS API]] allows you to create secure RSS feeds of data in your module.

=== Tag API (tag) ===

The [[Tag API]] allows you to store tags (and a tag cloud) to items in your module.

=== Task API (task) ===

The [[Task API]] lets you run jobs in the background. Either once off, or on a regular schedule.

=== Time API (time) ===

The [[Time API]] takes care of translating and displaying times between users in the site.

=== Testing API (test) ===

The testing API contains the Unit test API ([[PHPUnit]]) and Acceptance test API ([[Acceptance testing]]). Ideally all new code should have unit tests written FIRST.

=== User-related APIs (user) ===

This is a rather informal grouping of miscellaneous [[User-related APIs]] relating to sorting and searching lists of users.

=== Web services API (webservice) ===

The [[Web services API]] allows you to expose particular functions (usually external functions) as web services.

== Activity module APIs ==

Activity modules are the most important plugin in Moodle. There are several core APIs that service only Activity modules.

=== Activity completion API (completion) ===

The [[Activity completion API]] is to indicate to the system how activities are completed.

=== Advanced grading API (grading) ===

The [[Advanced grading API]] allows you to add more advanced grading interfaces (such as rubrics) that can produce simple grades for the gradebook.

=== Conditional activities API (condition) - deprecated in 2.7 ===

The deprecated [[Conditional activities API]] used to provide conditional access to modules and sections in Moodle 2.6 and below. It has been replaced by the [[Availability API]].

=== Groups API (group) ===

The [[Groups API]] allows you to check the current activity group mode and set the current group.

=== Gradebook API (grade) ===

The [[Gradebook API]] allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

=== Plagiarism API (plagiarism) ===

The [[Plagiarism API]] allows your activity module to send files and data to external services to have them checked for plagiarism.

=== Question API (question) ===

The [[Question API]] (which can be divided into the Question bank API and the Question engine API), can be used by activities that want to use questions from the question bank.

== See also ==

* [[Plugins]] - plugin types also have their own APIs
* [[Coding style]] - general information about writing PHP code for Moodle

Core APIs

2014-08-11T18:11:26Z

Emerrill:

Moodle has a number of core APIs that provide tools for Moodle scripts.

They are essential when writing [[Plugins|Moodle plugins]].

==Most-used General APIs==

These APIs are critical and will be used by nearly every Moodle plugin.

=== Access API (access) ===

The [[Access API]] gives you functions so you can determine what the current user is allowed to do, and it allows modules to extend Moodle with new capabilities.

=== Data manipulation API (dml) ===

The [[Data manipulation API]] allows you to read/write to databases in a consistent and safe way.

=== File API (files) ===

The [[File API]] controls the storage of files in connection to various plugins.

=== Form API (form) ===

The [[Form API]] defines and handles user data via web forms.

=== Logging API (log) ===

The [[Event 2]] API allows you to log events in Moodle, while [[Logging 2]] describes how logs are stored and retrieved.

=== Navigation API (navigation) ===

The [[Navigation API]] allows you to manipulate the navigation tree to add and remove items as you wish.

=== Page API (page) ===

The [[Page API]] is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

=== Output API (output) ===

The [[Output API]] is used to render the HTML for all parts of the page.

=== String API (string) ===

The [[String API]] is how you get language text strings to use in the user interface. It handles any language translations that might be available.

=== Upgrade API (upgrade) ===

The [[Upgrade API]] is how your module installs and upgrades itself, by keeping track of it's own version.

=== Moodlelib API (core) ===

The [[Moodlelib API]] is the central library file of miscellaneous general-purpose Moodle functions. Functions can over the handling of request parameters, configs, user preferences, time, login, mnet, plugins, strings and others. There are plenty of defined constants too.

==Other General APIs==

=== Admin settings (admin) ===

The [[Admin settings]] API deals with providing configuration options for each plugin and Moodle core.

=== Availability (availability) ===

The [[Availability API]] controls access to activities and sections.

=== Backup API (backup) ===

The [[Backup API]] defines exactly how to convert course data into XML for backup purposes, and the [[Restore API]] describes how to convert it back the other way.

=== Cache API (backup) ===

The [[The_Moodle_Universal_Cache_(MUC)]] is the structure for storing cache data within Moodle. [[Cache_API]] explains some of what is needed to use a cache in your code.

=== Calendar API (calendar) ===

The [[Calendar API]] allows you to add and modify events in the calendar for user, groups, courses, or the whole site.

=== Comment API (comment) ===

The [[Comment API]] allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.

=== Data definition API (ddl) ===

The [[Data definition API]] is what you use to create, change and delete tables and fields in the database during upgrades.

=== Enrolment API (enrol) ===

The [[Enrolment API]] deals with course participants.

=== Events API (event) ===

The [[Event 2]] allows to define "events" with payload data to be fired whenever you like, and it also allows you to define handlers to react to these events when they happen. This is the recommended form of inter-plugin communication. This also forms the basis for logging in Moodle.

=== External functions API (external) ===

The [[External functions API]] allows you to create fully parametrised methods that can be accessed by external programs (such as [[Web services]]).

=== Lock API (lock) ===

The [[Lock API]] lets you synchronise processing between multiple requests, even for separate nodes in a cluster.

=== Message API (message) ===

The [[Message API]] lets you post messages to users. They decide how they want to receive them.

=== Media API (media) ===

The [[Media embedding]] API can be used to embed media items such as audio, video, and Flash.

=== Preference API (preference) ===

The [[Preference API]] is a simple way to store and retrieve preferences for individual users.

=== Portfolio API (portfolio) ===

The [[Portfolio API]] allows you to add portfolio interfaces on your pages and allows users to package up data to send to their portfolios.

=== Rating API (rating) ===

The [[Rating API]] lets you create AJAX rating interfaces so that users can rate items in your plugin. In an activity module, you may choose to aggregate ratings to form grades.

=== RSS API (rss) ===

The [[RSS API]] allows you to create secure RSS feeds of data in your module.

=== Tag API (tag) ===

The [[Tag API]] allows you to store tags (and a tag cloud) to items in your module.

=== Task API (task) ===

The [[Task API]] lets you run jobs in the background. Either once off, or on a regular schedule.

=== Time API (time) ===

The [[Time API]] takes care of translating and displaying times between users in the site.

=== Testing API (test) ===

The testing API contains the Unit test API ([[PHPUnit]]) and Acceptance test API ([[Acceptance testing]]). Ideally all new code should have unit tests written FIRST.

=== User-related APIs (user) ===

This is a rather informal grouping of miscellaneous [[User-related APIs]] relating to sorting and searching lists of users.

=== Web services API (webservice) ===

The [[Web services API]] allows you to expose particular functions (usually external functions) as web services.

== Activity module APIs ==

Activity modules are the most important plugin in Moodle. There are several core APIs that service only Activity modules.

=== Activity completion API (completion) ===

The [[Activity completion API]] is to indicate to the system how activities are completed.

=== Advanced grading API (grading) ===

The [[Advanced grading API]] allows you to add more advanced grading interfaces (such as rubrics) that can produce simple grades for the gradebook.

=== Conditional activities API (condition) - deprecated in 2.7 ===

The deprecated [[Conditional activities API]] used to provide conditional access to modules and sections in Moodle 2.6 and below. It has been replaced by the [[Availability API]].

=== Groups API (group) ===

The [[Groups API]] allows you to check the current activity group mode and set the current group.

=== Gradebook API (grade) ===

The [[Gradebook API]] allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

=== Plagiarism API (plagiarism) ===

The [[Plagiarism API]] allows your activity module to send files and data to external services to have them checked for plagiarism.

=== Question API (question) ===

The [[Question API]] (which can be divided into the Question bank API and the Question engine API), can be used by activities that want to use questions from the question bank.

== See also ==

* [[Plugins]] - plugin types also have their own APIs
* [[Coding style]] - general information about writing PHP code for Moodle

Core APIs

2014-08-11T18:08:03Z

Emerrill: Update event and log API listings.

Moodle has a number of core APIs that provide tools for Moodle scripts.

They are essential when writing [[Plugins|Moodle plugins]].

==Most-used General APIs==

These APIs are critical and will be used by nearly every Moodle plugin.

=== Access API (access) ===

The [[Access API]] gives you functions so you can determine what the current user is allowed to do, and it allows modules to extend Moodle with new capabilities.

=== Data manipulation API (dml) ===

The [[Data manipulation API]] allows you to read/write to databases in a consistent and safe way.

=== File API (files) ===

The [[File API]] controls the storage of files in connection to various plugins.

=== Form API (form) ===

The [[Form API]] defines and handles user data via web forms.

=== Logging API (log) ===

The [[Event 2]] API allows you to log events in Moodle, while [[Logging 2]] describes how logs are stored and retrieved.

=== Navigation API (navigation) ===

The [[Navigation API]] allows you to manipulate the navigation tree to add and remove items as you wish.

=== Page API (page) ===

The [[Page API]] is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

=== Output API (output) ===

The [[Output API]] is used to render the HTML for all parts of the page.

=== String API (string) ===

The [[String API]] is how you get language text strings to use in the user interface. It handles any language translations that might be available.

=== Upgrade API (upgrade) ===

The [[Upgrade API]] is how your module installs and upgrades itself, by keeping track of it's own version.

=== Moodlelib API (core) ===

The [[Moodlelib API]] is the central library file of miscellaneous general-purpose Moodle functions. Functions can over the handling of request parameters, configs, user preferences, time, login, mnet, plugins, strings and others. There are plenty of defined constants too.

==Other General APIs==

=== Admin settings (admin) ===

The [[Admin settings]] API deals with providing configuration options for each plugin and Moodle core.

=== Availability (availability) ===

The [[Availability API]] controls access to activities and sections.

=== Backup API (backup) ===

The [[Backup API]] defines exactly how to convert course data into XML for backup purposes, and the [[Restore API]] describes how to convert it back the other way.

=== Calendar API (calendar) ===

The [[Calendar API]] allows you to add and modify events in the calendar for user, groups, courses, or the whole site.

=== Comment API (comment) ===

The [[Comment API]] allows you to save and retrieve user comments, so that you can easily add commenting to any of your code.

=== Data definition API (ddl) ===

The [[Data definition API]] is what you use to create, change and delete tables and fields in the database during upgrades.

=== Enrolment API (enrol) ===

The [[Enrolment API]] deals with course participants.

=== Events API (event) ===

The [[Event 2]] allows to define "events" with payload data to be fired whenever you like, and it also allows you to define handlers to react to these events when they happen. This is the recommended form of inter-plugin communication. This also forms the basis for logging in Moodle.

=== External functions API (external) ===

The [[External functions API]] allows you to create fully parametrised methods that can be accessed by external programs (such as [[Web services]]).

=== Lock API (lock) ===

The [[Lock API]] lets you synchronise processing between multiple requests, even for separate nodes in a cluster.

=== Message API (message) ===

The [[Message API]] lets you post messages to users. They decide how they want to receive them.

=== Media API (media) ===

The [[Media embedding]] API can be used to embed media items such as audio, video, and Flash.

=== Preference API (preference) ===

The [[Preference API]] is a simple way to store and retrieve preferences for individual users.

=== Portfolio API (portfolio) ===

The [[Portfolio API]] allows you to add portfolio interfaces on your pages and allows users to package up data to send to their portfolios.

=== Rating API (rating) ===

The [[Rating API]] lets you create AJAX rating interfaces so that users can rate items in your plugin. In an activity module, you may choose to aggregate ratings to form grades.

=== RSS API (rss) ===

The [[RSS API]] allows you to create secure RSS feeds of data in your module.

=== Tag API (tag) ===

The [[Tag API]] allows you to store tags (and a tag cloud) to items in your module.

=== Task API (task) ===

The [[Task API]] lets you run jobs in the background. Either once off, or on a regular schedule.

=== Time API (time) ===

The [[Time API]] takes care of translating and displaying times between users in the site.

=== Testing API (test) ===

The testing API contains the Unit test API ([[PHPUnit]]) and Acceptance test API ([[Acceptance testing]]). Ideally all new code should have unit tests written FIRST.

=== User-related APIs (user) ===

This is a rather informal grouping of miscellaneous [[User-related APIs]] relating to sorting and searching lists of users.

=== Web services API (webservice) ===

The [[Web services API]] allows you to expose particular functions (usually external functions) as web services.

== Activity module APIs ==

Activity modules are the most important plugin in Moodle. There are several core APIs that service only Activity modules.

=== Activity completion API (completion) ===

The [[Activity completion API]] is to indicate to the system how activities are completed.

=== Advanced grading API (grading) ===

The [[Advanced grading API]] allows you to add more advanced grading interfaces (such as rubrics) that can produce simple grades for the gradebook.

=== Conditional activities API (condition) - deprecated in 2.7 ===

The deprecated [[Conditional activities API]] used to provide conditional access to modules and sections in Moodle 2.6 and below. It has been replaced by the [[Availability API]].

=== Groups API (group) ===

The [[Groups API]] allows you to check the current activity group mode and set the current group.

=== Gradebook API (grade) ===

The [[Gradebook API]] allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

=== Plagiarism API (plagiarism) ===

The [[Plagiarism API]] allows your activity module to send files and data to external services to have them checked for plagiarism.

=== Question API (question) ===

The [[Question API]] (which can be divided into the Question bank API and the Question engine API), can be used by activities that want to use questions from the question bank.

== See also ==

* [[Plugins]] - plugin types also have their own APIs
* [[Coding style]] - general information about writing PHP code for Moodle

Old Events API

2014-08-11T18:04:26Z

Emerrill: Marking page as obsolete.

{{obsolete}}
'''See [[Event 2]] for the new Events API.'''

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement enrolment in Moodle 2.0. In the enrolment system, lib/enrollib.php will generate a 'user_enrolled' event upon completion of an enrolment of a user.

===Triggering an event===

When a user is enrolled, a 'user_enrolled' event is built and sent out by the enrol API. In this example let's pretend someone was just enrolled.

The enrol lib (could even be a module thats creating this event) needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.
<code php>
$ue = new stdClass();
$ue->enrolid = $instance->id;
$ue->status = is_null($status) ? ENROL_USER_ACTIVE : $status;
$ue->userid = $userid;
$ue->timestart = $timestart;
$ue->timeend = $timeend;
$ue->modifierid = $USER->id;
...
$ue->courseid = $courseid;
$ue->enrol = $name;

events_trigger('user_enrolled', $ue);
</code>
Then we post the object as an event and forget about it:
<code php>
events_trigger('user_enrolled', $eventdata);
</code>
We have now broadcast an event that we think other parts of the system might need to know about.

===Handling an event===

Modules or core code can define an events.php in under its */db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in mod/forum/db/events.php.

<code php>
$handlers = array (
'user_enrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_enrolled',
'schedule' => 'instant',
'internal' => 1,
),

'user_unenrolled' => array (
'handlerfile' => '/mod/forum/lib.php',
'handlerfunction' => 'forum_user_unenrolled',
'schedule' => 'instant',
'internal' => 1,
),
);
</code>

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''user_enrolled''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):
<code php>
include_once($CFG->dirroot.$handlers['user_enrolled']['handlerfile']);
call_user_func($handlers['user_enrolled']['handlerfunction'], $eventdata);
</code>
Any code can hook into any events this way.

The handler function accepts one parameter (the event data object) and should return a boolean. Returning false indicates that there was an error and the event will be left in the event queue.
<code php>
function forum_user_unenrolled($eventdata) {
// handle event
// ...
return true;
}
</code>
note: a lib/db/events.php exists as legacy and no events should be added here. Core API is not supposed to define events for consumption. Only modules and core components (non-api) should define events for consumption/handling.

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

All event names should follow a consistent naming pattern, such as componentname_noun_verb (See [[Frankenstyle]] about the component name)

If the event is being fired after the action has taken place (as in most cases) then use the past tense for the verb (created / deleted / updated / sent).

If the event '''is''' the action, then use the present tense (create / delete / update / send).

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_deleted
** record from 'user' table before marked as deleted
* user_updated
** full new record from 'user' table
* user_enrolled
** full user enrolment record (TBC)
* user_logout
** params TBC
* user_loggedin
** full record from user table
* user_unenrol_modified
** full user enrolment record (TBC)
* user_unenrolled
** full user enrolment record (TBC)

===Roles===
* role_assigned
** full new record from 'role_assignments' table
* role_unassigned
** record from 'role_assignments', course context only

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record
* course_content_removed
** full course record
* course_restored (2.5)

===Groups===
* groups_member_added
** groupid, userid
* groups_member_removed
** groupid, userid
* groups_group_created
** id, courseid, name, description, timecreated, timemodified, picture
* groups_group_updated
** id, courseid, name, description, timecreated, timemodified, picture
* groups_group_deleted
** id, courseid, name, description, timecreated, timemodified, picture
* groups_grouping_created
** id, courseid, name, timecreated, timemodified
* groups_grouping_updated
** id, courseid, name, timecreated, timemodified
* groups_grouping_deleted
** id, courseid, name, timecreated, timemodified
* groups_members_removed ''(user deleted from all groups in a course)''
** courseid, userid
* groups_groupings_groups_removed ''(remove all groups from all groupings in a course)''
** courseid (as plain integer, not object)
* groups_groups_deleted ''(delete all groups in a course)''
** courseid (as plain integer, not object)
* groups_groupings_deleted ''(delete all groupings in a course)''
** courseid (as plain integer, not object)

===Cohorts===
* cohort_added
** full cohort record (TBC)
* cohort_deleted
** full cohort record (TBC)
* cohort_member_added
** cohort ID, user ID (TBC)
* cohort_member_removed
** cohort ID, user ID (TBC)
* cohort_updated
** full cohort record (TBC)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

===Other===
* assessable_file_uploaded
* assessable_files_done
* mod_created
* mod_deleted
* mod_updated
* quiz_attempt_started
* quiz_attempt_submitted - ''Note: these two quiz events changed in Moodle 2.1''.

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.
* module_installed ''(= mod_created in v2?)''
* module_removed ''(= mod_deleted in v2?)''
* grade_update ''(= quiz_attempt_processed in v2?)''
* assignment_submitted
* course - editing turned on or off
* course completed
* course module completion state changed (completed / not completed)
* course was reset
* Some will_be ... events that would allow another plugin to react before these things happen:
** course_will_be_restored (with info about course being restored and the target category)
** course_category_will_be_moved (with info about category being moved and target category)
** course_will_be_moved (with course info and target category info)

Provide event trigger hooks for the modules, similar to what is done for the cron service which checks the LOCAL directory for a cron file. It is already possible to define an event trigger but the core/module code must be modified to actually make use of it.

== See also ==

* [[Core APIs]]
* [http://moodle.org/mod/forum/discuss.php?d=69103 Original General Developer Forum thread discussing this proposal].
* [[Messaging_2.0]]
* [[Event_2]]

[[Category:Coding guidelines|Events]]
[[Category:Grades]]
[[Category:API]]

Logging API

2014-08-11T18:01:55Z

Emerrill: Point people to the correct pages

{{obsolete}}
See [[Logging 2]] and [[Event 2]] for more up-to-date information. --[[User:Eric Merrill|Eric Merrill]] 17:00, 11 August 2014 (UTC)

==Overview==

The Logging API allows you to add new entries to the Moodle log and define how they get displayed in reports. Logging is an extremely important and often neglected aspect of Moodle Plugin development. All important actions such as viewing, deleting, editing etc should be logged.

==File locations==

The Log API is all in lib/datalib.php and is automatically included for you during the page setup.

==Functions and Examples==

Following are the functions that constitute the basic log API for Moodle.
<code php>
add_to_log($courseid, $module, $action, $url='', $info='', $cm=0, $user=0)
user_accesstime_log($courseid=0)
get_logs($select, array $params=null, $order='l.time DESC', $limitfrom='', $limitnum='', &$totalcount)
get_logs_usercourse($userid, $courseid, $coursestart)
get_logs_userday($userid, $courseid, $daystart)
</code>
The basic working of these functions can be categorized in two categories:-
# Adding data to logs
# Fetching data from logs
Let us take a deeper look into both of these:-

===Adding data to Logs===
In Moodle basically we have two functions that take care of adding data to the logs table :-
<code php>
add_to_log($courseid, $module, $action, $url='', $info='', $cm=0, $user=0)
user_accesstime_log($courseid=0)
</code>

==== add_to_log() ====
This function is basic core function which you should use to add all your logs to the Moodle Log table. While using this function to add data to logs, please remember that this function is more "Action" oriented rather than being based on "webserver hits", i.e the events should be logged with enough information that this data can be effectively used to regenerate the entire flow of events and action associated with any specific user.
This is a simple example:-
<code php>
add_to_log($course->id, 'role', 'assign', 'admin/roles/assign.php?contextid='.$context->id.'&roleid='.$roleid, $rolename, '', $USER->id);
</code>

==== user_accesstime_log() ====
user_accesstime_log() is used to record the last access time for courses and site. This is basically called when a user vists the site or a course page.
A simple example can be :-
<code php>
$courseid = $course->id;
user_accesstime_log($courseid);
</code>

===Fetching Logs===
we have three functions that can take care of all your needs to interact with the existing log data in the database. Following function can be used to effectively retrieve log data as per your needs:-
<code php>
get_logs($select, array $params=null, $order='l.time DESC', $limitfrom='', $limitnum='', &$totalcount)
get_logs_usercourse($userid, $courseid, $coursestart)
get_logs_userday($userid, $courseid, $daystart)
</code>
====get_logs()====
This is a generic function to fetch data based on a given SQL condition.
<code php>
$params = array();
$selector = "l.course = :courseid";
$params['courseid'] = $course->id;
$logs = get_logs($selector, $params, $order, $limitfrom, $limitnum, $totalcount);
</code>

====get_logs_usercourse()====
get_logs_usercourse() returns logs data for a given specific course and user.
<code php>
$coursestart = usergetmidnight($course->startdate);
$logs = get_logs_usercourse($user->id, $courseselect, $coursestart);
</code>
====get_logs_userday()====
This function can return logs specific to a given user and course for a given date.
<code php>
$daystart = usergetmidnight(time());
$logs = get_logs_userday($user->id, $courseselect, $daystart);
</code>

==Mod/*/db/log.php Files==
These files specify what information should be associated with a log entry. To understand the working of these files better its necessary to understand the structure of database table 'prefix_log_display'.

{| class="nicetable"
|-
! Field
! Type
! Default
! Info
|-
| id
| bigint(10)
| auto-incrementing
| The unique ID for this comment.
|-
| module
| varchar(20)
|
| who wrote this comment
|-
| action
| varchar(40)
|
| The action associated. Ex- view, delete, update etc
|-
| mtable
| varchar(30)
|
| The name of the database table from which info will be fetched to associate with the log entry
|-
| field
| varchar(200)
|
| Which filed needs to be fetched from mtable
|-
| component
| varchar(100)
|
| The component ([https://docs.moodle.org/dev/Frankenstyle Frankenstyle name]) associated with the entry
|}

When a log needs to be displayed to a front end user, this table helps us determine what information needs to be displayed to the user along with the log entry, so that they can make perfect sense out of the report. Whenever we have to display a log entry for a given module and action say $module and $action, the information that's shown along with the log is the value of the 'field' column fetched from 'mtable' corresponding to the given $module and $action.
Now Mod/*/db/log.php files are used to create this association by adding entries to the log_display table during the install or upgrade of a module.
===Example===
This a simple example of what contents of log.php files can be.
<code php>
$logs = array(
array('module'=>'page', 'action'=>'view', 'mtable'=>'page', 'field'=>'name'),
array('module'=>'page', 'action'=>'view all', 'mtable'=>'page', 'field'=>'name'),
array('module'=>'page', 'action'=>'update', 'mtable'=>'page', 'field'=>'name'),
array('module'=>'page', 'action'=>'add', 'mtable'=>'page', 'field'=>'name'),
);
</code>

==See Also==

* [[Core APIs]]
* [https://docs.moodle.org/en/Logs Logs Reports]

[[Category:API]]

SQL coding style

2014-06-11T15:32:25Z

Emerrill: Updating to show table aliases info and link to Database page.

This page describes recommended coding style for complex database queries.

Full SQL queries are used in $DB->get_records_sql(), $DB->get_recordset_sql() or $DB->execute(). SQL fragments may be used in DML method with _select() suffix.

== General rules==
* Use parameter placeholders!
* All SQL keywords are in UPPER CASE.
* All SQL queries and fragments should be enclosed in double quotes.
* Complex SQL queries should be on multiple lines.
* Multiline SQL queries should be right aligned on SELECT, FROM, JOIN, WHERE, GROUPY BY and HAVING.
* Use JOIN instead of INNER JOIN.
* Do not use right joins.
* Always use AS keyword for column aliases.
* Never use AS keyword for table aliases.

==Double quotes==

All sql queries and fragments should be enclosed in double quotes, do not concat SQL from multiple parts if possible. The single quotes are used for sql strings, it also helps with visual highlighting and SQL code completion in some IDEs.

<code php>
$records = $DB->get_records_select('some_table', "id > ?", array(111));
</code>

==Parameter placeholders==

All variable query parameters must be specified via placeholders. It is possible to use three different types of placeholders: :named, ? and $1. It is recommended to use named parameters if there is more than one parameter.

<code php>
$sql = "SELECT *
FROM {some_table}
WHERE id > :above";
$records = $DB->get_records_sql($sql, array('above'=>111));
</code>

==Indentation==

[[File:sql_indentation.png]]

==Subqueries==

There are no strict rules for subquery indentation, the deciding factor is good readability - see MDLSITE-1914.

==See also==

* [[Data manipulation API]]
* [[Database]]
* [[Coding style]]

[[Category:Coding guidelines|Coding style]]
[[Category:XMLDB]]
[[Category:DB]]

Cache API - Quick reference

2014-05-18T01:57:44Z

Emerrill: /* Create a definition */ Updating definition with current options.

This is a quick reference lookup for the Cache API.
More detail can be found on the [[Cache API]] page as well as a friendly explanation of the API.

==Using a cache object==
===Getting a cache instance for a definition===
<code php>
// Most basic
$cache = cache::make('component', 'area');

// Using identifiers
$cache = cache::make('component', 'area', array('dbfamily' => 'pgsql'));
</code>

===Getting an ad-hoc cache instance===
Using cache definitions is the recommended method. Ad-hoc caches should only be used where you have a rarely used cache, or insignificant cache. Typical use-case can be when you are refactoring some local static variables into MODE_REQUEST caches.
<code php>
// Application cache
$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'component', 'area');

// Session cache
$cache = cache::make_from_params(cache_store::MODE_SESSION, 'component', 'area');

// Request cache
$cache = cache::make_from_params(cache_store::MODE_REQUEST, 'component', 'area');

// Using identifiers
$cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'component', 'area',
array('dbfamily' => 'pgsql'));

// Using persistence so that the cache instance is stored for future use/request
$cache = cache::make_with_params(cache::MODE_APPLICATION, 'component', 'area', array(),
array('persistent' => true));

// Using a request cache to replace static variable
$cache = cache::make_from_params(cache_store::MODE_REQUEST, 'component', 'area', array(),
array('simplekeys' => true, 'simpledata' => true));
</code>

===Get a key===
If you have many keys to retrieve you should use [[#Get many keys at once|get_many]].
<code php>
// Get a cache instance
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

// Key can be an int or string
$data = $cache->get('key');

// Data returned will be what ever was stored, or false if it was not in the cache.
</code>

===Get many keys at once===
Not all cache stores will support fetching many keys at once, some stores will take the array of keys and process them one by one.
If you have many keys to fetch it is recommended to use this still as cache stores that do support this will likely perform better.
<code php>
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

// Set some data so I can show results
$cache->set('key1', 'data1');
$cache->set('key3', 'data3');

// Keys can be an int or string
$keys = array(
'key1',
'key2',
'key3'
);
$results = $cache->get_many($keys);

print_r($results);

// Will print the following:
// array(
// 'key1' => 'data1',
// 'key2' => false,
// 'key3' => 'data3'
// )
</code>

===Store a key===
If you have many items to store you should use [[#Store many keys at once|set_many]].
<code php>
// Get a cache instance
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

// Key can be an int or string
// Data can be anything
$result = $cache->set('key', 'data');

// Result will be true on success, false otherwise.
</code>

===Store many keys at once===
Note not all stores will support setting several items in a single transaction, stores that don't will process each item of the array separately.
It is still recommended to use this method if you have many items to set as those stores that do support it will likely perform better.
<code php>
// Get a cache instance
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

// Prepare an associative array of key => value pairs.
// Key can be an int or string
// Data can be anything
$data = array(
'key1' => 'data1',
'key3' => 'data3'
);

// Use set_many
$result = $cache->set_many($data);

// Result will be an int, the number of items successfully set.
</code>

===Delete a key===
If you have several keys you want to delete you should use [[#Delete many keys at once|delete_many]]. If you want to delete everything you should use [[#Delete all keys|purge]].
<code php>
// Get a cache instance
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

// Key can be an int or string
// Data can be anything
$result = $cache->set('key', 'data');

// Result will be true on success, false otherwise.
</code>
===Delete many keys at once===
<code php>
// Get a cache instance
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

// Key can be an int or string
// Data can be anything
$result = $cache->delete_many('key', 'data');

// $result will contain the number of items successfully deleted.
</code>

===Delete all keys===
It is not recommended to purge unless absolutely required, this will cause the store (plugin instance) being used by your cache to be purged. Not all stores can tell which keys belong to your cache and in that circumstance all keys in the store are deleted, not just the keys belonging to your cache, also the keys belonging to other caches using that same store.
<code php>
// Get a cache instance
$cache = cache::make(cache_store::MODE_APPLICATION, 'component', 'area');

$result = $cache->purge();
// $result will contain the number of items successfully deleted.
</code>

===Create a definition===
Basic definition with just the required mode:
<code php>
$definitions = array(
// The name of the cache area is the key. The component/plugin will be picked up from the file location.
'area' => array(
// [int] Required; Sets the mode for the definition. Must be one of cache_store::MODE_*
'mode' => cache_store::MODE_*,
)
);
</code>

Advanced definition:
<code php>
$definitions = array(
// The name of the cache area is the key. The component/plugin will be picked up from the file location.
'area' => array(
// [int] Required; Sets the mode for the definition. Must be one of cache_store::MODE_*
'mode' => cache_store::MODE_*,

// All of the following options are default

// [bool] Set to true if your cache will only use simple keys for its items.
// Simple keys consist of digits, underscores and the 26 chars of the english language. a-zA-Z0-9_
// If true the keys won't be hashed before being passed to the cache store for gets/sets/deletes. It will be
// better for performance and possible only becase we know the keys are safe.
'simplekeys' => false,

// [bool] If set to true we know that the data is scalar or array of scalar.
'simpledata' => false,

// [array] An array of identifiers that must be provided to the cache when it is created.
'requireidentifiers' => array('ident1', 'ident2'),

// [bool] If set to true then only stores that can guarantee data will remain available once set will be used.
'requiredataguarantee' => false,

// [bool] If set to true then only stores that support multiple identifiers will be used.
'requiremultipleidentifiers' => false,

// [bool] If set to true then a lock will be gained before reading from the cache store. It is recommended not to use
// this setting unless 100% absolutely positively required. Remember 99.9% of caches will NOT need this setting.
// This setting will only be used for application caches presently.
'requirelockingread' => false,

// [bool] If set to true then a lock will be gained before writing to the cache store. As above this is not recommended
// unless truly needed. Please think about the order of your code and deal with race conditions there first.
// This setting will only be used for application caches presently.
'requirelockingwrite' => false,

// [int] If set this will be used as the maximum number of entries within the cache store for this definition.
// Its important to note that cache stores don't actually have to acknowledge this setting or maintain it as a hard limit.
'maxsize' => null,

// [string] A class to use as the loader for this cache. This is an advanced setting and will allow the developer of the
// definition to take 100% control of the caching solution.
// Any class used here must inherit the cache_loader interface and must extend default cache loader for the mode they are using.
'overrideclass' => null,

// [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.
'overrideclassfile' => null,

// [string] A class to use as the data loader for this definition.
// Any class used here must inherit the cache_data_loader interface.
'datasource' => null,

// [string] Suplements the above setting indicated the file containing the class to be used. This file is included when required.
'datasourcefile' => null,

// [bool] This setting does two important things. First it tells the cache API to only instantiate the cache structure for
// this definition once, further requests will be given the original instance.
// Second the cache loader will keep an array of the items set and retrieved to the cache during the request.
// This has several advantages including better performance without needing to start passing the cache instance between
// function calls, the downside is that the cache instance + the items used stay within memory.
// Consider using this setting when you know that there are going to be many calls to the cache for the same information
// or when you are converting existing code to the cache and need to access the cache within functions but don't want
// to add it as an argument to the function.
'staticacceleration' => false,

// [int] This supplements the above setting by limiting the number of items in the caches persistent array of items.
// Tweaking this setting lower will allow you to minimise the memory implications above while hopefully still managing to
// offset calls to the cache store.
'staticaccelerationsize' => null,

// [int] A time to live for the data (in seconds). It is strongly recommended that you don't make use of this and
// instead try to create an event driven invalidation system.
// Not all cache stores will support this natively and there are undesired performance impacts if the cache store does not.
'ttl' => 0,

// [bool] If set to true only the mapped cache store(s) will be used and the default mode store will not. This is a super
// advanced setting and should not be used unless absolutely required. It allows you to avoid the default stores for one
// reason or another.
'mappingsonly' => false,

// [array] An array of events that should cause this cache to invalidate some or all of the items within it.
'invalidationevents' => array('event1', 'event2'),

// [int] The sharing options that are appropriate for this definition. Should be the sum of the possible options.
'sharingoptions' => cache_definition::SHARING_DEFAULT,

// [int] The default sharing option to use. It's highly recommended that you don't set this unless there is a very
// specific reason not to use the system default.
'defaultsharing' => cache_definition::SHARING_DEFAULT,
)
);
</code>

A better explanation of the cache definition can be found on the [[Cache API#The definition|Cache API]] page

==Invalidating keys from a cache==
===Invalidate keys using an event===
<code php>
cache_helper::invalidate_by_event('event1', array('key1', 'key2'));
</code>

===Invalidate keys using belonging to a definition===
<code php>
// Identifiers for the definitions
$identifiers = array(
'ident1' => 'something'
);

// Keys to invalidate
$keys = array('key1', 'key2');

cache_helper::invalidate_by_definition('component', 'area', $identifiers, $keys);
</code>

Cache API

2014-05-18T01:50:59Z

Emerrill: Updating definitions to include simplekeys/simpledata/sharingoptions/defaultsharing. Renaiming persist options to static.

Database

2014-05-15T16:59:28Z

Emerrill: /* Database structures */ Minor type

==Database structures==

To help you create tables that meet these guidelines, we recommend you use the built in [[XMLDB_defining_an_XML_structure#The_XMLDB_editor|database definition (XMLDB) editor]].

# Every table must have an auto-incrementing id field (INT10) as primary key. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Core tables in general should have single word names non-pluralised, and double word names pluralised only for the last word e.g. 'course', 'course_categories'. The only exceptions should be for reserved words e.g. 'files'. Some tables don't fit this pattern right now for historical reasons, but this will eventually be changed.
# Table and column names should avoid using [[XMLDB_reserved_words|reserved words in any database]]. Please check them before creation. Table names may be up to 28 characters long, and Column names up to 30 characters.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/column aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Don't use''' '''table aliases''' at all for DELETE statments (Mysql doesn't like it).
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.
# When refering to integer variable in SQL queries, do not surround the value in quotes. For example, get_records_select('question', "category=$catid") is right. get_records_select('question', "category='$catid'") is wrong. It hides bugs where $catid is undefined. ([http://moodle.org/mod/forum/discuss.php?d=80629 This thread explains].)
# Never use double quotes for variable values in SQL queries (e.g. <strike>'SELECT * FROM {user} WHERE username = "someuser"'</strike>). While this is OK for MySQL, which does not respect ANSI standard for databases, Postgresql is treating double quoted variable this as system identifier (e.g. field name).
# Moodle does not support database "views", don't use them. See Petr's comment on [http://tracker.moodle.org/browse/MDL-25407 Task 25407] for more info about this.

[[Category:Coding guidelines|Database]]
[[Category:DB|Database]]
[[Category:XMLDB|Database]]

Moodle 2.7 release notes

2014-05-06T16:00:22Z

Emerrill: /* Platform */ Typo

[[Releases]] > {{FULLPAGENAME}}

Release date: Expected in May 2014

==Server requirements==

These are just minimums. We recommend keeping all your software updated.

* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* Minimum Database versions:
** PostgreSQL 9.1
** MySQL 5.5.31
** MariaDB 5.5.31
** MSSQL 2008, or
** Oracle 10.2
* Minimum PHP version: PHP 5.4.4 (always use latest PHP 5.4.x or 5.5.x on Windows - http://windows.php.net/download/)
*Ghostscript should be installed for pdf annotation.

==Browser requirements==

* Recent Google Chrome, recent Mozilla Firefox, Safari 6 or later, Internet Explorer 9 or later (IE 10 required for drag and drop of files from outside the browser into Moodle)

==Before you upgrade==

===Questions===

If
* your site stared off on a version of Moodle 2.0.x or older,
* and, when you upgraded to Moodle 2.1 or 2.2, you made use of the complex facility to delay part of the quetion engine upgrade as explained in [https://docs.moodle.org/21/en/Upgrading_to_Moodle_2.1#Planning_the_question_engine_upgrade the upgrade documentation for that version],
* and, you still have not got around to completing that upgrade,
then you must complete it before upgrading to Moodle 2.7.

As you can tell from that previous paragraph, this almost certainly does not affect you. You can check by looking at the bottom of the the [[:en:Environment]] check page in your site, providing you are running a version later than 2.4.9, 2.5.5 or 2.6.2. If you have a problem, it will tell you there. If there is no mention of questions there, you can forget about this.

===Themes===

Several core themes have been removed from Moodle 2.7 (see MDL-43784). If you wish to continue using one of these themes then it's best to reinstall it explicitly *BEFORE* running the upgrade.

* After burner [https://moodle.org/plugins/view.php?plugin=theme_afterburner plugins db] [https://github.com/moodlehq/moodle-theme_afterburner github]
* Anomaly [https://moodle.org/plugins/view.php?plugin=theme_anomaly plugins db] [https://github.com/moodlehq/moodle-theme_anomaly github]
* Arialist [https://moodle.org/plugins/view.php?plugin=theme_arialist plugins db] [https://github.com/moodlehq/moodle-theme_arialist github]
* Binarius [https://moodle.org/plugins/view.php?plugin=theme_binarius plugins db] [https://github.com/moodlehq/moodle-theme_binarius github]
* Boxxie [https://moodle.org/plugins/view.php?plugin=theme_boxxie plugins db] [https://github.com/moodlehq/moodle-theme_boxxie github]
* Brick [https://moodle.org/plugins/view.php?plugin=theme_brick plugins db] [https://github.com/moodlehq/moodle-theme_brick github]
* Formal_white [https://moodle.org/plugins/view.php?plugin=theme_formal_white plugins db] [https://github.com/andreabix/moodle-theme_formal_white github]
* Form factor [https://moodle.org/plugins/view.php?plugin=theme_formfactor plugins db] [https://github.com/moodlehq/moodle-theme_formfactor github]
* Fusion [https://moodle.org/plugins/view.php?plugin=theme_fusion plugins db] [https://github.com/moodlehq/moodle-theme_fusion github]
* Leatherbound [https://moodle.org/plugins/view.php?plugin=theme_leatherbound plugins db] [https://github.com/moodlehq/moodle-theme_leatherbound github]
* Magazine [https://moodle.org/plugins/view.php?plugin=theme_magazine plugins db] [https://github.com/moodlehq/moodle-theme_magazine github]
* Nimble [https://moodle.org/plugins/view.php?plugin=theme_nimble plugins db] [https://github.com/moodlehq/moodle-theme_nimble github]
* Nonzero [https://moodle.org/plugins/view.php?plugin=theme_nonzero plugins db] [https://github.com/moodlehq/moodle-theme_nonzero github]
* Overlay [https://moodle.org/plugins/view.php?plugin=theme_overlay plugins db] [https://github.com/moodlehq/moodle-theme_overlay github]
* Serenity [https://moodle.org/plugins/view.php?plugin=theme_serenity plugins db] [https://github.com/moodlehq/moodle-theme_serenity github]
* Sky high [https://moodle.org/plugins/view.php?plugin=theme_sky_high plugins db] [https://github.com/moodlehq/moodle-theme_sky_high github]
* Splash [https://moodle.org/plugins/view.php?plugin=theme_splash plugins db] [https://github.com/moodlehq/moodle-theme_splash github]
* Standard [https://moodle.org/plugins/view.php?plugin=theme_standard plugins db] [https://github.com/moodlehq/moodle-theme_standard github]
* Standard old [https://moodle.org/plugins/view.php?plugin=theme_standardold plugins db] [https://github.com/moodlehq/moodle-theme_standardold github]

==Headline core features==

===Interface===
* Atto - our new [https://docs.moodle.org/27/en/Text_editor text editor], tightly integrated in Moodle and focussing on usability and accessibility (TinyMCE still available as an option)
* MDL-43855 - New equation editor for Atto
* [https://docs.moodle.org/27/en/Standard_themes Themes clean-up] - Moodle is focussed on Bootstrap and improved responsive design. Clean is now the default theme and most other old themes have been removed from core (still available from Plugins directory). Many small improvements have been made all through the interface.
* More - a completely new theme called More that provides easy configuration though the UI while retaining the power of LESS and Bootstrap.
* Improved [https://docs.moodle.org/27/en/Conditional_activities_settings conditional activities] - complex boolean combinations now supported, plus plugin conditions and a better interface. And faster!
* Reports - User interface for [https://docs.moodle.org/27/en/Logs loglive and log reports] has been improved with more information and filtering support (MDL-43682 and MDL-43681)
* MDL-43856 - New [https://docs.moodle.org/27/en/MathJax_filter MathJax filter]

===Platform===
* Logging - a new logging subsystem with plugins allowing Moodle logs to be very detailed and external. [https://docs.moodle.org/27/en/Events_list Many new events] have been added which developers can take advantage of. MDL-37658 These advancements will support better analytics as well as things like TinCan.
* Tasks - an improved [https://docs.moodle.org/27/en/Scheduled_tasks scheduling system] (like Unix cron) that allows precise scheduling of tasks even on complex clustered servers.
* Performance - With improvements to logging and scheduled tasks, as well as many other small improvements, overall performance will be improved, particularly on large sites.

===Long-term support (LTS) until June 2017===

Most of our releases receive 1 year of backported general bug fixes and 1.5 years of security and dataloss fixes from Moodle HQ.

Due to popular demand, we are committing to giving Moodle 2.7 extended support for security and dataloss fixes for '''3 years''' (that's an extra 1.5 years support for this version).

If you are stuck on an old version then this might be the perfect time to upgrade!

==Details==

===Quiz & Question bank===

* Quiz reports improved. MDL-41727
** Responses from all tries are available for analysis when using or "Adaptive", "Interactive with multiple tries" or similar behaviours.
** Break-down by question variant, for question types like Calculated, STACK and Variable-numeric, which one question can have different random variants.
** Progress bar during long calculations to prevent time-outs.
** Low-level calculation code moved into the question component, where it could potentially be reused by other activities.
** Much more automated testing of this complex area of code.
* Some minor improvements to the usability of the question bank - Some of MDL-40987
** To duplicate a question, you now start by clicking the x2 icon, like for activities. MDL-33653
** The various different ways to move questions in the question bank have been rationalised. MDL-33839
** There is now a 'Save changes and continue editing' button when editing questions. Useful when you are working on a complex question with the preview open in another window. MDL-33653
* New plugin point, so that plugins can add columns to the question bank, or new search conditions. MDL-40313 & MDL-40457
* Essay questions can now require an attachment, with the text optional, rather than the other way around. MDL-39756
* Random short-answer matching question type brought back from the dead. (This was in stable branches, but worth mentioning again.) MDL-27414

===Assignment===

The old Assignment (2.2) module has been removed from core (MDL-33952). It has been replaced by a stub to support transparently remapping urls and restoring course backups from the old module to the new one.

If you are still using the old assignment module - all instances of the old assignment module will be hidden after upgrading to Moodle 2.7. Once the upgrade tool is run on those assignments they will become visible again.

It is recommended to upgrade, and then convert any remaining assignments because logic has been added to the assignment upgrade code for Moodle 2.7 to transparently map urls from the old assignment module to the new one.

If you really, really need to keep using the old module, you should update the code to Moodle 2.7, and then replace the "mod/assignment" folder with the one from the plugins database before completing the upgrade.

A new capability ''mod/assign:editothersubmission'' can be given to teachers to allow them to edit or delete student submissions.

A checkbox 'Notify students' is available to control when to send feedback during the grading process.

Teachers can comment directly on student's work on online text assignments MDL-34432

===Cron===

Cron has received a major update and now has support for both scheduled and adhoc tasks - MDL-25499.
The benefits of these changes are:
* The schedule for every task can be configured by the admin
* Tasks can run in parallel
* Cron processes use locking to prevent the same task running at the same time by different processes

A result of this is that cron can be run much more often, which means (for example) forum posts can be sent out sooner. Admins can keep cron running at the same schedule as before, but it is strongly recommended that they increase the frequency of running cron to at least once per minute.

===Authentication===
Manual account authentication can now have password expiry enabled - MDL-42816

A new setting allows users to log in with both their username and their email address - MDL-41115

== Developer Notes ==

=== API changes ===
* Reports: Reports that use log table, should be updated to use the new logging frame work. Old reports will continue to work as before as long as legacy logging is enabled in the site. See [[Migrating log access in reports]] for details.

[[Category:Release notes]]
[[Category:Moodle 2.7]]

[[fr:Notes de mise à jour de Moodle 2.7]]
[[es:Notas de Moodle 2.7]]

version.php

2014-03-03T23:57:13Z

Emerrill: Clarify the module-> vs plugin-> changes.

This file is included in the main directory of plugin. It is compulsory for most plugin types. Even when not compulsory it is highly recommended. It is required in the Plugins Directory for Moodle 2 and onwards.

It contains a number of fields, which are used during the install / upgrade process to make sure the plugin is compatible with the current Moodle install, as well as spotting whether an upgrade is needed.

The file is a standard PHP file, starting with an opening '<?php' tag and defining the following variables:

'''Note:''' Before Moodle 2.6, for activity modules only, <tt>$module-></tt> had to be used instead of <tt>$plugin-></tt> in the version.php file. Starting in Moodle 2.6, either may be used. Support for <tt>$module-></tt> will be dropped with Moodle 2.10. (MDL-43896)

* $plugin->version = 2011051000;
** Required - the version number of your plugin in the form YYYYMMDDxx, so this example is 10th May 2011 (with 00 indicating this is the first version for that day)
* $plugin->requires = 2010112400;
** Optional - minimum version number of Moodle that this plugin requires (Moodle 1.9 = 2007101509; Moodle 2.0 = 2010112400; Moodle 2.1 = 2011070100; Moodle 2.2 = 2011120500; Moodle 2.3 = 2012062500). See [[Releases]] for a full list.
* $plugin->cron = 0;
** Optional - time interval (in seconds) between calls to the plugin's 'cron' function; set to 0 to disable the cron function calls.
** Cron support is not yet implemented for all plugins.
* $plugin->component = 'plugintype_pluginname';
** Optional - ''frankenstyle'' plugin name, strongly recommended. It is used for installation and upgrade diagnostics.
* $plugin->maturity = MATURITY_STABLE;
** Optional - how stable the plugin is: MATURITY_ALPHA, MATURITY_BETA, MATURITY_RC, MATURITY_STABLE (Moodle 2.0 and above)
* $plugin->release = '2.x (Build: 2011051000)';
** Optional - Human-readable version name
* $plugin->dependencies = array('mod_forum' => ANY_VERSION, 'mod_data' => 2010020300);
** Optional - list of other plugins that are required for this plugin to work (Moodle 2.2 and above)
** In this example, the plugin requires any version of the forum activity and version '20100020300' (or above) of the database activity

Here is a template to copy and paste:
<code 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/>.

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

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

$plugin->version = TODO;
$plugin->requires = TODO; // See https://docs.moodle.org/dev/Moodle_Versions
$plugin->cron = 0;
$plugin->component = 'TODO_FRANKENSTYLE';
$plugin->maturity = MATURITY_STABLE;
$plugin->release = 'TODO';

$plugin->dependencies = array(
'mod_forum' => ANY_VERSION,
'mod_data' => TODO
);
</code>

==See also==

* [[Moodle versions]]

[[Category:Plugins]]

User talk:Eloy Lafuente (stronk7)/Namespaces

2014-02-13T03:00:13Z

Emerrill: /* Comments */

== Votes ==

(put your name/known nick under the preferred options)

* U05: TOVOTE: Allowed syntax of imports:
** A) One import per line is required. ([https://github.com/moodle/moodle/blob/master/mod/assign/feedback/editpdf/locallib.php#L28 example])
*** (eloy) (tim) (dan) (sam) (emerrill)
** B) Multiple imports (comma separated) per line are required. ([https://github.com/moodle/moodle/blob/master/mod/assign/classes/plugininfo/assignsubmission.php#L26 example])
***
** C) Both A) and B) are ok.
*** (damyon) (david)

* L02: TOVOTE: Level 2 namespace:
** A) Must be always a [https://docs.moodle.org/dev/Core_APIs valid Moodle API], with an special (to determine) "componentapi" subspace available for everything else.
*** (eloy) (david)
** B) Can be anything except [https://docs.moodle.org/dev/Core_APIs valid Moodle APIs], that are reserved for classes belonging to such APIs. ([https://github.com/moodle/moodle/tree/master/course/classes/management non-api example]), ([https://github.com/moodle/moodle/tree/master/mod/assign/classes/event api example])
*** (damyon) (tim) (dan) (sam) (emerrill)
** C) No, my friend, there is not C) here, lol.

* A03) TOVOTE: Always apply for the maximum level of detail deciding the namespace for a class (The "event observers" case, currently in a non-normalized way, look for them in code)
** A) Yes (a class zzzz known to belong to component xxxx, api yyyyy, should be \xxxx\yyyy\zzzz).
*** (damyon) (eloy) (tim) (dan) (david) (sam) (emerrill)
** B) No (we can put it elsewhere, as far as it's autoloaded, who cares). ([https://github.com/moodle/moodle/blob/master/badges/classes/observer.php non-namespaced observer]), ([https://github.com/moodle/moodle/blob/master/mod/quiz/classes/group_observers.php namespaced observer]).
***

*S03: TOVOTE: Global scope class backslashing (from namespaced code):
**A) is always required. ([https://github.com/moodle/moodle/blob/master/lib/classes/event/user_updated.php#L69 moodle global scope example]), ([https://github.com/moodle/moodle/blob/master/lib/classes/update/checker.php#L784 php global scope example]).
*** (damyon) (eloy) (tim) (dan) (sam) (emerrill)
**B) is forbidden (because access is provided by importing the global scope class). ([https://github.com/moodle/moodle/blob/master/lib/classes/plugininfo/mod.php#L26 moodle global scope example])
*** (david)
**C) Both A) and B) are ok.
***

== Comments ==

Damo: U05: Can't see why we would need to be so prescriptive.
:Eloy: well, that what the voting is about

Damo: L02: Even in a core plugin I can see that there could be complex code that would benefit from 2nd level namespaces - e.g. quiz. To ban them and reserve them only for core apis is again - too prescriptive.
:Eloy: note that option A provides a way for developers to own an entire sub-namespace ("componentapi") so then can use it and sublevels freely.

Damo: A03 For stuff where this is known it makes sense to standardise.

Damo: S02: A) Because that's how I've done it and I rule.
:Eloy, LOL

----
[[User:David Mudrak|David Mudrak]] ([[User talk:David Mudrak|talk]]) 01:03, 13 February 2014 (WST):
* UO3C - long names would span over multiple lines anyway
* L02A - because it really sucks to explain to our poor add-on developers that they have to refactorize their code just because we started to like some keyword, too. It's enough we already suffer from this heritage in activity modules prefixes.
:Eric: To me, I would rather have the freedom as a contrib dev. Things frequently break between major versions, so that is always a risk. You could provide a know, safe, namespace, but don't *require* it's use. I would rather have the shorter namespace and risk a collision that I need to fix down the road. Here is an ([https://github.com/merrill-oakland/mod_webexactivity/tree/master/classes example]) of what I have being doing at the moment.
::Eloy: Offtopic, and said with love, it's the 2nd time I hear from you about that "freedom" opinion. And, while I understand your point... I also thinks it's a bit nonsense: 1) I want freedom in my addons 2) I want to follow coding-standards 3) As far as coding-standards do not provide me freedom 4) I push to change coding-standards to, officially, get freedom. Again, just arguing by the pleasure of arguing (in my side), but up to some degree I see your point that way. Surely wrongly, lol, but hey, it's my opinion.
:::Dan: But the problem is I can't see everything always naturally fitting into a core api and so that is where I/we want freedom. Rather than forcing it under some core api prefix which is not natural. (GRR. WHY do we insist on using the wiki as a discussion tool. Grr. It sucks.)

:::Eric: Eloy - To me, that logic would only make sense if I am to treat Moodle HQ as a black box that stuff comes out of. There was a discussion going on about this topic, so I'll put in my opinions, and they should be weighted by people for what they are worth (not much). Also, I am not trying to change existing policy - once a the decision is made, I will abide by it. Freedom vs Prescription isn't black and white, I tend to lean towards freedom. That doesn't mean I feel there shouldn't be rules, and plenty of them. I aspire to one day write more than just some patches and contrib modules, and write honest to goodness core code, so I follow these discussions as close as I can, and sometimes participate - I try and walk the fine line between being involved, and being a nuisance (sometimes I fail at that). And I know you argue with love - no Moodle policy discussion would be complete without strong opinions from Eloy :)
* A03A - it just makes sense
* S03B - I \just \can't help \myself but I soooo \dislike these backslashes when looking \at the code. PLEASE. (edit: after spending more time with this, I can understand why to go the A way - such as PHP bug 60022 or following what other frameworks like Symphony, Doctrine or Drupal do). But it still makes me a sad panda :-/)
:<div id="the_easter_egg_revealed">Eloy: hehe, I was aware of that problem from Drupal (only affects php global scope, not moodle global scope, afaik), and that S03B answer is really an easter egg, you found it!. Also, there are at least two more drawbacks with this option. First, its maintenance (to keep the list of imported classes on sync with code, on deletions and so on). And second, it really does not provide any interesting information to know that, along a class, you are going to use, say, stdClass or FileIterator or whatever. And the list can be huge!

p.s. I know it's out of scope of this issue, but I see it a shame that (generally) namespaces in PHP do not really help to prevent collisions in 3rd libraries. Particularly (again from our add-on developers' POV) I know a case when two add-ons ship with the same 3rd party lib. Namespaces really do not help much if one would like to keep 3rd party libs untouched.

p.p.s. To be completely honest (and I know this will be completely out of scope), I still do not see namespaces much useful in Moodle codebase at all. If we were pretending that Moodle code can be composed by reusable components found here and there, then our namespace would have to start with vendor name, i.e. \Moodle\... This is not our case. And we have established and working conventions (frankenstyle prefix) that solve the collisions well. I can't stop thinking that this will just add another layer of code style inconsistency (as I am not naive enough to believe that one day we rewrite everything to use namespaces).

:Eloy: I only can agree 100%. Autoloading was the excuse, since then the tree has been growing without control... time will tell if the fruits are tasty or nasty. I'm sceptic too. But fun is guaranteed!
----

User talk:Eloy Lafuente (stronk7)/Namespaces

2014-02-13T02:59:50Z

Emerrill: /* Comments */

== Votes ==

(put your name/known nick under the preferred options)

* U05: TOVOTE: Allowed syntax of imports:
** A) One import per line is required. ([https://github.com/moodle/moodle/blob/master/mod/assign/feedback/editpdf/locallib.php#L28 example])
*** (eloy) (tim) (dan) (sam) (emerrill)
** B) Multiple imports (comma separated) per line are required. ([https://github.com/moodle/moodle/blob/master/mod/assign/classes/plugininfo/assignsubmission.php#L26 example])
***
** C) Both A) and B) are ok.
*** (damyon) (david)

* L02: TOVOTE: Level 2 namespace:
** A) Must be always a [https://docs.moodle.org/dev/Core_APIs valid Moodle API], with an special (to determine) "componentapi" subspace available for everything else.
*** (eloy) (david)
** B) Can be anything except [https://docs.moodle.org/dev/Core_APIs valid Moodle APIs], that are reserved for classes belonging to such APIs. ([https://github.com/moodle/moodle/tree/master/course/classes/management non-api example]), ([https://github.com/moodle/moodle/tree/master/mod/assign/classes/event api example])
*** (damyon) (tim) (dan) (sam) (emerrill)
** C) No, my friend, there is not C) here, lol.

* A03) TOVOTE: Always apply for the maximum level of detail deciding the namespace for a class (The "event observers" case, currently in a non-normalized way, look for them in code)
** A) Yes (a class zzzz known to belong to component xxxx, api yyyyy, should be \xxxx\yyyy\zzzz).
*** (damyon) (eloy) (tim) (dan) (david) (sam) (emerrill)
** B) No (we can put it elsewhere, as far as it's autoloaded, who cares). ([https://github.com/moodle/moodle/blob/master/badges/classes/observer.php non-namespaced observer]), ([https://github.com/moodle/moodle/blob/master/mod/quiz/classes/group_observers.php namespaced observer]).
***

*S03: TOVOTE: Global scope class backslashing (from namespaced code):
**A) is always required. ([https://github.com/moodle/moodle/blob/master/lib/classes/event/user_updated.php#L69 moodle global scope example]), ([https://github.com/moodle/moodle/blob/master/lib/classes/update/checker.php#L784 php global scope example]).
*** (damyon) (eloy) (tim) (dan) (sam) (emerrill)
**B) is forbidden (because access is provided by importing the global scope class). ([https://github.com/moodle/moodle/blob/master/lib/classes/plugininfo/mod.php#L26 moodle global scope example])
*** (david)
**C) Both A) and B) are ok.
***

== Comments ==

Damo: U05: Can't see why we would need to be so prescriptive.
:Eloy: well, that what the voting is about

Damo: L02: Even in a core plugin I can see that there could be complex code that would benefit from 2nd level namespaces - e.g. quiz. To ban them and reserve them only for core apis is again - too prescriptive.
:Eloy: note that option A provides a way for developers to own an entire sub-namespace ("componentapi") so then can use it and sublevels freely.

Damo: A03 For stuff where this is known it makes sense to standardise.

Damo: S02: A) Because that's how I've done it and I rule.
:Eloy, LOL

----
[[User:David Mudrak|David Mudrak]] ([[User talk:David Mudrak|talk]]) 01:03, 13 February 2014 (WST):
* UO3C - long names would span over multiple lines anyway
* L02A - because it really sucks to explain to our poor add-on developers that they have to refactorize their code just because we started to like some keyword, too. It's enough we already suffer from this heritage in activity modules prefixes.
:Eric: To me, I would rather have the freedom as a contrib dev. Things frequently break between major versions, so that is always a risk. You could provide a know, safe, namespace, but don't *require* it's use. I would rather have the shorter namespace and risk a collision that I need to fix down the road. Here is an ([https://github.com/merrill-oakland/mod_webexactivity/tree/master/classes example]) of what I have being doing at the moment.
::Eloy: Offtopic, and said with love, it's the 2nd time I hear from you about that "freedom" opinion. And, while I understand your point... I also thinks it's a bit nonsense: 1) I want freedom in my addons 2) I want to follow coding-standards 3) As far as coding-standards do not provide me freedom 4) I push to change coding-standards to, officially, get freedom. Again, just arguing by the pleasure of arguing (in my side), but up to some degree I see your point that way. Surely wrongly, lol, but hey, it's my opinion.
:::Dan: But the problem is I can't see everything always naturally fitting into a core api and so that is where I/we want freedom. Rather than forcing it under some core api prefix which is not natural. (GRR. WHY do we insist on using the wiki as a discussion tool. Grr. It sucks.)
:::Eric: Eloy - To me, that logic would only make sense if I am to treat Moodle HQ as a black box that stuff comes out of. There was a discussion going on about this topic, so I'll put in my opinions, and they should be weighted by people for what they are worth (not much). Also, I am not trying to change existing policy - once a the decision is made, I will abide by it. Freedom vs Prescription isn't black and white, I tend to lean towards freedom. That doesn't mean I feel there shouldn't be rules, and plenty of them. I aspire to one day write more than just some patches and contrib modules, and write honest to goodness core code, so I follow these discussions as close as I can, and sometimes participate - I try and walk the fine line between being involved, and being a nuisance (sometimes I fail at that). And I know you argue with love - no Moodle policy discussion would be complete without strong opinions from Eloy :)
* A03A - it just makes sense
* S03B - I \just \can't help \myself but I soooo \dislike these backslashes when looking \at the code. PLEASE. (edit: after spending more time with this, I can understand why to go the A way - such as PHP bug 60022 or following what other frameworks like Symphony, Doctrine or Drupal do). But it still makes me a sad panda :-/)
:<div id="the_easter_egg_revealed">Eloy: hehe, I was aware of that problem from Drupal (only affects php global scope, not moodle global scope, afaik), and that S03B answer is really an easter egg, you found it!. Also, there are at least two more drawbacks with this option. First, its maintenance (to keep the list of imported classes on sync with code, on deletions and so on). And second, it really does not provide any interesting information to know that, along a class, you are going to use, say, stdClass or FileIterator or whatever. And the list can be huge!

p.s. I know it's out of scope of this issue, but I see it a shame that (generally) namespaces in PHP do not really help to prevent collisions in 3rd libraries. Particularly (again from our add-on developers' POV) I know a case when two add-ons ship with the same 3rd party lib. Namespaces really do not help much if one would like to keep 3rd party libs untouched.

p.p.s. To be completely honest (and I know this will be completely out of scope), I still do not see namespaces much useful in Moodle codebase at all. If we were pretending that Moodle code can be composed by reusable components found here and there, then our namespace would have to start with vendor name, i.e. \Moodle\... This is not our case. And we have established and working conventions (frankenstyle prefix) that solve the collisions well. I can't stop thinking that this will just add another layer of code style inconsistency (as I am not naive enough to believe that one day we rewrite everything to use namespaces).

:Eloy: I only can agree 100%. Autoloading was the excuse, since then the tree has been growing without control... time will tell if the fruits are tasty or nasty. I'm sceptic too. But fun is guaranteed!
----

User talk:Eloy Lafuente (stronk7)/Namespaces

2014-02-12T20:23:04Z

Emerrill: /* Comments */

User talk:Eloy Lafuente (stronk7)/Namespaces

2014-02-12T20:19:50Z

Emerrill: /* Comments */ My thoughts about L02

User talk:Eloy Lafuente (stronk7)/Namespaces

2014-02-12T20:17:12Z

Emerrill: /* Votes */ My votes. Feel free to ignore if you just want HQ/core voters

Events API

2014-02-06T15:40:00Z

Emerrill: /* Information contained in events */ Reflect changes in MDL-43661, level became edulevel

{{Infobox Project
|name = Events 2
|state = Implementation in progress
|tracker = MDL-39797 , MDL-39952, MDL-39846
|discussion = https://moodle.org/mod/forum/discuss.php?d=229425
|assignee = Backend Team
}}

= What are events? =

Events are atomic pieces of information describing something that happened in Moodle. Events are primarily the result of user actions, but could also be the result of the [[:en:Cron|cron]] process or administration actions [[:en:Administration via command line|undertaken via the command line]].

When an action takes place, an event is created by a [[Core APIs|core API]] or [[Plugins|plugin]]. The Events system then disseminates this event information to observers registered for this event. In this way, the events system acts as a communication backbone throughout the Moodle system.

Event observers can not modify event data or interrupt the dispatching of events, it is a one way communication channel.

= Why is a new events system needed? =

The need to improve the Events system was prompted by a need for a richer and more efficient logging system, however the benefits of this improvement will be useful to other parts of Moodle that observe event information.

* The events need to be more strictly defined if we want to use them for new logging and other advanced use cases. They need to contain a lot more information in a standardised way (such as most fields from current log table and log_actions table).
* Complex data types were allowed in old events which was causing major problems when serialising/storing/unserializing the data.
* The logging and events contain similar information and are tiggered at the same places, new events would remove this code duplication. All events should be loggable and all current log entries should be triggered as events.
* The logging system will become an event observer, listening to all events and directing them to logging storage plugins in a controllable way.
* It will be possible to subscribe to '*' event, which would allow a system to potentially observe, and selectively deal with, all events. Current handlers do not get event name which makes this problematic.
* Current event handlers may trigger exceptions during site upgrade which would lead to fatal upgrade problems. The new design eliminates this.
* Failure in handlers blocked dispatching of subsequent events. Instead problems in new observers would be only logged and execution would continue normally.
* Current execution of external handlers during DB transactions blocks other handlers. This would be eliminated by in-memory buffer for external events.
* It would good to have observer priority.
* Nested events are not dispatched sequentially, it would change the order of events received in lower priority handlers.

= Performance =
Some basic profiling has been conducted.

There is a general plan to complete pre- and post-implementation testing as development happens. The new system will be imemented in parallel with the old one which should help with comparison of new and old logging and event triggering performance on each page.

Our aim is to trigger more events and log more information, which is going to impact on performance. We hope to offset that impact by improving log storage, simplifying event dispatching and adding other core performance improvements. The proposed class structure of the base event should allow some new advanced techniques, which may also improve performance in some scenarios.

More details will be added to this section soon.

= Events API =

Each plugin will define the events that it can report (trigger) by extending an abstract base class, once for each possible event. This approach will have several benefits.
; Events will be active objects
: When they are triggered and possibly after they are reinstantiated (say, when they are retrieved from a log), an event object will be able to provide callback functions for various purposes (such as capability checks).
; Automatic inclusion
: Event class definitions will be automatically included when needed, without having to maintain lists of known event types. New event definitions can be added without the need to upgrade, only purging of MUC cache is required after adding new observer.
; Maintainability
: It will be easy to add new events and migrate existing events. Code review will be simplified because there will be less duplication of code when triggering events and all event related information/code will be concentrated in one file in fixed locations.
; Self documenting
: The behaviour of events will be combined with the definition of events in one place (file). It will be easy for event observer writers to know what events a plugin can trigger. This includes support for autocompletion and code inspection in modern IDEs.
; Quick, self-validating data structure
: As events are instantiated objects, the PHP processor will validate the structure and type of event classes. This does not ensure data value validity, but does give some assurance of consistency and it also detects common typos.

== Backwards compatibility and migration ==

Events:
* Moodle core and standard plugins will replace all calls to the events_trigger() function with new events classes.
* For events that already exist in Moodle 2.5 the additional legacy information should be added to the event data (in properties 'legacyeventname' and 'legacyeventdata'.
* The function events_trigger() will continue working as before, but it will be called automatically after a new event is processed using the 'legacyeventname' and 'legacyeventdata'.
* The legacy events handling code will be maintained separately and will continue being supported in Moodle 2.x. New legacy events will not be added.
* Existing legacy event handlers will be migrated to new event handlers accepting new event class instances.
* More subsystems may be migrated to events-handlers, ex.: gradebook history.

Logging:
* Function add_to_log() and all logging internals will continue working as before.
* Existing add_to_log() parameters will be migrated inside new events method get_legacy_log_data() and core_event_base::trigger() will call add_to_log() automatically (this will depend on $CFG->loglifetime setting for performance reasons).

== Event dispatching and observers ==

The new event dispatching system is completely separate from the old events code. Original event handlers are now called observers with the description stored in the same db/events.php file, but as a new array with a different format.

=== Event observers ===

The observers are described in db/events.php in the array $observers, the array is not indexed and contains a list of observers defined as an array with the following properties;
* eventname - event class name or "*" indicating all events. All events must use namespace, ex.: ''\plugintype_pluginname\event\something_happened''.
* callback - PHP callable type.
* includefile - optional. File to be included before calling the observer. Path relative to dirroot.
* priority - optional. Defaults to 0. Observers with higher priority are notified first.
* internal - optional. Defaults to true. Non-internal observers are not called during database transactions, but instead after a successful commit of the transaction.

<code php>

$observers = array(

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::observe_one',
),

array(
'eventname' => '\core\event\sample_executed',
'callback' => 'core_event_sample_observer::external_observer',
'priority' => 200,
'internal' => false,
),

array(
'eventname' => '*',
'callback' => 'core_event_sample_observer::observe_all',
'includefile' => null,
'internal' => true,
'priority' => 9999,
),

);

</code>

=== Event dispatching ===

A list of available observers is constructed on the fly directly from all available events.php files. Previously handlers were installed only during installation and upgrade. There is no risk of performance regression because the list is already cached in MUC. Observers get events before installation or any upgrade, however observers are not notified during the initial installation of moodle core tables.

Developers of observers must make sure that execution does not end with a fatal error under any condition (before install, before upgrade or normal operation). Exceptions are automatically captured, logged in the PHP error log, and notification of other observers continues. Current handlers must not throw any exceptions at any time.

Observers are notified sequentially in the same order in which events were triggered. This means that events triggered in observers are queued in FIFO buffer and are processed after all observers are notified.

=== Differences from old event handling ===

# New events contain a lot more structured information.
# New event data must not contain any PHP classes.
# There is separate context cache which may be used when deleting data or for observer performance improvements.
# No database access in new event dispatching code.
# There is no support for cron execution - this eliminates performance problems, simplifies events dispatching and prevents abuse of cron events.
# Events triggered in observers are processed in a different order.
# External events are buffered when a transaction is in progress, instead of being sent to the cron queue.
# It is possible to define multiple observers for one event in one events.php file.
# It is possible to subscribe an observer to all events.
# The new event manager is using frankenstyle autoloading - smaller memory footprint when events are not used on the current page.

== Triggering events ==

* All event descriptions are objects extending the \core\event\base class.
* Events are triggered by creating a new instance of the class event and executing $event->trigger().
* Each event class name is a unique identifier of the event.
* Class names and namespace follow the identifier scheme \'''frankenstyle_component'''\event\'''some_object_action'''. Core events have prefix 'core_'.
* Plugins define each event class in a separate file. File name and location must match the class name, for example: '''plugindir'''/classes/event/'''something_happened'''.php
* The event identifier suffix has the form ''some_object_action'' ('''something_happened''' in the example above) and should follow our standard naming convention. The last word after underscore is automatically parsed as action, the rest of words is object.

Decision:[[#Verb_list| Recommended verb list]]

Examples: \core\event\course_completed, \mod_assign\event\submission_commented, \mod_forum\event\post_shared, \mod_forum\event\post_responded, etc.

* Ideally, it should be possible to trigger an event without gathering additional information for the event. To reduce the cost of data gathering, specifically the cost of database reads, at least the minimal values needed to trigger an event should be already available in variables.

An example of triggering an event:
<code php>
$event = \mod_myplugin\event\something_happened::create(array('context' => $context, 'objectid' => YYY, 'other' => ZZZ));
// ... code that may add some record snapshots
$event->trigger();
</code>

=== Use of php autoloading ===

All new OOP APIs in Moodle 2.6 are going to use class auto loading - see [[Automatic class loading]]. New events use PHP strictly defined namespaces which concentrate all events classes in classes/event/ subdirectory.

=== Why separate classes? ===
There were two alternatives proposed on how to define the event structure. The first is a separate class for each event (extending the base class), the other being each event is based on a generic event instance of the base class.
<pre>
Decision: Use separate class for each event.
</pre>
'''Each plugin creates its own event class for each event'''

Pros
* Maintainability - It is much easier to review, debug, integrate.
* Self documenting, behaviour is combined with definition.
* It is extremely flexible for plugin developers and core devs too.
* Automatically lists events without being installed - PHPDocs as events documentation.
* It is included only when needed using autoloading.
* Self-validating data structure (by PHP).
* Some developers will find it easier to copy whole class files as templates.
Cons
* Big learning curve for developers without OOP skills (all other new subsystems in Moodle already use OOP, you can not code without these skills any more).
* Some developers may find it harder to copy-and-paste examples because they will need to create new class first and use it afterwards (this can be viewed as a benefit because it forces developers to think more about events).

'''Each plugin defines events in a list based on a generic object'''

Pros
* Easier for some developers (this can be eliminated with developer documentation).
* Some developers think it gives more control of event structure in core (we can easily solve that with private access and validation in the base class).
Cons
* It is not flexible enough. PHP code gives developers more freedom.
* It would not be possible to implement any performance hacks in custom methods. All data would have to be calculated even if it is not used.
* It would be necessary to define access control callbacks in other code.
* It would be harder and slower to integrate legacy logging.
* It would be harder and slower to implement support for legacy events.
* Event observers could not use event class names as reliable identifiers.
* Event object and action could not be parsed from class name, it would have to be stored in event properties every time you trigger event.
* Requires upgrade/install to register an event in DB table with MUC cache. Events could not be triggered earlier.
* The localised descriptions and names would have to be stored as properties, it would not be possible to store them in any definition.
* The implementation of an events infrastructure would be significantly more complex and error prone.

== Information contained in events ==

Events have to contain as much information as they can, but this should not affect the performance. That's why part of the information is available in properties, and the rest via methods. This allows for delaying the computation of the data at the time it is really needed, if it ever is.

=== Properties ===

List of properties that the developer has to pass to the event upon creation, or automatically generated when possible and cost free. Some of those properties not mandatory.

{| class="nicetable"
|-
! Property name
! Title
! Type
! Comment
|-
| ''eventname''
| Event name
| ''static, automatic from class name''
| Automatically computed by copying class name
|-
| ''component''
| Component
| ''static, automatic from top namespace''
| Component declaring the event, automatically computed from class name.
|-
| ''action''
| Action
| ''static, automatic from last word in class name''
| Can be automatically computed from class name.
|-
| ''target''
| target of action
| ''static, automatic from class name''
| Target on which the action is taken, can be automatically computed from class name.
|-
| objecttable
| Database table name
|
| optional database table name where is/was the object stored. Never use a relationship table here.
|-
| objectid
| Object ID
|
| optional id of the object record from objecttable
|-
| '''''crud'''''
| Transaction type
| ''static mandatory''
| One of [crud] letters. Statically declared in the event class method init().
|-
| '''''level''''' / '''''edulevel'''''
| Level
| ''static mandatory''
| Level of educational value of the event. Statically declared in the event class method init(). Changed from '''''level''''' to '''''edulevel''''' in Moodle 2.7 (See below for more details)
|-
| contextid
| Context ID
| mandatory
|
|-
| contextlevel
| Context level
| automatic from context
| This tells you if it was a course, activity, course category, etc.
|-
| contextinstanceid
| Context instanceid
| automatic from context
| Based on context level this may be course id , course module id, course category, etc.
|-
| userid
| User ID
| defaults to current user
| User ID, or 0 when not logged in, or -1 when other (System, CLI, Cron, ...)
|-
| courseid
| Affected course
| defaults to course context from context
| This is used only for contexts at and bellow course level - this can be used to filter events by course (includes all course activities)
|-
| relateduserid
| Affected user
|
| Is this action related to some user? This could be used for some personal timeline view.
|-
| other
| All other data
|
| Any other fields needed for event description - scalars or arrays, must be serialisable using json_encode()
|-
| timecreated
| Time of the event
| automatic
|
|}

* ''static'': It is the same for all event instances of this class.
* '''mandatory''': Is required in order to trigger the event.

==== Level property ====

The edulevel property helps defining the educational value of the event. It is intentional that the list is limited to only 3 different constants, having too many options would make it harder for developers to pick the right one(s). We also have to keep in mind that this is not supposed to answer all the questions about a particular event, other event properties like the courseid, the context, the component name can be used with the level to get more granular reports.

Remember that this is event based. If the user that has triggered the event is not really "participating" because he is an admin, or a manager, then it is the job of the report to filter those. The event itself has a static educational level.

'''Teaching''' (LEVEL_TEACHING: 1)

Any event/action that is performed by someone (typically a teacher) and has a teaching value (anything that is affecting the learning experience/environment of the students). This should not be combined with "Participating" events.

Valid events:

* A teacher grading a student
* A teacher modifying the course settings
* A teacher adding a new section to the course page
* A teacher modifying a module settings
* A teacher adding a page to course
* A teacher leaving a feedback

INVALID events:

* A teacher posting in a forum (it might affect the learning experience, but not necessarily, so the teacher is just participating)

'''Participating''' (LEVEL_PARTICIPATING: 2)

Any event/action that is performed by a user, that is related (or could be related) to his learning experience.

Valid events:

* A user posting to a forum
* A user submitting an assignment
* A user blogging
* A user reading someone's blog
* A user posting a comment
* A user chatting on a chat activity
* A user viewing the course page
* A user deletes a blog post

INVALID events:

* A user updating his profile
* A user visiting someone's profile
* A user viewing his /my/ page
* A user sending a message to another one

'''Other''' (LEVEL_OTHER: 0)

Any other action, whether they are related to the site administration, or are specific to user. They do not have any educational value.

=== Methods ===

The computation of this data is not required by default, but can be accessed by any event observer if need be.

{| class="nicetable"
|-
! Method
! Comment
|-
| get_name()
| Returns localised name of the event, it is the same for all instances.
|-
| get_description()
| Returns localised description of one particular event.
|-
| can_view($user)
| Can the specified user view the event?
|-
| get_url()
| Returns Moodle URL where the event can be observed afterwards.
|-
| get_legacy_eventname()
| Information necessary for event BC.
|-
| get_legacy_eventdata()
| Information necessary for event BC.
|-
| get_legacy_logdata()
| Information necessary for logging BC.
|}

===Record caching===

The standard event data may not contain all the information observers need. The built-in record snapshot support in events allows developers to attach more auxiliary information when triggering events, it may be for example course record, some record that was just deleted, etc. The snapshot is meant to be a full database record, as it will be automatically fetched from get_record_snapshot() if not set previously and assuming the property ''objecttable'' is set. Please be aware that the snapshots are not stored in the event, and cannot be restored.

<code php>
$event = \core\event\role_assigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

<code php>
$event = \core\event\role_unassigned::create(
array('context'=>$context, 'objectid'=>$ra->roleid, 'relateduserid'=>$ra->userid,
'other'=>array('id'=>$ra->id, 'component'=>$ra->component, 'itemid'=>$ra->itemid)));
$event->add_record_snapshot('role_assignments', $ra);
$event->trigger();
</code>

The related methods are:
* public function add_record_snapshot($tablename, $record)
* public function get_record_snapshot($tablename, $id)

=== Rejected properties and methods ===

{| class="nicetable"
|-
! Property
! Title
! Why
|-
| URL
| relevant page URL
| These URLs can be constructed on the fly from other data, external log plugins may use get_url() method.
|-
| version
| Event specification number
| The event specification should never change
|-
| type
| Type of event (action, error, ...)
| Event are not intended for error logging or debugging.
|-
| actor
| Whether current execution is cron, cli, user, ...
| Impossible to track down at a low level
|-
| severity
| Severity following [http://tools.ietf.org/html/rfc5424#section-6.2.1 logging standards]
| Our logging does not match this, as we will not (at present) log errors
|-
| coursecatname
| Category name
| Might be costly to retrieve for little gain
|-
| coursename
| Course name
| Might be costly to retrieve for little gain
|-
| cmname
| Course module name
| Might be costly to retrieve for little gain
|-
| categoryid
| Course category id
| Categories are a tree structure, we can not identify them by one integer. It would have to be a path.
|-
| cmid
| Course module id
| Can be derived from contextlevel and contextinstanceid
|-
| associatedobject
| Associated object
| Object associated to the main object. Ie: The user to whom a message is sent.
|-
| associatedobjectid
| Associated object ID
| Identifier of the associated object
|-
| realuserid
| Real User ID
| Will be tracked by log plugins only - user who "logged in as", stores the real user ID
|-
| origin
| Origin of the event
| Will be tracked by log plugins only - CLI, cron, Webservice, ... (optionally with IP address)
|}

{| class="nicetable"
|-
! Method
! Comment
! Why
|-
| get_all_affected_users()
| Returns all the users affected by this event
| It is expensive to fetch all users and it changes in time, so it would be unreliable too. For now we store only one user who is related to each event.
|-
| get_objecturl()
| Returns the URL to view the object
| There is usually only one URL where event changes may be observed. The URL may depend on current user capabilities too.
|-
| get_associatedobjecturl()
| Returns the URL to view the associated object
| No associated user property is present.
|-
| get_currenturl()
| Returns the current URL, uses $PAGE.
| This information may be added by logger, current page info is not part of events data.
|-
| get_useripaddress()
| Returns the User IP address
| Page access method is not part of events API, this should be implemented as logdata properties in loggers.
|}

== Events naming convention ==

Clear event names help developers when reading what events are triggered, and defining the events properties when defining the event class.

Decision: \<component>\event\<some_object>_<verb>

=== Structure of existing events ===

List of existing events called in 2.5, along with their future name and the decomposition of the new name into ''action'' and ''object''.

{| class="nicetable"
|-
! 2.5 name
! New name
! Subject
! Action
! Object
! <relationship>
! Object 2
! Comment
|-
| activity_completion_changed
| '''core_event_activity_completion_updated'''
| Someone
| changed
| completion
| of
| activity
|-
| assessable_content_uploaded
| '''mod_*_event_assessablecontent_uploaded'''
| Someone
| uploaded
| assessablecontent
|-
| assessable_files_done
| '''mod_*_event_assessablecontent_processed'''
| Someone
| processed
| assessable content
|
|
|
|-
| assessable_file_uploaded
|
| Someone
| uploaded
| assessable_file
|
|
| ''To be deprecated MDL-35197''
|-
| assessable_submitted
| '''mod_*_event_assessablecontent_submitted'''
| Someone
| submitted
| assessable content
|-
| blog_entry_added
| '''mod_blog_event_entry_created'''
| Someone
| added
| entry
|-
| blog_entry_deleted
| '''mod_blog_event_entry_deleted'''
| Someone
| deleted
| entry
|-
| blog_entry_edited
| '''mod_blog_event_entry_updated'''
| Someone
| updated
| entry
|-
| cohort_added
| '''core_event_cohort_created'''
| Someone
| created
| cohort
|-
| cohort_deleted
| '''core_event_cohort_deleted'''
| Someone
| deleted
| cohort
|-
| cohort_updated
| '''core_event_cohort_updated'''
| Someone
| updated
| cohort
|-
| cohort_member_added
| '''core_event_cohort_member_added'''
| Someone
| added
| member
| to
| cohort
|-
| cohort_member_removed
| '''core_event_cohort_member_deleted'''
| Someone
| deleted
| member
| from
| cohort
|-
| course_category_deleted
| '''core_event_coursecat_deleted'''
| Someone
| deleted
| coursecat
|-
| course_completed
| '''core_event_course_completed'''
| Someone
| completed
| course
|-
| course_content_removed
| '''core_event_course_purged'''
| Someone
| purged
| course
|-
| course_created
| '''core_event_course_created'''
| Someone
| created
| course
|-
| course_deleted
| '''core_event_course_deleted'''
| Someone
| deleted
| course
|-
| course_restored
| '''core_event_course_restored'''
| Someone
| restored
| course
|-
| course_updated
| '''core_event_course_updated'''
| Someone
| updated
| course
|-
| groups_group_created
| '''core_event_group_created'''
| Someone
| created
| group
|-
| groups_group_deleted
| '''core_event_group_deleted'''
| Someone
| deleted
| group
|-
| groups_grouping_created
| '''core_event_grouping_created'''
| Someone
| created
| grouping
|-
| groups_grouping_deleted
| '''core_event_grouping_deleted'''
| Someone
| deleted
| grouping
|-
| groups_groupings_deleted
|
| Someone
| deleted
| groupings
|
|
| ''To deprecate''
|-
| groups_groupings_groups_removed
|
| Someone
| removed
| groups
| from
| groupings
| ''To deprecate''
|-
| groups_grouping_updated
| '''core_event_grouping_updated'''
| Someone
| updated
| grouping
|-
| groups_groups_deleted
|
| Someone
| deleted
| groups
|
|
| ''To deprecate''
|-
| groups_group_updated
| '''core_event_group_updated'''
| Someone
| updated
| group
|-
| groups_member_added
| '''core_event_group_member_added'''
| Someone
| added
| member
| to
| group
|-
| groups_member_removed
| '''core_event_group_member_deleted'''
| Someone
| deleted
| member
| from
| group
|-
| groups_members_removed
|
| Someone
| removed
| members
| from
| group
| ''To deprecate''
|-
| lti_unknown_service_api_call
| '''mod_lti_event_unknownservice_called'''
| Someone
| called
| unknown service
|-
| mod_created
| '''core_event_module_created'''
| Someone
| created
| module
|-
| mod_deleted
| '''core_event_module_deleted'''
| Someone
| deleted
| module
|-
| portfolio_send
|
|
|
|
|
|
| ''This is a hack...''
|-
| role_assigned
| '''core_event_user_role_added'''
| Someone
| added
| role
| to
| user
| ''Or ..._role_assigned''
|-
| role_unassigned
| '''core_event_user_role_removed'''
| Someone
| removed
| role
| from
| user
| ''Or ..._role_unassigned''
|-
| quiz_attempt_started
| '''mod_quiz_event_attempt_started'''
| Someone
| started
| attempt
| of
| quiz
|-
| test_cron
|-
| test_instant
|-
| user_created
| '''core_event_user_created'''
| Someone
| created
| user
|-
| user_deleted
| '''core_event_user_deleted'''
| Someone
| deleted
| user
|-
| user_enrolled
| '''core_event_user_enrolment_created'''
| Someone
| added
| enrolment
| of
| user
|-
| user_enrol_modified
| '''core_event_user_enrolment_updated'''
| Someone
| updated
| enrolment
| of
| user
|-
| user_unenrolled
| '''core_event_user_enrolment_deleted'''
| Someone
| removed
| enrolment
| of
| user
|-
| user_logout
| '''core_event_loggedout'''
| Someone
| loggedout
|-
| user_updated
| '''core_event_user_updated'''
| Someone
| updated
| user
|-
| workshop_viewed
| '''mod_workshop_event_viewed'''
| Someone
| viewed
| workshop
|-
|}

=== Verb list ===
All events must use a verb from this list. New verbs should be added to this list if required.
{| class="nicetable"
|-
!verb
!Explanation
!Source
|-
|accepted
|Example: Accepting a statement when submitting an assignment.
|Moodle
|-
|added
| Used to represent "something that already exists is now part of/bound to another entity". Examples: "Admin added role to user X", "Admin added user X to group A". Wrong example: "User added course in category" because it is a 'move' action, except if a course can be part of multiple categories. The good examples work because: A user can have multiple roles, a user can be in multiple groups.
|Moodle
|-
|answered
| Indicates the actor responded to a Question
|Tincan
|-
|assessed
| Some submitted material has been assessed
|Moodle
|-
|attempted
|
|Tincan
|-
|awarded
| ex:-teacher awarded student a badge.
|Moodle
|-
|backedup
| When a backup has been performed.
|Moodle
|-
|called
|When a call to something is made like an API @see unknown_service_api_called.php
|Moodle
|-
|commented
|Offered an opinion or written experience of the activity. Can be used with the learner as the actor or a system as an actor. Comments can be sent from either party with the idea that the other will read and react to the content.
|Tincan
|-
|completed
|To experience the activity in its entirety. Used to affirm the completion of content. This can be simply experiencing all the content, be tied to objectives or interactions, or determined in any other way. Any content that has been initialized, but not yet completed, should be considered incomplete. There is no verb to 'incomplete' an activity, one would void the statement which completes the activity."
|Tincan
|-
|created
| Used to represent "something new has been created".
|Moodle
|-
|deleted
| Used to indicate the object in context was deleted.
|Moodle
|-
|duplicated
|For something that has been copied.
|Moodle
|-
|evaluated
| Material has been evaluated.
|Moodle
|-
|failed
|Learner did not perform the activity to a level of pre-determined satisfaction. Used to affirm the lack of success a learner experienced within the learning content in relation to a threshold. If the user performed below the minimum to the level of this threshold, the content is 'failed'. The opposite of 'passed'.
|Tincan
|-
|graded
|Used to represent an activity was graded.
|Moodle
|-
|imported
|The act of moving an object into another location or system.
|Tincan
|-
|loggedin/loggedout
| For login and logout.
|Moodle
|-
|loggedinas
| If user is logged in as different user. This is used by only one event (user_loggedinas). Adding this verb makes event name more clear, then using loggedin verb.
|Moodle
|-
|locked
|
|Moodle
|-
|moved
| Used to indicate the object in context was moved.
|Moodle
|-
|passed
|Used to affirm the success a learner experienced within the learning content in relation to a threshold. If the user performed at a minimum to the level of this threshold, the content is 'passed'. The opposite of 'failed'.
|Tincan
|-
|previewed
|Something has been previewed.
|Moodle
|-
|reassessed
| Submitted material has been assessed again.
|Moodle
|-
|reevaluated
| Material has been evaluated again.
|Moodle
|-
|submitted
|This is very close to "Attempted". Depends on context which one should be used. For example:- "Admin submitted a form. Student attempted a quiz." is correct, however some cases might not be as clear as the previous example. We can say both "Student submitted an assignment" or "student attempted an assignment". We need to make the difference clear.
|Moodle
|-
|suspended
| Suspend something. (example a user)
| Tincan (However the context is different)
|-
|switched
|Something has been switched. For example:- The workshop phase has been switched to assessment"
|Moodle
|-
|viewed
|Something has been viewed. For example:- "Student viewed chapter 1 of book 1."
|Moodle
|-
|registered
|Indicates the actor registered for a learning activity
|Tincan
|-
|removed
|By opposition to "Added". This does not mean that the object has been deleted, but removed from the entity, or not bound to it any more.
|Moodle
|-
|restored
| When restoring a backup. Rolling back to a previous state.
|Moodle
|-
|reset
| Sets one or more properties back to the default value.
|Moodle
|-
|revealed
|Example: Identities revealed after blind marking.
|Moodle
|-
|unlocked
|
|Moodle
|-
|upgraded
|Something was upgraded, some module probably
|Moodle
|-
|updated
|Used to indicate the object in context was updated. Simple example is "Admin updated course xyz".
|Moodle
|-
|}

=== Rules ===

==== Use singular ====

Plurals must be used on objects when it's a ''One to Many'' relationship. Ex: bulk import, mass deletion, ... In any other case, use the singular.

==== Ends with a verb ====

The last word (after the last underscore) must be a verb.

== Shared events ==

Decision: Not supported at this stage.

In Moodle 2.5 we have a good example of a shared event: 'assessable_content_uploaded' which is triggered in ''forum'', 'assignment'' and ''workshop''.

The problem with shared events is that we cannot easily track what component triggered them. Of course we could add a new property to the event to keep track of that, but we would soon need more information and more properties. Also, in the case of a logger, the event received would be unique, where in fact it should be considered different depending on the component firing it.

In our first implementation, we will create one specific event per module. This flexibility does not prevent any observer from capturing them, but still makes sure that the consistency and specificity of each event is maintained.

It could happen that some events are defined in core and shared, but this should not really happen as low-level APIs should trigger the event, and a module should call that low API instead of doing the job itself.

== One to many ==

Decision: Each event should have a one to one relationship. We can reconsider this at a later stage, if the performance hit is extremely high.

In 2.5, some events are triggered when an action happens on multiple objects. We have to decide whether we want to keep supporting ''One to Many'' events or not.

Keeping a list of all changes for multiple actions may be problematic because you would have to keep them all in memory until all things are processed. This might also result in the order of events being incorrect. The only correct solution seems to be to trigger each item individually and then many things at the end. Performance needs to be improved elsewhere...

=== Accuracy ===

When uploading a bunch of users using the CSV upload feature, if only one event is triggered, it means that the observers of ''user_created'' won't be triggered. And so some functionality can be lost as, as a plugin developer, I expect this ''user_created'' to be triggered regardless of the way they have been uploaded. Of course, the developer could observe the event ''bulk_user_imported'', but that means that he could miss some relevant observers.

This applies to existing events.

=== Performance ===

Triggering one event is cheaper then repeating the same events x number of times...

=== Information tracking ===

A ''bulk'' event, might not be verbose enough to allow for proper logging afterwards. Though this is the responsibility of the logger, we probably want to make it easy to store relevant information.

=== Double event ===

In the case of a bulk user import, if we were to trigger an event per user created, we probably want to trigger one event 'user_bulk_upload_started' when the action starts.

== Unit Testing ==

With unit testing for this system we want to assert the following:

* That event strict validation and custom validation works.
* Missing event data is auto filled with accurate data.
* Typos in properties passed to ::create() are captured (if we decide to validate).
* The legacy methods return the expected values (use assertEventLegacyData() and assertEventLegacyData())
* The class properties are correctly overridden (crud, level, action, object, ...).
* The properties automatically generated (component, name, ...) are correct.
* Events are dispatched to the corresponding observers.
* Events are dispatched to the corresponding legacy handlers.
* Events are dispatched to the * observers.
* Events perform an add_to_log() if it has legacy log data.
* 'Events restore' restored the whole event data, and does not miss any information.
* 'Events restore' does not generate any extra information.
* Event methods should check context object or avoid using it, as context might not be valid at time of event restore (use assertEventContextNotUsed())

= Example events =

== Assignment ==

Assumption: Course contains groups with students in each group.

'''1.''' Teacher creates an assignment with group mode set to 'Separate groups' and Feedback type set to comments and files.
*Event: User 'Teacher' has created assignment 'B' in course 'C101'.
'''2.''' A student views the assignment.
*Event: User 'Student' has viewed assignment 'B' in course 'C101'.
'''3.''' A member from one of the groups submits an assignment
*Event: User 'Student' has added a submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''4.''' User 'Adrian' adds some changes to the assignment and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to the teacher and all students in that group.
'''5.''' Teacher views the assignment.
*Event: User 'Teacher' has viewed assignment 'B' in course 'C101'.
'''6.''' Teacher clicks on 'View/grade all submissions'
*Event: User 'Teacher' has viewed the assignment 'B' grade area in course 'C101'.
'''7.''' Teacher clicks to grade the student's submission.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''8.''' Teacher marks the assignment with the setting 'Apply grades and feedback to entire group' set to 'Yes' leaving a comment and a file.
*Event: User 'Teacher' has marked assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for group 'C' in course 'C101'.
*Event: User 'Teacher' has uploaded a file to the course 'C101'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been marked. - This is done for all users in the group.
'''9.''' User 'Adrian' views the feedback.
*Event: User 'Adrian' has viewed assignment 'B' in course 'C101'.
'''10.''' User 'Adrian' opens the feedback file.
*Event: User 'Adrian' has viewed the file 'A' for assignment 'B' in course 'C101'.
'''11.''' User 'Adrian' adds some changes to the assignment insulting the teachers marking and updates it.
*Event: User 'Adrian' has updated the submission for assignment 'B' for group 'C' in course 'C101'.
*Event: Email sent to user 'Teacher' notifying them that user 'Adrian' has updated the submission for assignment 'B'.
*Event: Email sent to user 'Student' notifying them their submission for assignment 'B' has been updated. - This is done for all users in the group.
'''12.''' The teacher clicks directly on the link in the email to be taken to the grading page.
*Event: User 'Teacher' has viewed the submission for user 'student' for assignment 'B' in course 'C101'.
'''13.''' The teacher is upset due to the harsh comments and decides to mark Adrian down, but not the rest of the group by setting 'Apply grades and feedback to entire group' set to 'No'.
*Event: User 'Teacher' has marked assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has left a comment for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: User 'Teacher' has uploaded a feedback file for assignment 'B' for user 'Adrian' in course 'C101'.
*Event: Email sent to user 'Adrian' notifying them their submission for assignment 'B' has been marked.

= FAQs =

; Why not use create events in core subsystems? : Because we could not see all core events in one place, it would create problems when naming event classes and finally subsystems are incomplete, we would have to add more now because we could not move the events in the future.

= Development stages =

== Stage 1 ==

* Finish class loader spec and implement basic Frankenstyle class loader.
* Describe new observer definition - just few new flags in current db/events.php
* Describe new event dispatcher.
* Describe core_event_base class.
* Current (= legacy) events triggering:
** Re-factor current event handling code to new self-contained class - do not change functionality, keep events_trigger().
** Create new event handler management class that deals with installation and upgrades of both legacy and new handlers.
* New events:
** Create new core_event_base class.
** Create new self-contained event dispatcher class with '*' handler support.
** In function core_event_base::trigger() check if the event has property 'legacyeventname' execute events_trigger($this->legacyeventname, $this->legacyeventdata) after triggering new event.
** Write unit tests for all new events code.
* No changes to be made to the current logging system yet.

After completing this stage everything should continue to work as it did before and we can start parallel work on further stages.

== Stage 2 (requires completion of Stage 1) ==

* Create event classes and replace existing calls to events_trigger() and with new event classes containing legacy information properties.
* Add more events throughout the standard Moodle package in places where we have add_to_log(). Implement some_event::get_legacy_log_data() which returns original parameters of add_to_log() and remove it. Old add_to_log() function is called in core_event_base::trigger() automatically with original parameters.
* Add even more new events all over the place.

The difficult part is defining the new event classes properly because we must not change them after the 2.6 release.

== Stage 3 (requires partial completion of Stage 2) ==

* Migrate current legacy event handlers to new handlers with one event class instance parameter, ex.: enrol plugins.

== Stage 4 (requires partial completion of Stage 2) ==

* Implement an event logging handler.
* Implement logging storage plugins.
* Define logging apis.
* Create new reports.
* Switch to new logging everywhere after Stage 2 has been completed and new reports are usable.

See [[Logging 2]]

== Stage 5 ==

* Decide how much backwards compatibility we want for old log tables. Most probably they will get only legacy log data.
* Implement some BC solution for old code that reads log tables directly.

See [[Logging 2]]

== Stage 6 (requires completion of Stage 4 and 5) ==

Moodle 2.8dev? This is the ultimate end of old logging via the ''log'' table.

* Deprecate the add_to_log() function with a debug message and do nothing inside.
* Remove all legacy logging from event classes.

See [[Logging 2]]

Developer meeting January 2014

2014-01-21T13:16:52Z

Emerrill:

[[Developer meetings]] > January 2014 meeting notes

{| class="nicetable"
|-
| Time
| [http://timeanddate.com/worldclock/fixedtime.html?year=2014&month=1&day=21&hour=13&min=0&sec=0 13:00 UTC on Tuesday, 21 January 2014]
|-
| Meeting room
| [http://www.youtube.com/user/moodlehq Moodle HQ YouTube channel] (changed since last meeting)
|-
| Chat
| [https://moodle.org/local/chatlogs/info.php Regular Dev chat]
|-
| Twitter
| [https://twitter.com/search?q=%23moodledev #moodledev]
|}

In this meeting we will focus on Moodle development happening outside Moodle HQ.

The meeting will be streamed live on YouTube with chat through the regular Dev chat room and comments on Twitter.

== Agenda ==
* Quiz editing changes (Tim Hunt, Colin Chamber, Mahmoud Kassaei, OU)
* Possible future changes to Conditional Activities (Sam Marshall, OU)
* Moodle 2.7 progress
** Prototypes site (Martin Dougiamas)
** Clean as default theme (Jérôme Mouneyrac)
*** Should we move most themes to Plugins Directory?
*** Bootstrap 3?
** Editor replacement (Damyon Wiese)
** Old Assignment removal (Damyon Wiese)
** Outcomes (Andrew Davis)
** New logging (Rajesh Taneja)
* Moodle Mobile update (Juan Leyva)
* Integration update (Dan Poltawski)
** Pre-checking of issues by CiBot
** Testing requirements
** Behat improvements
** Misc
* Long term support (Martin Dougiamas)
* A better video conferencing solution for Gen Dev meetings? (Michael de Raadt)

Questions

* What are the plans in 2.7 for Gradebook improvements?
* Will the base theme no longer receive updates or be actively worked on?
* Anymore changes to the event system? We want to start planning/scoping out analytics/alerts using the new event system in 2.6, but don't want to progress if more changes are expected.
* Global Search ?

If you have something you'd like to add to the agenda, please [https://docs.moodle.org/dev/index.php?title=Developer_meeting_January_2014&action=edit edit this page] or contact [http://moodle.org/user/profile.php?id=381842 Michael d].

Moodle 2.6 release notes

2013-10-22T18:19:00Z

Emerrill: /* Other highlights */ MDL-41940 Add new option to disable new files in legacy course files

[[Releases]] > {{FULLPAGENAME}}

=UNDER CONSTRUCTION=

Release date: November 2013 (Not yet released)

See [https://docs.moodle.org/26/en/New_features New features] for a user-friendly tour with screenshots.

===Requirements===

These are just minimums. We recommend keeping all your software updated.

* Recommended minimum browser: recent Google Chrome, recent Mozilla Firefox, Safari 6, Internet Explorer 9 (IE 10 required for drag and drop of files from outside the browser into Moodle)
* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* Minimum DB versions: PostgreSQL 8.3, MySQL 5.1.33, MariaDB 5.2, MSSQL 2005 or Oracle 10.2
* Minimum PHP version: PHP 5.3.3 (always use latest PHP 5.3.x, 5.4.x or 5.5.x on Windows - http://windows.php.net/download/)
* New PHP extensions: zlib extension now recommended

===Known problems===

* IE8 and Safari 5 are not fully supported any more, they should still work but they are not tested regularly and there might be some known problems. Like most of the world's web sites and browser producers, we encourage you to keep your browsers current to improve security and functionality while saving us valuable time. ([http://googleappsupdates.blogspot.ca/2012/09/supporting-modern-browsers-internet.html For example see what Google is doing])
* IE6 and IE7 are not recommended for Moodle 2.6 at all. You would have big problems trying to use those old browsers in today's internet.
* Support for Oracle database is limited, there are known performance and compatibility problems, many add-ons are not compatible. Most of these problems are caused by the fact that Oracle databases do not implement necessary industry SQL standards and contain several legacy limitations. If you are using Oracle or planning to then we highly encourage you to think about using one of the open source databases we support.

===Major new features===

* MDL-31776 - Alternate name fields
* MDL-31830 - Improved category and course management interface
* MDL-13114 - Bulk course creation tool
* MDL-40121 - New Single Activity Course Format (and removed SCORM course format MDL-40122)
* MDL-30740 - Microsoft Skydrive repository
* MDL-17081 - Roles import and export
* MDL-40493 - Users may select preferred text editor
* MDL-37565 - Toolbar switching in TinyMCE editor (one or multiple lines)
* MDL-41866, MDL-18375 - Support for multiple calendars
* MDL-23692 - Simplified recovery of forgotten username and password reset

====Assignment activity====

* MDL-38359 - New marker allocation and grading workflow settings
* MDL-37621 - Admins can set assignment setting defaults
* MDL-42023 - Edit PDF plugin
* MDL-37148 - Lots more webservices

====Forum activity====

* MDL-29663 - Forum read tracking options now Off, Optional, and Forced.
* MDL-41933 - Option to set default read tracking option.
* MDL-4908 - Per-forum digest settings

====Quiz and question bank====

* MDL-32188 - Big improvements to how certainty-based marking (CBM) works. There is now much better feedback for students about how they have done, and what they need to do to improve in future.
* MDL-9873 - Question text is now a required field when creating and editing questions.
* MDL-39155 - Option for what size user picture to show during quiz attempts.

====SCORM activity====

* MDL-28579 / MDL-41580 - Allow use of file aliases and direct linking to imsmanifest.xml inside an extracted zip in the file system repository.
* MDL-39910 - Improved SCORM player with responsive design elements and better support for mobile devices.
* MDL-39926 - New objectives report
* MDL-41290 - Improved user level reporting with ability to export data.
* MDL-41434 - When updating a SCORM package we no longer delete and re-create the scorm_scoes table - we now use a sortorder field.

===Performance===

* MDL-38189 - Restoring of large courses possible
* MDL-40415 - OPcache extension fully supported and recommended
* MDL-31501 - New session drivers supporting files, database and memcached storage
* MDL-40545 - New $CFG->localcachedir setting (intended for clustered servers)
* MDL-40563 - Improved theme resource caching (local cache compatible)
* MDL-40546 - Improved javascript caching (local cache compatible)
* MDL-41019 - Language caching improvements (local cache compatible)
* MDL-41017 - HTMLPurifier caching improvements (local cache compatible)
* MDL-39474 - Developer debug checks improvements
* MDL-38570 - Automatic temp directory cleanup

===Other highlights===

* MDL-40770 - New TinyMCE editor icons
* MDL-39814 - Improved edit icons for usability on all screens
* MDL-11270 - Significantly improved MS SQL Server compatibility
* MDL-39985 - Full MariaDB support
* MDL-19390 - Email notification for new users added manually
* MDL-33955 - Support for open_basedir restriction
* MDL-41245, MDL-41437, MDL-41086 - Multiple installation and upgrade fixes and improvements
* MDL-42078 - Standardised plugin uninstallation and management.
* MDL-37717 - Teachers are warned before suspending own enrolment in course
* MDL-38155 - User enrolment may be suspended via CSV upload
* MDL-16073 - New test pages for external database authentication and enrolment plugins
* MDL-41838 - Backup and restore .mbz files now supports a new .tar.gz internal format (helps with very large courses)
* MDL-41940 - Option to prevent users from adding new files and directories to legacy course files

===Security issues===

* To be published after release.

===For developers: API changes===

* MDL-39854 - Automatic class loader
* MDL-39797 - New events infrastructure
* MDL-41267 - Support for sub-plugins in admin tool plugins
* MDL-26943 - Support for sub-plugins in local plugins
* MDL-20045 - Unofficial support for custom context levels
* MDL-40359 - 3rd party libraries updated to latest versions
* MDL-40305, MDL-40940 - PHPUnit testcase autoloader
* MDL-23493 - Support for including a font through theme CSS
* MDL-40248 - Better support for subplugins in Activity chooser
* MDL-41953 - Plugin name restrictions were relaxed, multiple trailing numbers are allowed
* MDL-42040 - New API for registration of shutdown handlers
* MDL-42148 - New admin page listing all third party libraries, thirdpartylibs.xml now supported in plugins

====Upgrade notes for developers====

;Assignment: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/assign/upgrade.txt;hb=master
;Backup: http://git.moodle.org/gw?p=moodle.git;a=blob;f=backup/upgrade.txt;hb=master
;Cache: http://git.moodle.org/gw?p=moodle.git;a=blob;f=cache/upgrade.txt;hb=master
;Calendar: http://git.moodle.org/gw?p=moodle.git;a=blob;f=calendar/upgrade.txt;hb=master
;Core: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/upgrade.txt;hb=master
;Course formats: http://git.moodle.org/gw?p=moodle.git;a=blob;f=course/format/upgrade.txt;hb=master
;Enrolment plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=enrol/upgrade.txt;hb=master
;Forum: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/forum/upgrade.txt;hb=master
;Question types: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/type/upgrade.txt;hb=master
;Repositories: http://git.moodle.org/gw?p=moodle.git;a=blob;f=repository/upgrade.txt;hb=master
;Themes: http://git.moodle.org/gw?p=moodle.git;a=blob;f=theme/upgrade.txt;hb=master
;TinyMCE plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/editor/tinymce/upgrade.txt;hb=master

<noinclude>
==See also==
* [https://docs.moodle.org/26/en/Category:New_features User documentation of new features in Moodle 2.6]
* [https://docs.moodle.org/26/en/Upgrading_to_Moodle_2.6 Upgrading to Moodle 2.6] - information for admins who are upgrading from earlier versions

[[Category:Release notes]]
[[Category:Moodle 2.6]]

[[es:Notas de Moodle 2.6]]
[[fr:Notes de mise à jour de Moodle 2.6]]
</noinclude>

Moodle 2.6 release notes

2013-10-22T18:17:48Z

Emerrill: /* Quiz and question bank */ Updating question text required description

[[Releases]] > {{FULLPAGENAME}}

=UNDER CONSTRUCTION=

Release date: November 2013 (Not yet released)

See [https://docs.moodle.org/26/en/New_features New features] for a user-friendly tour with screenshots.

===Requirements===

These are just minimums. We recommend keeping all your software updated.

* Recommended minimum browser: recent Google Chrome, recent Mozilla Firefox, Safari 6, Internet Explorer 9 (IE 10 required for drag and drop of files from outside the browser into Moodle)
* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* Minimum DB versions: PostgreSQL 8.3, MySQL 5.1.33, MariaDB 5.2, MSSQL 2005 or Oracle 10.2
* Minimum PHP version: PHP 5.3.3 (always use latest PHP 5.3.x, 5.4.x or 5.5.x on Windows - http://windows.php.net/download/)
* New PHP extensions: zlib extension now recommended

===Known problems===

* IE8 and Safari 5 are not fully supported any more, they should still work but they are not tested regularly and there might be some known problems. Like most of the world's web sites and browser producers, we encourage you to keep your browsers current to improve security and functionality while saving us valuable time. ([http://googleappsupdates.blogspot.ca/2012/09/supporting-modern-browsers-internet.html For example see what Google is doing])
* IE6 and IE7 are not recommended for Moodle 2.6 at all. You would have big problems trying to use those old browsers in today's internet.
* Support for Oracle database is limited, there are known performance and compatibility problems, many add-ons are not compatible. Most of these problems are caused by the fact that Oracle databases do not implement necessary industry SQL standards and contain several legacy limitations. If you are using Oracle or planning to then we highly encourage you to think about using one of the open source databases we support.

===Major new features===

* MDL-31776 - Alternate name fields
* MDL-31830 - Improved category and course management interface
* MDL-13114 - Bulk course creation tool
* MDL-40121 - New Single Activity Course Format (and removed SCORM course format MDL-40122)
* MDL-30740 - Microsoft Skydrive repository
* MDL-17081 - Roles import and export
* MDL-40493 - Users may select preferred text editor
* MDL-37565 - Toolbar switching in TinyMCE editor (one or multiple lines)
* MDL-41866, MDL-18375 - Support for multiple calendars
* MDL-23692 - Simplified recovery of forgotten username and password reset

====Assignment activity====

* MDL-38359 - New marker allocation and grading workflow settings
* MDL-37621 - Admins can set assignment setting defaults
* MDL-42023 - Edit PDF plugin
* MDL-37148 - Lots more webservices

====Forum activity====

* MDL-29663 - Forum read tracking options now Off, Optional, and Forced.
* MDL-41933 - Option to set default read tracking option.
* MDL-4908 - Per-forum digest settings

====Quiz and question bank====

* MDL-32188 - Big improvements to how certainty-based marking (CBM) works. There is now much better feedback for students about how they have done, and what they need to do to improve in future.
* MDL-9873 - Question text is now a required field when creating and editing questions.
* MDL-39155 - Option for what size user picture to show during quiz attempts.

====SCORM activity====

* MDL-28579 / MDL-41580 - Allow use of file aliases and direct linking to imsmanifest.xml inside an extracted zip in the file system repository.
* MDL-39910 - Improved SCORM player with responsive design elements and better support for mobile devices.
* MDL-39926 - New objectives report
* MDL-41290 - Improved user level reporting with ability to export data.
* MDL-41434 - When updating a SCORM package we no longer delete and re-create the scorm_scoes table - we now use a sortorder field.

===Performance===

* MDL-38189 - Restoring of large courses possible
* MDL-40415 - OPcache extension fully supported and recommended
* MDL-31501 - New session drivers supporting files, database and memcached storage
* MDL-40545 - New $CFG->localcachedir setting (intended for clustered servers)
* MDL-40563 - Improved theme resource caching (local cache compatible)
* MDL-40546 - Improved javascript caching (local cache compatible)
* MDL-41019 - Language caching improvements (local cache compatible)
* MDL-41017 - HTMLPurifier caching improvements (local cache compatible)
* MDL-39474 - Developer debug checks improvements
* MDL-38570 - Automatic temp directory cleanup

===Other highlights===

* MDL-40770 - New TinyMCE editor icons
* MDL-39814 - Improved edit icons for usability on all screens
* MDL-11270 - Significantly improved MS SQL Server compatibility
* MDL-39985 - Full MariaDB support
* MDL-19390 - Email notification for new users added manually
* MDL-33955 - Support for open_basedir restriction
* MDL-41245, MDL-41437, MDL-41086 - Multiple installation and upgrade fixes and improvements
* MDL-42078 - Standardised plugin uninstallation and management.
* MDL-37717 - Teachers are warned before suspending own enrolment in course
* MDL-38155 - User enrolment may be suspended via CSV upload
* MDL-16073 - New test pages for external database authentication and enrolment plugins
* MDL-41838 - Backup and restore .mbz files now supports a new .tar.gz internal format (helps with very large courses)

===Security issues===

* To be published after release.

===For developers: API changes===

* MDL-39854 - Automatic class loader
* MDL-39797 - New events infrastructure
* MDL-41267 - Support for sub-plugins in admin tool plugins
* MDL-26943 - Support for sub-plugins in local plugins
* MDL-20045 - Unofficial support for custom context levels
* MDL-40359 - 3rd party libraries updated to latest versions
* MDL-40305, MDL-40940 - PHPUnit testcase autoloader
* MDL-23493 - Support for including a font through theme CSS
* MDL-40248 - Better support for subplugins in Activity chooser
* MDL-41953 - Plugin name restrictions were relaxed, multiple trailing numbers are allowed
* MDL-42040 - New API for registration of shutdown handlers
* MDL-42148 - New admin page listing all third party libraries, thirdpartylibs.xml now supported in plugins

====Upgrade notes for developers====

;Assignment: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/assign/upgrade.txt;hb=master
;Backup: http://git.moodle.org/gw?p=moodle.git;a=blob;f=backup/upgrade.txt;hb=master
;Cache: http://git.moodle.org/gw?p=moodle.git;a=blob;f=cache/upgrade.txt;hb=master
;Calendar: http://git.moodle.org/gw?p=moodle.git;a=blob;f=calendar/upgrade.txt;hb=master
;Core: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/upgrade.txt;hb=master
;Course formats: http://git.moodle.org/gw?p=moodle.git;a=blob;f=course/format/upgrade.txt;hb=master
;Enrolment plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=enrol/upgrade.txt;hb=master
;Forum: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/forum/upgrade.txt;hb=master
;Question types: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/type/upgrade.txt;hb=master
;Repositories: http://git.moodle.org/gw?p=moodle.git;a=blob;f=repository/upgrade.txt;hb=master
;Themes: http://git.moodle.org/gw?p=moodle.git;a=blob;f=theme/upgrade.txt;hb=master
;TinyMCE plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/editor/tinymce/upgrade.txt;hb=master

<noinclude>
==See also==
* [https://docs.moodle.org/26/en/Category:New_features User documentation of new features in Moodle 2.6]
* [https://docs.moodle.org/26/en/Upgrading_to_Moodle_2.6 Upgrading to Moodle 2.6] - information for admins who are upgrading from earlier versions

[[Category:Release notes]]
[[Category:Moodle 2.6]]

[[es:Notas de Moodle 2.6]]
[[fr:Notes de mise à jour de Moodle 2.6]]
</noinclude>

Moodle 2.6 release notes

2013-10-11T13:21:53Z

Emerrill: /* Forum activity */ Fixed typo

[[Releases]] > {{FULLPAGENAME}}

=UNDER CONSTRUCTION=

Release date: November 2013 (Not yet released)

===Requirements===

These are just minimums. We recommend keeping all your software updated.

* Recommended minimum browser: recent Google Chrome, recent Mozilla Firefox, Safari 6, Internet Explorer 9 (IE 10 required for drag and drop of files from outside the browser into Moodle)
* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* Minimum DB versions: PostgreSQL 8.3, MySQL 5.1.33, MariaDB 5.2, MSSQL 2005 or Oracle 10.2
* Minimum PHP version: PHP 5.3.3 (always use latest PHP 5.3.x, 5.4.x or 5.5.x on Windows - http://windows.php.net/download/)
* New PHP extensions: zlib extension now recommended

NOTE: IE8 and Safari 5 are not fully supported any more, they should still work but they are not tested regularly and there might be some known problems, IE6 and IE7 are not compatible with Moodle. Like most of the world's web sites and browser producers, we encourage you to keep your browsers current to improve security and functionality while saving us valuable time. ([http://googleappsupdates.blogspot.ca/2012/09/supporting-modern-browsers-internet.html For example see what Google is doing])

===Major new features===

* MDL-31776 - Alternate name fields
* MDL-13114 - Bulk course creation tool
* MDL-40121 - New Single Activity Course Format (and removed SCORM course format MDL-40122)
* MDL-30740 - Microsoft Skydrive repository
* MDL-17081 - Roles import and export
* MDL-41098 - New Atto simple text editor suitable for iOS devices
* MDL-37565 - Toolbar switching in TinyMCE editor (one or multiple lines)
* MDL-41866 - Multiple calendar support (MDL-18375 was the original issue but it was decided we would split this into two separate tasks, hence the newly created epic).

====Assignment activity====

* MDL-38359 - New marker allocation and grading workflow settings
* MDL-37621 - Admins can set assignment setting defaults
* MDL-42023 - Edit PDF plugin
* MDL-37148 - Lots more webservices

====Forum activity====

* MDL-29663 - Forum read tracking options now Off, Optional, and Forced.
* MDL-41933 - Option to set default read tracking option.

====SCORM activity====

* MDL-28579 / MDL-41580 - Allow use of file aliases and direct linking to imsmanifest.xml inside an extracted zip in the file system repository.
* MDL-39910 - Improved SCORM player with responsive design elements and better support for mobile devices.
* MDL-39926 - New objectives report
* MDL-41290 - Improved user level reporting with ability to export data.
* MDL-41434 - When updating a SCORM package we no longer delete and re-create the scorm_scoes table - we now use a sortorder field.

===Performance===

* MDL-40415 - OPcache extension fully supported and recommended
* MDL-31501 - New session drivers supporting files, database and memcached storage
* MDL-40545 - New $CFG->localcachedir setting (intended for clustered servers)
* MDL-40563 - Improved theme resource caching (local cache compatible)
* MDL-40546 - Improved javascript caching (local cache compatible)
* MDL-41019 - Language caching improvements (local cache compatible)
* MDL-41017 - htmlpurifier caching improvements (local cache compatible)
* MDL-39474 - Developer debug checks improvements
* MDL-38570 - automatic temp directory cleanup

===Other highlights===

* MDL-40770 - New TinyMCE editor icons
* MDL-11270 - Significantly improved MS SQL Server compatibility
* MDL-39985 - Full MariaDB support
* MDL-19390 - Email notification for new users added manually
* MDL-33955 - Support for open_basedir restriction
* MDL-9873 - Question text now required
* MDL-41245, MDL-41437, MDL-41086 - Multiple installation and upgrade fixes and improvements

===Security issues===

* To be published after release.

===For developers: API changes===

* MDL-39854 - Automatic class loader
* MDL-39797 - New events infrastructure
* MDL-41267 - Support for sub-plugins in admin tool plugins
* MDL-26943 - Support for sub-plugins in local plugins
* MDL-20045 - Unofficial support for custom context levels
* MDL-40359 - 3rd party libraries updated to latest versions
* MDL-40305, MDL-40940 - PHPUnit testcase autoloader
* MDL-23493 - Support for including a font through theme CSS
* MDL-35434 - File picker available in themes settings
* MDL-40248 - better support for subplugins in Activity chooser

====Upgrade notes for developers====

;Assignment: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/assign/upgrade.txt;hb=master
;Backup: http://git.moodle.org/gw?p=moodle.git;a=blob;f=backup/upgrade.txt;hb=master
;Cache: http://git.moodle.org/gw?p=moodle.git;a=blob;f=cache/upgrade.txt;hb=master
;Calendar: http://git.moodle.org/gw?p=moodle.git;a=blob;f=calendar/upgrade.txt;hb=master
;Core: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/upgrade.txt;hb=master
;Course formats: http://git.moodle.org/gw?p=moodle.git;a=blob;f=course/format/upgrade.txt;hb=master
;Enrolment plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=enrol/upgrade.txt;hb=master
;Forum: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/forum/upgrade.txt;hb=master
;Question types: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/type/upgrade.txt;hb=master
;Repositories: http://git.moodle.org/gw?p=moodle.git;a=blob;f=repository/upgrade.txt;hb=master
;Themes: http://git.moodle.org/gw?p=moodle.git;a=blob;f=theme/upgrade.txt;hb=master
;TinyMCE plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/editor/tinymce/upgrade.txt;hb=master

<noinclude>

[[Category:Release notes]]
[[Category:Moodle 2.6]]

[[es:Notas de Moodle 2.6]]
[[fr:Notes de mise à jour de Moodle 2.6]]
</noinclude>

Moodle 2.6 release notes

2013-10-11T13:21:10Z

Emerrill: /* UNDER CONSTRUCTION */

[[Releases]] > {{FULLPAGENAME}}

=UNDER CONSTRUCTION=

Release date: November 2013 (Not yet released)

===Requirements===

These are just minimums. We recommend keeping all your software updated.

* Recommended minimum browser: recent Google Chrome, recent Mozilla Firefox, Safari 6, Internet Explorer 9 (IE 10 required for drag and drop of files from outside the browser into Moodle)
* Moodle upgrade: Moodle 2.2 or later (if upgrading from earlier versions, you must upgrade to 2.2.11 as a first step)
* Minimum DB versions: PostgreSQL 8.3, MySQL 5.1.33, MariaDB 5.2, MSSQL 2005 or Oracle 10.2
* Minimum PHP version: PHP 5.3.3 (always use latest PHP 5.3.x, 5.4.x or 5.5.x on Windows - http://windows.php.net/download/)
* New PHP extensions: zlib extension now recommended

NOTE: IE8 and Safari 5 are not fully supported any more, they should still work but they are not tested regularly and there might be some known problems, IE6 and IE7 are not compatible with Moodle. Like most of the world's web sites and browser producers, we encourage you to keep your browsers current to improve security and functionality while saving us valuable time. ([http://googleappsupdates.blogspot.ca/2012/09/supporting-modern-browsers-internet.html For example see what Google is doing])

===Major new features===

* MDL-31776 - Alternate name fields
* MDL-13114 - Bulk course creation tool
* MDL-40121 - New Single Activity Course Format (and removed SCORM course format MDL-40122)
* MDL-30740 - Microsoft Skydrive repository
* MDL-17081 - Roles import and export
* MDL-41098 - New Atto simple text editor suitable for iOS devices
* MDL-37565 - Toolbar switching in TinyMCE editor (one or multiple lines)
* MDL-41866 - Multiple calendar support (MDL-18375 was the original issue but it was decided we would split this into two separate tasks, hence the newly created epic).

====Assignment activity====

* MDL-38359 - New marker allocation and grading workflow settings
* MDL-37621 - Admins can set assignment setting defaults
* MDL-42023 - Edit PDF plugin
* MDL-37148 - Lots more webservices

====Forum activity====

* MDL-29663 - Forum read tracking options now Off, On, and Forced.
* MDL-41933 - Option to set default read tracking option.

====SCORM activity====

* MDL-28579 / MDL-41580 - Allow use of file aliases and direct linking to imsmanifest.xml inside an extracted zip in the file system repository.
* MDL-39910 - Improved SCORM player with responsive design elements and better support for mobile devices.
* MDL-39926 - New objectives report
* MDL-41290 - Improved user level reporting with ability to export data.
* MDL-41434 - When updating a SCORM package we no longer delete and re-create the scorm_scoes table - we now use a sortorder field.

===Performance===

* MDL-40415 - OPcache extension fully supported and recommended
* MDL-31501 - New session drivers supporting files, database and memcached storage
* MDL-40545 - New $CFG->localcachedir setting (intended for clustered servers)
* MDL-40563 - Improved theme resource caching (local cache compatible)
* MDL-40546 - Improved javascript caching (local cache compatible)
* MDL-41019 - Language caching improvements (local cache compatible)
* MDL-41017 - htmlpurifier caching improvements (local cache compatible)
* MDL-39474 - Developer debug checks improvements
* MDL-38570 - automatic temp directory cleanup

===Other highlights===

* MDL-40770 - New TinyMCE editor icons
* MDL-11270 - Significantly improved MS SQL Server compatibility
* MDL-39985 - Full MariaDB support
* MDL-19390 - Email notification for new users added manually
* MDL-33955 - Support for open_basedir restriction
* MDL-9873 - Question text now required
* MDL-41245, MDL-41437, MDL-41086 - Multiple installation and upgrade fixes and improvements

===Security issues===

* To be published after release.

===For developers: API changes===

* MDL-39854 - Automatic class loader
* MDL-39797 - New events infrastructure
* MDL-41267 - Support for sub-plugins in admin tool plugins
* MDL-26943 - Support for sub-plugins in local plugins
* MDL-20045 - Unofficial support for custom context levels
* MDL-40359 - 3rd party libraries updated to latest versions
* MDL-40305, MDL-40940 - PHPUnit testcase autoloader
* MDL-23493 - Support for including a font through theme CSS
* MDL-35434 - File picker available in themes settings
* MDL-40248 - better support for subplugins in Activity chooser

====Upgrade notes for developers====

;Assignment: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/assign/upgrade.txt;hb=master
;Backup: http://git.moodle.org/gw?p=moodle.git;a=blob;f=backup/upgrade.txt;hb=master
;Cache: http://git.moodle.org/gw?p=moodle.git;a=blob;f=cache/upgrade.txt;hb=master
;Calendar: http://git.moodle.org/gw?p=moodle.git;a=blob;f=calendar/upgrade.txt;hb=master
;Core: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/upgrade.txt;hb=master
;Course formats: http://git.moodle.org/gw?p=moodle.git;a=blob;f=course/format/upgrade.txt;hb=master
;Enrolment plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=enrol/upgrade.txt;hb=master
;Forum: http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/forum/upgrade.txt;hb=master
;Question types: http://git.moodle.org/gw?p=moodle.git;a=blob;f=question/type/upgrade.txt;hb=master
;Repositories: http://git.moodle.org/gw?p=moodle.git;a=blob;f=repository/upgrade.txt;hb=master
;Themes: http://git.moodle.org/gw?p=moodle.git;a=blob;f=theme/upgrade.txt;hb=master
;TinyMCE plugins: http://git.moodle.org/gw?p=moodle.git;a=blob;f=lib/editor/tinymce/upgrade.txt;hb=master

<noinclude>

[[Category:Release notes]]
[[Category:Moodle 2.6]]

[[es:Notas de Moodle 2.6]]
[[fr:Notes de mise à jour de Moodle 2.6]]
</noinclude>

User:Eric Merrill

2013-09-12T22:15:30Z

Emerrill: Setting up a bare page for myself

Eric Merrill is a Learning Management Programmer at [http://www.oakland.edu Oakland University].

Eric writes and maintains the [https://moodle.org/plugins/view.php?plugin=enrol_lmb Banner/Luminis Message Broker] enrollment plugin.

Security:Insecure configuration management

2013-09-12T22:00:33Z

Emerrill: Update to represent more recent version of Moodle (and using git).

This page forms part of the [[Security|Moodle security guidelines]].

==What is the danger?==

Evil Hacker somehow gets access to your server some time and installs some nasty code. For example, they could add some code to the login page that records every username and password entered, and sends it back to evel-hacker.com.

Unfortunately, you have no procedures in place for detecting that this is happening.

Another problem is not updating to the latest Moodle release, which means that you will be running a version of Moodle with know security holes.

==How Moodle avoids this problem==

This is not really a problem that can be solved from within Moodle code. However, any Moodle code that does install other PHP code (for example admin/langimport.php) must be written with extreme care.

==What you need to do in your code==

* If you are writing code like admin/langimport.php, make sure you know what you are doing.

==What you need to do as an administrator==

* Keep up-to-date with the latest Moodle release from whichever branch you are using.
** Register your Moodle site, so you get notified of security problems before the general public.
* Think about how you deploy the Moodle code to your server. For example, if you [[:en:Git_for_Administrators|use git]], then 'git status' will tell you which files have been edited.
** Alternatively, if you upload the Moodle code manually, delete all the old code except config.php before you upload a new version.
* Be very careful who can access your servers.

==See also==

* [[Security]]
* [[Coding]]

[[Category:Security]]

Acceptance testing

2013-05-15T13:32:06Z

Emerrill: /* Advanced usage */ Adding instructions for different browsers

== Introduction ==
This page describes how we describe Moodle's functionalities and how we automatically test all of them.

Behat is a behavioural driven development (BDD) tool written in PHP, it can parse a human-readable list of sentences (called steps) and execute actions in a browser using Selenium or other tools to simulate users interactions.

For technical info: https://docs.moodle.org/dev/Behat_integration

=== How it works ===
Behat parses and executes features files which describes Moodle's features (for example ''Post in a forum''), each feature file is composed by many scenarios (for example ''Add a post to a discussion'' or ''Create a new discussion''), and finally each scenario is composed by steps (for example ''I press "Post to Forum"'' or ''I should see "My post title"''). When the feature file is executed, every step internally is translated into an PHP method and is executed.

This features are executed nightly in the HQ servers with all the supported databases (MySQL, PostgreSQL, MSSQL and Oracle) and with different browsers (Firefox, Internet Explorer, Safari and Chrome) to avoid regressions and test new functionalities.

=== Examples ===

* There is a closed list of steps to use in the features, a feature written with the basic (or low-level) steps looks like this:
@auth
'''Feature''': Login
In order to login
As a moodle user
I need to be able to validate the username and password against moodle

'''Scenario''': Login as an existing user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

'''Scenario''': Login as an unexisting user
Given I am on "login/index.php"
When I fill in "username" with "admin"
And I fill in "password" with "moodle"
And I press "loginbtn"
Then I should see "Moodle 101: Course Name"

Note that The 3 sentences below ''Feature: Login'' are only information about what we want to test.

These are simple scenarios, but most of Moodle's functionalities would require a huge list of this steps to test a scenario, imagine a ''Add a post to a discussion'' scenario; you need to login, create a course, create a user and enrol it in the course... Most of this steps is not what we intend to test in a ''Post in a forum'' feature, Moodle provides extra steps to quickly set up the context required to test a Moodle feature, for example:

@mod @mod_forum
'''Feature''': Add forum activities and discussions
In order to discuss topics with other users
As a moodle teacher
I need to add forum activities to moodle courses

'''Scenario''': Add a forum and a discussion
'''Given''' the following "users" exists:
| username | firstname | lastname | email |
| teacher1 | Teacher | 1 | teacher1@asd.com |
'''And''' the following "courses" exists:
| fullname | shortname | category |
| Course 1 | C1 | 0 |
'''And''' the following "course enrolments" exists:
| user | course | role |
| teacher1 | C1 | editingteacher |
'''And''' I log in as "teacher1"
'''And''' I follow "Course 1"
'''And''' I turn editing mode on
'''And''' I add a "Forum" to section "1" and I fill the form with:
| Forum name | Test forum name |
| Forum type | Standard forum for general use |
| Description | Test forum description |
'''When''' I add a new discussion to "Test forum name" forum with:
| Subject | Forum post subject |
| Message | This is the body |
'''Then''' I should see "Test forum name"

Note that:

* Each scenario is executed in an isolated testing environment, so the first step begins with an empty moodle site and what you set up in an scenario (like the ''Test forum name'' forum in the example above) is cleaned up after the scenario execution
* The prefixes "Given", "When" and "Then" are only informative and they are used to define the context (Given), specify the action (When) and check the results (Then), using them properly helps to understand what the scenario is testing.

== Quick start ==

This is a quick introduction to write a functional test (acceptance tests) using steps in a development/testing site, please DON'T USE THIS IN A PRODUCTION SITE.

To let you experience the pleasure of watching a feature file doing "your work" automatically in a real browser, this guide includes 2 optional steps to download Selenium and run it in another CLI.

# Open a command line interface
# '''cd /to/your/moodle/dirroot'''
# Edit config.php adding the following lines before the lib/setup.php include
#: <code language="text">$CFG->behat_prefix = 'b_';
$CFG->behat_dataroot = '/path/to/your/behat/dataroot/directory';
$CFG->behat_switchcompletely = true;
</code>
# '''curl http://getcomposer.org/installer | php''' (In case you have problems read https://docs.moodle.org/dev/Acceptance_testing#Installation)
# '''php admin/tool/behat/cli/init.php'''
# Download selenium-server-standalone-2.NN.N.jar from http://seleniumhq.org/download/, under "Selenium server (formerly the Selenium RC Server)"
# Open another command line interface and run '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml'''
# You just ran the current Moodle tests, now let's add your own test, add a blog entry for example
# Browse to your $CFG->wwwroot, this is an empty test site and it is reset before each test (called scenario)
# From this point follow the steps you would follow to add manually a blog entry (login credentials are admin/admin)
# When you are done go to 'Site administration' -> 'Development' -> 'Acceptance testing', you will find the list of "actions" that can be run automatically, you can filter them to find what do you need to do (more steps can be added if you need, more info in https://docs.moodle.org/dev/Acceptance_testing#Adding_steps_definitions)
# To 'add a blog entry' we need to:
## Log in the system as a valid user
## Expand 'My profile' node of the navigation block
## Expand the 'Blogs' node of the navigation block
## Follow he 'Add a new entry' link
## Fill the moodle form with values for 'Entry title' and 'Blog entry body'
## Press the 'Save changes' button
## Verify you see the values you entered in the form and verify you are not in the form page
# This translated to steps is:
#: <code language="text">Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "Blog entries"
And I should see "I'm the description"
And I should not see "Required"
</code>
# We need to wrap this steps following the behaviour driven development guidelines (more info in https://docs.moodle.org/dev/Acceptance_testing#Writing_features)
#: <code language="text">
@core @core_blog
Feature: Add a blog entry
In order to let the world know about me
As a user
I need to write blog entries

@javascript
Scenario: Add a blog entry with valid data
Given I log in as "admin"
And I expand "My profile" node
And I expand "Blogs" node
And I follow "Add a new entry"
And I fill the moodle form with:
| Entry title | I'm the name |
| Blog entry body | I'm the description |
When I press "Save changes"
Then I should see "View all of my entries"
And I should see "I'm a description"
And I should not see "Required"
</code>
# And save it into a file, in this case '''blog/tests/behat/add_entry.feature'''
# '''php admin/tool/behat/cli/util.php --enable''' (This will update the available tests and steps definitions)
# '''vendor/bin/behat --config /path/to/your/behat/dataroot/directory/behat/behat.yml --tags @core_blog'''
# Selenium will open a browser (firefox by default) and you will see how the steps you have been writting are executed

You can also try to expand non existing nodes or change the 'Then' assertions to get a beautiful failure.

For detailed steps and/or troubleshooting:
* https://docs.moodle.org/dev/Acceptance_testing#Running_tests
* https://docs.moodle.org/dev/Acceptance_testing#Writing_features

== Requirements ==
* PHP 5.4 (see https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage for PHP 5.3, only for non-production sites)
* Other dependencies are managed by the composer installer

== Installation ==
* Edit config.php
** Use $CFG->behat_dataroot to set the directory where behat test environment dataroot will be stored, something like '''$CFG->behat_dataroot = '/your/directory/path';'''. Ensure the directory can be created or have write permissions
** Use $CFG->behat_prefix to set the database prefix of the behat test environment database tables, something like '''$CFG->behat_prefix = 'behat_';'''
* Download composer
** '''cd /your/moodle/dirroot'''
** '''curl http://getcomposer.org/installer | php'''
*** If you don't have curl installed or you have problems running '''curl http://getcomposer.org/installer | php''':
**** Download '''http://getcomposer.org/installer'''
**** Store it in /your/moodle/dirroot/composerinstaller.php for example
**** Run it from /your/moodle/dirroot with '''php composerinstaller.php''', you can delete this file after running the next step ('''php composer.phar update --dev''')
* Install behat dependencies and enable the test environment
** '''cd /your/moodle/dirroot'''
** '''php admin/tool/behat/cli/init.php'''
* (Optional) If you want to run tests that involves Javascript (most of them) you will also need Selenium
** Download it from http://seleniumhq.org/download/, named "Selenium server (formerly the Selenium RC Server)"

== Running tests ==
# Start the PHP built-in web server
#* Open a command line interface and '''cd /to/your/moodle/dirroot'''
#* '''php -S localhost:8000''' (This is the default address, if you want to use another one you can override it in config.php with $CFG->behat_wwwroot attribute; more info in https://docs.moodle.org/dev/Acceptance_testing#Advanced_usage)
# (Optional) Start the Selenium server (in case you want to run tests that involves Javascript)
#* Open another command line interface and '''java -jar /path/to/your/selenium/server/selenium-server-standalone-2.NN.N.jar'''
# Run Behat
#* '''vendor/bin/behat --config /path/to/your/CFG_behat_dataroot/behat/behat.yml''' (For more options '''vendor/bin/behat --help''' or http://docs.behat.org/guides/6.cli.html)
#* In case you don't want to run Javascript tests use the Behat tags option to skip them, '''vendor/bin/behat --tags ~@javascript --config /path/to/your/CFG_behat_dataroot/behat/behat.yml'''
# (Optional) If you are adding new tests or steps definitions update the tests list:
#* '''php admin/tool/behat/cli/util.php --enable'''
# (Optional) Disable test environment (in case you want to use the PHP built-in web server for regular moodle environment)
#* '''php admin/tool/behat/cli/util.php --disable'''

=== Tests filters ===
With the '''--tags''' or the '''-name''' Behat options you can filter which tests are going to run or which ones are going to be skipped. There are few tags that you might be interested in:
* '''@javascript''': All the tests that runs in a browser using Javascript; they require Selenium to be running, otherwise an exception will be thrown.
* '''@_only_local''': All the tests that involves file uploading or any OS feature that is not 100% part of the browser. They should only be executed when Selenium is running in the same machine where the tests are running.
* '''@_cross_browser''': All the tests that should run against multiple combinations of browsers + OS in a regular basis. The features that are sensitive to different combinations of OS and browsers should be tagges as @_cross_browser.
* '''@componentname''': Moodle features uses the [https://docs.moodle.org/dev/Frankenstyle Frankenstyle] component name to tag the features according to the Moodle subsystem they belong to.

== Advanced usage ==
There are a few settings for advanced use of Behat and execution in continuous integration systems, by default all this options are disabled, use this settings only if you know what you are doing.

* '''Different test server URL''', by default the test web server only can be accessed in localhost. If for example your are interested in allowing accesses from your local network because your Jenkins server is there you can set $CFG->behat_wwwroot to '''http://my.computer.local.ip:8000'''
* '''Behat configuration''', Moodle writes a behat.yml config file with info about the available tests and steps definitions along with other Behat parameters, you can override the Behat parameters we set and add your new parameters, your parameters will be merged with the Moodle ones giving priority to your values in case of conflict. This is useful for an advanced use of Behat, with multiple profiles, output formats, integration with continuous servers...
* '''Running with a browser other than Firefox''', by adding the following code to your config.php you can change the selected browser that is run when behat is invoked. In this case Chrome is selected, but internet explorer, firefox, iphone, android, chrome, htmlunit should be valid options. You will need to run '''php admin/tool/behat/cli/init.php''' for changes to take effect.
<code language="text">
$CFG->behat_config = array(
'default' => array(
'extensions' => array(
'Behat\MinkExtension\Extension' => array(
'selenium2' => array(
'browser' => 'chrome'
)
)
)
)
);
</code>
:Note that for Chrome, you will need the Selenium Chrome Driver (https://code.google.com/p/selenium/wiki/ChromeDriver), and it will need to be installed in the command search path.
* '''Switch completely to test environment''', DON'T USE THIS SETTING IN PRODUCTION SITES! all the site users would be using the test environment instead of the regular one with your courses and all your data and they wouldn't be able to login in your site; this setting should only be used in development/testing installations. It's purpose is to ease the integration with cloud-based continuous integration systems, another possible use is to allow acceptance testing in a development environment without PHP 5.4.
** Note that when using cloud-based systems that can make use of non-standard capabilities like Saucelabs, you might want to provide configuration attributes containing the ''''-'''' character, which is automatically converted to ''''_'''' by the Symfony configuration manager that Behat is making use of (@see Symfony\Component\Config\Definition\Processor::normalizeKeys()) a way to avoid this restriction is to, adding to the vars you set like ''''max-duration'''' add the same var replacing dashes for underscores, this way the configuration manager will maintain the attribute containing dashes.
You can find more info and examples of how to use this settings in the config-dist.php file included in the Moodle codebase.

== Writing features ==

All Moodle components and plugins (including 3rd party plugins) can specify their tests in .feature files using all the available steps.

Once you decided which functionality you want to specify as a feature you should:
# Select the most appropriate Moodle component to include your test and create a COMPONENTNAME/tests/behat/FEATURENAME.feature file
# Add a tag with the component name in Frankenstyle format (https://docs.moodle.org/dev/Frankenstyle) on the first line along with the plugin type or @core if it's a core subsystem
# Begin writing the user story of the feature, including in the 'As a ...' statement the main beneficiary of the feature:
#: <code lang="text">@plugintype @plugintype_pluginname
Feature: FEATURENAME
In order to ... // Why this feature is useful
As ... // It can be 'an admin', 'a teacher', 'a student', 'a guest', 'a user', 'a tests writer' and 'a developer'
I need to ... // The feature we want</code>
# From the beneficiary point of view, think of different scenarios to ensure the feature works as expected
# For each scenario you thought:
## Think of the initial context you need, for example ''1 course with 2 students on it and an assignment'', and which steps do you need to follow (interacting with the browser) to verify the scenario works as expected
## What you are testing requires Javascript? Think only on the feature you are testing (for example if you want to test that you can view your profile you don't need Javascript to click on a link and assert against plain HTML, but if you want to test something related with the course's gradebook you might want to test it with Javascript)
## Check the steps list (more info in https://docs.moodle.org/dev/Acceptance_testing#Available_steps) and set the initial context data (see https://docs.moodle.org/dev/Acceptance_testing#Fixtures for more info) and the steps to follow to verify all works as it should work. Remember to use ''Given'', ''When'' and ''Then'' in a way that reflects what the scenario is testing
## Copy the list of steps to the .feature file with the Scenario header:
##: <code lang="text">Scenario: Short description of the scenario
Given step 1
And step 2
And step 3
When step 4
And step 5
Then step 6</code>
## If the steps you are using requires Javascript add the @javascript tag above the "Scenario:" headline
##: <code lang="text">@javascript
Scenario: Short description of the scenario
...
...</code>
# Run the tests, when creating your new features/scenarios you can specify a '@wip' (work in progress) tag in both the line above the Scenario description and the tests runner (vendor/bin/behat) to execute only the new scenario instead of running the whole set of tests.
# Add extra tags to the scenario or the feature if required
#* If there are scenarios that includes files uploads they should be tagged as @_only_local
#* If there are scenarios that are likely to fail in some browser-OS combinations they can be tagged as @_cross_browser, they will be tested in different OS / browser combinations by Moodle HQ continuous integration servers

=== Available steps ===

Moodle provides a interface to list and filter the steps you can use when writing features. You can access it through the Administration block, following '''Site Administration''' -> '''Development''' -> '''Acceptance testing'''. It allows filtering by keyword, by the Moodle component or by the type of step:
* Processes to set up the environment
* Actions that provokes an event
* Checkings to ensure the outcomes are the expected ones

[[File:Acceptance_testing_UI_2.5.png]]

=== Tips ===
* You can use a '''Background''' section before the '''Scenario''' sections, this steps will be executed before the steps of each scenario (http://docs.behat.org/guides/1.gherkin.html#backgrounds)
* Is better to tests the outcomes against the given data than against language strings, which are depending on the selected language.
* In case you need to interact with popup windows you need to switch to the window you want to interact with after opening it using the '''I switch to "popupwindowname" window''', close it when you finish interacting with it and return to the main window using '''I switch to main window'''
* The format of the .feature files is YAML which finds out the data hierarchy from the indentation of it's elements, so be sure that the elements are correctly nested and the indentation is correct using spaces when necessary

=== Providing values to steps ===
Most of the steps requires values, there are four methods to provide values to steps, the method depends on the step specification, you can know when a steps requires a value because you will see a drop down menu with a closed list of options that the step accepts as argument or an upper case string between double quotes, something like '''I press "BUTTON_STRING"''' or it ends with a ''':''' . The three methods are:
* '''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 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 selector'''; there are steps that can be used with different kinds of elements, for example '''I click on "User Name" "link"''' or '''I click on "User Name" "button"''' this is a closed list of elements, in the 'Acceptance testing' interface you can see a dropdown menu to select one of these options:
** field - for searching a field by its id, name, value or label
** fieldset - for searching a fieldset by it's id or legend
** link - for searching a link by its href, id, title, img alt or value
** button - for searching a button by its name, id, value, img alt or title
** link_or_button - for searching for both, links and buttons
** select - for searching a select field by its id, name or label
** checkbox - for searching a checkbox by its id, name, or label
** radio - for searching a radio button by its id, name, or label
** file - for searching a file input by its id, name, or label
** optgroup - for searching optgroup by its label
** option - for searching an option by its content
** table - for searching a table by its id or caption
** css_element - for searching an element by its CSS selector
** xpath_element - for searching an element by its XPath

==== Uploading files ====
Note than some tests requires files to be uploaded, in this case
* The '''I upload "FILEPATH_STRING" file to "FILEPICKER_FIELD_STRING" filepicker''' step can be used when located in the form page
* The file to upload should be included along with the Moodle codebase in COMPONENTNAME/tests/fixtures/*
* The file to upload is specified by it's path, which should be relative to the codebase root ('''lib/tests/fixtures/users.csv''' for example)
* '''/''' should be used as directory separator and the file names can not include this '''/''' character as all of them would be converted to the OS-dependant directory separator to maintain the compatibility with Windows systems.
* The scenarios that includes files uploading should be tagged using the '''@_only_local''' tag

=== Fixtures ===

As seen in [[https://docs.moodle.org/dev/Acceptance_testing#Examples examples]] Moodle provides a way to quickly set up the contextual data (courses, users, enrolments...) that you need to properly test scenarios, this can be done using one of the site templates (TODO) or creating entities in the background section (common for all the steps) or in the "Given" part of your scenario. Note that this steps can only be used to set up the contextual data required to test the feature but they don't test what they are doing; for example, the "Given the following "users" exists" is not testing that Moodle is able to create a user, but to test that a user can add a blog entry you might want to use this step. For further info, acceptance tests are supposed to be black-boxed tests (the tester don't know about the internals of the application) and this steps are using internal Moodle data generators instead of running all the steps required to create a user or to create a course, which speeds up the test execution. There are other features to test that all this elements can be properly created.

==== Available elements ====
Most of the available elements can only be created in relation to other elements, to hide the complexity of the Moodle internals (references by contexts, ids...) the references can be done using more human-friendly mappings.

The examples below shows how to add elements referencing other elements, there are required fields to reference the elements, other attributes will be filled with random data if they are not specified.

* Course categories
** The required field is idnumber
** References between parent/children by their idnumber, using the "category" field
Given the following "categories" exists:
| name | category | idnumber |
| Category 1 | 0 | CAT1 |
| Category 2 | CAT1 | CAT2 |

* Courses
** The required field is shortname
** Uses the category idnumber as category reference
Given the following "courses" exists:
| fullname | shortname | category | format |
| Course 1 | COURSE1 | CAT1 | topics |
| Course 2 | COURSE2 | CAT2 | |

* Groups
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groups" exists:
| name | description | course | idnumber |
| Group 1 | Anything | COURSE1 | GROUP1 |

* Groupings
** The required fields are course and idnumber
** Uses the course shortname as course reference
Given the following "groupings" exists:
| name | course | idnumber |
| Grouping 1 | COURSE1 | GROUPING1 |
| Grouping 2 | COURSE1 | GROUPING2 |

* Users
** The required field is username (if password is not set username value will be used as password too)
Given the following "users" exists:
| username | email | firstname | lastname |
| testuser | asd@asd.com | Test | User |

* Course enrolments
** The required fields are user, course and role
** Uses the course shortname as course reference
** Uses the user username as user reference
** Uses the role shortname as role reference
** Uses the enrolment name as enrol reference
Given the following "course enrolments" exists:
| user | course | role | enrol |
| testuser | COURSE1 | editingteacher | manual |

* System role assigns
** The required fields are user and role
** Uses the user username as user reference
** Uses the role shortname as role reference
Given the following "system role assigns" exists:
| user | role |
| testuser | manager |

* Group members
** The required fields are user and group
** Uses the group idnumber as group reference
** Uses the user username as user reference
Given the following "group members" exists:
| user | group |
| testuser | GROUP1 |

* Grouping groups
** The required fields are grouping and group
** Uses the group idnumber as group reference
** Uses the grouping idnumber as grouping reference
Given the following "grouping groups" exists:
| grouping | group |
| GROUPING1 | GROUP1 |

* Cohorts
** The required field is idnumber
Given the following "cohorts" exists:
| name | idnumber |
| Cohort 1 | COHORT1 |

== Adding steps definitions ==

Each Moodle component and plugin (including 3rd party plugins) can add new steps definitions. If you are writing tests and you notice that you are repeating the same group of steps you might want to create a new step definition that allows you to substitute the group of steps for one single step, something like ''I add a forum post with "blablabla" as description'' for example; also you can create whole new steps using the APIs provided by Behat and Mink if what you need to do is not covered by any of the available steps.

=== Check list ===

New steps should be/have:
* Implemented as public methods of a PHP class whose name must begin with 'behat_' prefix and with '.php extension
* Using the class name as filename (adding the '.php' extension) and extending MOODLEDIRROOT/lib/behat/behat_base.php (or MOODLEDIRROOT/lib/behat/behat_files.php if it's a repository or is files-related)
* With a descriptive class name, for example the component name (it will be used when filtering steps definitions)
* Stored in COMPONENTNAME/tests/behat/ directory or lib/tests/behat/ if is not part of any other component
* Describe it's purpose in a single line inside the method doc comment, the size of the comment is not a problem
* Describe the regular expression with the most appropriate tag inside the method doc comment:
** '''@Given''' - A step to set up the initial context (for example ''the following "courses" exists'')
** '''@When''' - An action that provokes an event (for example ''I press the button "buttonname"'')
** '''@Then''' - Checkings to ensure the outcomes are the expected (for example ''I should see "whatever"'')
* Depending on the inputs your definition expects you must use a different regular expression:
** '''If you expect a number:''' "(?P<info_about_what_you_expect_number>\d+)" (note that the regular expression is quoted between '''"''')
** '''If you expect a string or a text:''' "(?P<info_about_what_you_expect_string>(?:[^"]|\\")*)" Don't use '''text_selector_string''' and '''selector_string''' as info strings, they are reserved to selector types (note that the regular expression is quoted between '''"''')
** '''If you expect a table with key/value pairs (for example to fill a form):''' Finish your regular expression with ''':''' and provide info in the description about the contents of the table
** '''If you expect a selector type:''' "(?P<selector_string>[^"]*)" or "(?P<text_selector_string>[^"]*)" depending on whether you want to use any selector or you want a text-based selector (more info about selectors in https://docs.moodle.org/dev/Acceptance_testing#Providing_values_to_steps)
* To make test writer's life better is good to include explicative info in the subexpressions of the regular expression about what the test writer is supposed to put in there (for example ''I expand "(?P<nodetext>(?:[^"]|\\")*)" node'')
* Is recommended to use the static part of the regular expression as the name of the method, using underscores instead of spaces (see current steps definitions)

=== Example ===

You can use this example below or any of the existing steps definitions as a template.

* auth/tests/behat/behat_auth.php
class behat_auth extends behat_base {
/**
* Logs in the user. There should exist a user with the same value as username and password
*
* @Given /^I log in as "(?P<username_string>(?:[^"]|\\")*)"$/
*/
public function i_log_in_as($username) {
return array(new Given('I am on homepage'),
new Given('I follow "Login"'),
new Given('I fill in "Username" with "'.$username.'"'),
new Given('I fill in "Password" with "'.$username.'"'),
new Given('I press "Login"'),
new Given('I should see "You are logged in as"'));
}
}

=== Tips ===

If you are creating a completely new step definition there are also a few things to consider:
* The definition code will be executed by Behat, not by Moodle, you have to keep this in mind for example when throwing exceptions, Behat exceptions will give more info to the user about where is the problem
** You can find these exceptions in '''vendor/behat/mink/src/Behat/Mink/Exception/*'''
* Selenium is fast, sometimes it tries to interact with DOM elements or tries to execute actions that requires JS that are not loaded or ready to used; this is why, sometimes and randomly, you can see an "element not found" failure
** The quickest way to solve this problem is using behat_base::find*() methods (where the * corresponds to '''<nowiki>''</nowiki>''', '''_all''', or to a named selector preceded by '''_''', http://mink.behat.org/#named-selectors) which only requires the locator as argument. This methods will wait for the requested element to be ready or return an exception if the element is not found after the timeout value expires, you can also force the timeout value, which defaults to 6 seconds. An example of a named selector use is '''$button = $this->find_button("Save changes");''' if you are not sure about the element being available you always can wrap the find*() call in a try & catch.
** For advanced usages, the spin method is defined in '''lib/behat/behat_base::spin''', consider that all the contents of the closures passed to spin() can be executed more than once, so don't use irreversible actions that can invalidate the tests results (for example use find() methods but don't use click() methods)

If you create new steps definitions or tests you must run '''php admin/tool/behat/cli/util.php --enable''' to update the Behat config file before running '''vendor/bin/behat'''

== Links ==
* Technical info: https://docs.moodle.org/dev/Behat_integration
* Behat CLI command options: http://docs.behat.org/guides/6.cli.html
* How to use selectors to interact with the site elements: http://mink.behat.org/#traverse-the-page-selectors

[[Category:Behat]]

[[es:Prueba de aceptación]]

Question behaviours

2012-06-19T12:11:57Z

Emerrill:

{{Template:Question_engine_2}}
This page explains how to go about writing a new question behaviour for the new Moodle [[Question Engine 2|question engine]].

Previous section: [[Overview_of_the_Moodle_question_engine|Overview_of_the_Moodle_question_engine]]

To learn to write question behaviours, you are highly encouraged to read the code of some of the existing behaviours in the Moodle code base. The code for most behaviours is shorter than these instructions!

Also note that all the question engine code has extensive PHP documenter comments that should explain the purpose of every class and method. This document is supposed to provide an overview of the key points to get you started. It does not attempt to duplicate all the details in the PHPdocs.

This document assumes that you understand the data model, where a question attempt comprises a number of steps, and each step has some properties like a state and a mark, and an array of submitted data. This is explained in the [[Overview_of_the_Moodle_question_engine|overview_of_the_Moodle_question_engine]].

==File layout==

A question behaviour plugin lives in a folder in <tt>question/behaviour</tt>. The layout inside that folder follows the typical layout for a Moodle plugin. For example, inside <tt>question/behaviour/mybehaviour/</tt> we would have:

; behaviour.php : This contains the definition of the <tt>qbehaviour_mybehaviour</tt> class, which should extend the <tt>question_behaviour</tt> base class.
; renderer.php : This contains the definition of the <tt>qbehaviour_mybehaviour_renderer</tt> class, which should extend the <tt>qbehaviour_renderer</tt> base class.
; simpletest/... : Contains the unit tests for this behaviour. You are strongly encouraged to write thorough unit tests to ensure the correctness of your behaviour.
; lang/en_utf8/qbehaviour_mybehaviour.php : English language strings for this behaviour. You can, of course, include other languages too. The language file must define at least the string giving the model a name, for example <tt>$string['mybehaviour'] = 'My behaviour';</tt>.

Note that question behaviours are not expected to have their own database tables or capabilities. Therefore, there should not be a db sub-folder.

In future, we will probably add the ability for a behaviour to have a settings.php file, so that it can have configuration options.

==Question behaviour class==

One instance of this class will be created for each <tt>question_attempt</tt> that uses this model.

This documentation just lists the methods that you are likely to need to override. See the PHPdocumentor comments for a complete API documentation.

===Class declaration===

The class name for the behaviour class must be the plugin name (e.g. <tt>mybehaviour</tt>) prefixed by <tt>qbehaviour_</tt>. You must extend the <tt>question_behaviour</tt> base class, or another model class.

<code php>
class qbehaviour_mybehaviour extends question_behaviour {
// ...
}
</code>

You should not need to override the constructor.

===Fields===

When a behaviour class is created, the fields <tt>qa</tt> and <tt>question</tt> are initialised to point to the question attempt and question that this model is being used by.

From the base class code:
<code php>
// From the base class.
/** @var question_attempt */
protected $qa;
/** @var question_definition */
protected $question;

public function __construct(question_attempt $qa) {
$this->qa = $qa;
$this->question = $qa->get_question();
// ...
}
</code>

===Methods used during attempts at a question===

====required_question_definition_class()====

Most behaviours can only work with a particular subclasses of <tt>question_definition</tt>. For example, they may only be able to work work with questions that are <tt>question_automatically_gradable</tt>s. This method lets the behaviour document that. The type of question passed to the constructor is then checked against the class name returned by this function.

Example from <tt>qbehaviour_deferredfeedback</tt>:
<code php>
public function required_question_definition_class() {
return 'question_automatically_gradable';
}
</code>

====get_min_fraction()====

Returns the smallest possible [[Question_Engine_2:Design#Words_related_to_grades|fraction]] that this behaviour, applied to this question, may give. Normally this will be the min fraction of the question type, however some behaviours (for example CBM) manipulate the question scores, and so need to return an adjusted min_fraction.

For example, from <tt>qbehaviour_deferredfeedback</tt>:
<code php>
public function get_min_fraction() {
return $this->question->get_min_fraction();
}
</code>

From <tt>qbehaviour_deferredcbm</tt>:
<code php>
public function get_min_fraction() {
return question_cbm::adjust_fraction(
parent::get_min_fraction(), question_cbm::HIGH);
}
</code>

====get_expected_data()====

Some behaviours display additional form controls. When the question form is submitted, these submitted values are read using the standard optional_param function. The question engine needs to know what parameters to look for, and with what types.

The <tt>get_expected_data</tt> function should return an array of expected parameters, with the corresponding param type. Note that the array of expected parameters may depend on the current state of the question attempt. For example, from <tt>qbehaviour_deferredcbm</tt>
<code>
public function get_expected_data() {
if (question_state::is_active($this->qa->get_state())) {
return array('certainty' => PARAM_INT);
}
return parent::get_expected_data();
}
</code>

====init_first_step()====

You are unlikely to need to override this method. This is called when the question attempt is actually stared. It gives the behaviour a chance to do any necessary initialisation, including passing on the request to the question type. This is, for example, how the choices in a multiple choices question are shuffled.

From the base class:
<code php>
public function init_first_step(question_attempt_step $step) {
$this->question->init_first_step($step);
}
</code>

====process_action()====

This is the most important method. It controls what happens when someone does something with the question (other than starting it, which is handled by <tt>init_first_step</tt>.)

When the method is called, a pending attempt step is passed in. This method can either return <tt>question_attempt::DISCARD</tt>, to indicate nothing interesting happened, and the pending step should be discarded. Or, it can update that step, and return <tt>question_attempt::KEEP</tt>, to have the new step retained.

Typically, the method is implemented by examining the current state of the attempt, and the pending step, to decide what sort of action this is, and then dispatching to a more specific method.

For example, from <tt>qbehaviour_deferredfeedback</tt>
<code php>
public function process_action(question_attempt_step $pendingstep) {
if ($pendingstep->has_behaviour_var('comment')) {
return $this->process_comment($pendingstep);
} else if ($pendingstep->has_behaviour_var('finish')) {
return $this->process_finish($pendingstep);
} else {
return $this->process_save($pendingstep);
}
}
</code>

Note that there are some special actions that every behaviour must be able to handle:

; behaviour_var comment => '... ''the comment'' ...' : If this question has marks, then there will also be a behaviour_var mark and a behaviour_var maxmark. This is the action that is fired when a user manually grades a question.
; behaviour_var finish => 1 : This is the action that is generated when the user submits and finishes a whole usage. For example when they click ''''Submit all and finish'''' in a quiz.

The base class implements the <tt>process_comment</tt> method in a way that should be suitable for most behaviours. There is also a subclass <tt>question_behaviour_with_save</tt> of <tt>question_behaviour</tt> which provides a <tt>process_save</tt> implementation that may be suitable for most behaviours. You may find it helps to extend this class instead of <tt>question_behaviour</tt>.

====process_...()====

So, the process_action function has dispatched to a more specific process_... function. What should that function do? Normally, it has to delegate some processing to the question type, and based on the results of that, upgrade the <tt>$pendingstep</tt>.

For example, from <tt>qbehaviour_deferredfeedback</tt>
<code php>
public function process_finish(question_attempt_pending_step $pendingstep) {
if ($this->qa->get_state()->is_finished()) {
return question_attempt::DISCARD;
}

$response = $this->qa->get_last_step()->get_qt_data();
if (!$this->question->is_gradable_response($response)) {
$pendingstep->set_state(question_state::$gaveup);
} else {
list($fraction, $state) = $this->question->grade_response($response);
$pendingstep->set_fraction($fraction);
$pendingstep->set_state($state);
}
$pendingstep->set_new_response_summary($this->question->summarise_response($response));
return question_attempt::KEEP;
}
</code>

First, if the question attempt has already been finished, there is nothing to do, so <tt>question_attempt::DISCARD</tt> is returned.

If there is something to do, the response data is extracted from the <tt>$pendingstep</tt>. The question type is asked whether the data there is complete enough to be graded. If not, the state is set to 'gave up'. If there is, the question type is asked to compute the fraction, and that and the state are put into the <tt>$pendingstep</tt>. Finally, the response summary, which is displayed in places like the quiz reports is updated and <tt>question_attempt::DISCARD</tt> is returned.

====adjust_display_options()====

This method is called before a question is rendered, so that the behaviour can change the display options depending on the current state of the question. So, for example, after the question is finished, it should be displayed in read-only mode. Before the student had submitted an answer, no feedback should be displayed.

For example, the base class does
<code php>
public function adjust_display_options(question_display_options $options) {
if ($this->qa->get_state()->is_finished())) {
$options->readonly = true;
$options->numpartscorrect = $options->numpartscorrect &&
$this->qa->get_state()->is_partially_correct() &&
!empty($this->question->shownumcorrect);
} else {
$options->hide_all_feedback();
}
}
</code>

====get_state_string()====

In the info box that starts each question, the is a few words summary of the current state of the question. That summary is generated by this method. It is not often necessary to override the base class implementation:
<code php>
public function get_state_string($showcorrectness) {
return $this->qa->get_state()->default_string($showcorrectness);
}
</code>
An example where it is overridden is <tt>qbehaviour_interactive</tt>, if you want to look.

====get_our_resume_data()====

This method is required to make the quiz feature '''Each attempt builds on last''' work. It needs to return any behaviour variable from the current attempt that would be needed to start a new attempt in the same state.

For example, from <tt>qbehaviour_deferredcbm</tt>:
<code php>
protected function get_our_resume_data() {
$lastcertainty = $this->qa->get_last_behaviour_var('certainty');
if ($lastcertainty) {
return array('-certainty' => $lastcertainty);
} else {
return array();
}
}
protected function get_our_resume_data() {
return array();
}
</code>

===Methods used for reporting===

As well as just processing a single attempt as it happens, we need to be able to run reports of what happened across lots of attempts, for example to determine whether questions are performing well or badly.

Some of these methods in this section are called during the attempt, and the result stored in the database at that time, rather than when the report is run. That is just a performance consideration. Logically, these methods are all for reporting, so I list them here.

====get_correct_response()====

In fact, this first method is not even used for the reports. It is used in the question preview pop-up window to make the 'Fill in correct response' button work. It returns the behaviour data that needs to be submitted as part of a correct response. Obviously, this is then combined with data from the question type.

For example, from <tt>qbehaviour_deferredcbm</tt>
<code php>
public function get_correct_response() {
if ($this->qa->get_state()->is_active()) {
return array('certainty' => question_cbm::HIGH);
}
return array();
}
</code>

====get_question_summary()====

This method returns a plain-text summary of the question that was asked. This is used, for example, by the quiz Responses report. Normally the base-class implementation that just delegates to the question type is all you need.
<code php>
public function get_question_summary() {
return $this->question->get_question_summary();
}
</code>

====get_right_answer_summary()====

This should return a plain-text summary of what the right answer to the question is. For example, in the base class:
<code php>
public function get_right_answer_summary() {
return $this->question->get_right_answer_summary();
}
</code>
and in <tt>qbehaviour_deferredcbm</tt>:
<code php>
public function get_right_answer_summary() {
$summary = parent::get_right_answer_summary();
return $summary . ' [' . question_cbm::get_string(question_cbm::HIGH) . ']';
}
</code>
(Hmm. I probably should not be concatenating language strings like that.)

====adjust_random_guess_score()====

Questions are able to report an estimate of the mark a student would get by guessing. Naturally, question types that modify the marks need to be able to manipulate that. For example in <tt>qbehaviour_deferredcbm</tt>:
<code php>
public static function adjust_random_guess_score($fraction) {
return question_cbm::adjust_fraction($fraction, question_cbm::default_certainty());
}
</code>

====classify_response()====

This is used by the response analysis in the quiz statistics report: At the moment, no behaviours do more than delegate to the question type:
<code php>
public function classify_response() {
return $this->question->classify_response($this->qa->get_last_qt_data());
}
</code>

====summarise_action()====

This is used by the response history table that is shown underneath questions on the quiz review page, in the Action column. It should return a plain text representation of the action the student took in this step. For example, from <tt>qbehaviour_deferredfeedback</tt>:
<code php>
public function summarise_action(question_attempt_step $step) {
if ($step->has_behaviour_var('comment')) {
return $this->summarise_manual_comment($step);
} else if ($step->has_behaviour_var('finish')) {
return $this->summarise_finish($step);
} else {
return $this->summarise_save($step);
}
}
</code>
from <tt>question_behaviour_with_save</tt>
<code php>
public function summarise_save(question_attempt_step $step) {
$data = $step->get_submitted_data();
if (empty($data)) {
return $this->summarise_start($step);
}
return get_string('saved', 'question',
$this->question->summarise_response($step->get_qt_data()));
}
</code>
and from the base class:
<code php>
public function summarise_start($step) {
return get_string('started', 'question');
}

public function summarise_finish($step) {
return get_string('attemptfinished', 'question');
}
</code>

===Things related to the setting UI===

An activity using questions needs to provide various options to the user that relate to behaviours. For example, on the quiz settings form, we need to display a menu '''How questions behave''' where the teacher can choose which behaviour they want. The quiz does this by calling <tt>question_engine::get_behaviour_options()</tt>. Similarly, when selecting the display options '''Users may review''', '''During the attempt''', not all options are relevant to all behaviours, The quiz can get the appropriate dependencies by calling <tt>question_engine::get_behaviour_unused_display_options()</tt>. Naturally, the question engine needs to consult the behaviours to implement these methods This is done using the following two things.

====IS_ARCHETYPAL====

Some behaviours should be offered as options in the user interface. For example CBM, interactive, and so on. Others are for internal use. For example <tt>qbehaviour_informationitem</tt>, <tt>qbehaviour_interactiveadaptedformyqtype</tt>. This is indicated by defining a constant <tt>IS_ARCHETYPAL</tt> in the class. True means that this behaviour will be offered as an option in the UI.

<code php>
const IS_ARCHETYPAL = true; // or false
</code>

====get_unused_display_options()====

This method should return a list of <tt>question_display_options</tt> field that are irrelevant before <tt>question_usage_by_activity::finish_all_questions()</tt> is called.

For example, from <tt>qbehaviour_deferredfeedback</tt>:
<code php>
public static function get_unused_display_options() {
return array('correctness', 'marks', 'specificfeedback',
'generalfeedback', 'rightanswer');
}
</code>

==Renderer class==

Renderers are all about generating HTML output. The overall output of questions is controlled by the <tt>core_question_renderer::question(...)</tt> method, which in turn calls other methods of the core question renderer, the behaviour renderer and the question type renderer, to generate the various bits of output. See [[Question_Engine_2:Overview#What_are_the_parts_of_a_question.3F|this overview of the parts of a question]].

Note that most of the methods take a <tt>question_display_options</tt> object that specifies what should and should not be visible. For example, should feedback, or marks information, be displayed. It is important that your renderer respects these options.

Once again, in what follows, I only list the methods your are most likely to want to override.

===controls===

This is a block of output in the question formulation area. It goes after all the question type output in this area.

Two examples. This method is used by the interactive behaviour to show the '''Submit''' button (if the question is in an appropriate state). It is used by the CBM model to show the certainty choices. Here is the interactive behaviour code:
<code php>
public function controls(question_attempt $qa, question_display_options $options) {
return $this->submit_button($qa, $options);
}
</code>
<tt>submit_button</tt> is a helper method provided by the base class.

===feedback===

This is a block of output in the feedback area of the question. It is used, for example, in interactive behaviour, to show the '''Try again''' button, and in the CBM model to output some text that explains how the score was adjusted. Here is the interactive behaviour code:
<code php>
public function feedback(question_attempt $qa, question_display_options $options) {
if (!$qa->get_state()->is_active() || !$options->readonly) {
return '';
}

// Set up $attributes array ...

$output = html_writer::empty_tag('input', $attributes);
if (empty($attributes['disabled'])) {
$output .= print_js_call('question_init_submit_button',
array($attributes['id'], $qa->get_slot()), true);
}
return $output;
</code>

Note that we set up a call to the JavaScript function <tt>question_init_submit_button</tt>, passing the button id, and the question slot number. You should do that for any button you output that will cause the question to be submitted.

==Unit tests==

For a general introduction, see the [[Unit_tests|Moodle unit testing documentation]].

Most of the behaviours are currently tested by working one or more test questions through a sequence of example inputs and testing the results. To do this they sub-class <tt>qbehaviour_walkthrough_test_base</tt> which provides a lot of helper methods to facilitate writing tests like that.

The best way to start is probably to look at the tests for some of the standard behaviours. For example <tt>qbehaviour_deferredfeedback_walkthrough_test::test_deferredfeedback_feedback_multichoice_single</tt>
<code php>
public function test_deferredfeedback_feedback_multichoice_single() {

// Create a true-false question with correct answer true.
$mc = test_question_maker::make_a_multichoice_single_question();
$rightindex = $this->get_mc_right_answer_index($mc);

// Start a deferred feedback attempt and add the question to it.
$this->start_attempt_at_question($mc, 'deferredfeedback', 3);

// Verify.
$this->check_current_state(question_state::$todo);
$this->check_current_mark(null);
$this->check_current_output(
$this->get_contains_question_text_expectation($mc),
$this->get_contains_mc_radio_expectation(0, true, false),
$this->get_contains_mc_radio_expectation(1, true, false),
$this->get_contains_mc_radio_expectation(2, true, false),
$this->get_does_not_contain_feedback_expectation());

// Process the data extracted for this question.
$this->process_submission(array('answer' => $rightindex));

// Verify.
$this->check_current_state(question_state::$complete);
$this->check_current_mark(null);
$this->check_current_output(
$this->get_contains_mc_radio_expectation($rightindex, true, true),
$this->get_contains_mc_radio_expectation(($rightindex + 1) % 3, true, false),
$this->get_contains_mc_radio_expectation(($rightindex + 1) % 3, true, false),
$this->get_does_not_contain_correctness_expectation(),
$this->get_does_not_contain_feedback_expectation());

// Finish the attempt.
$this->quba->finish_all_questions();

// Verify.
$this->check_current_state(question_state::$gradedright);
$this->check_current_mark(3);
$this->check_current_output(
$this->get_contains_mc_radio_expectation($rightindex, false, true),
$this->get_contains_correct_expectation());

// Now change the correct answer to the question, and regrade.
$mc->answers[13]->fraction = -0.33333333;
$mc->answers[14]->fraction = 1;
$this->quba->regrade_all_questions();

// Verify.
$this->check_current_state(question_state::$gradedwrong);
$this->check_current_mark(-1);
$this->check_current_output(
$this->get_contains_incorrect_expectation());
}
</code>

As you can see, the helper methods hide a lot of the details, like starting an attempt, but if you browse the code, you will be able to see exactly what those (quite simple) helper functions do. I was going to summarise here what the test does, but I think the comments in the code already do that well enough.

==See also==

In the next section, [[Developing a Question Type|Developing a Question Type]] I describe what a developer will need to do to create a Question Type plugin for the new system.

* The PHP documenter comments that explain the purposes of every method in the question engine code.
* Back to [[Question_Engine_2|Question Engine 2]]

[[Category:Plugins]]