MoodleDocs - User contributions [en]

Git for developers

2016-11-15T14:17:01Z

Gabrielros: /* Changing commit message, reordering and squashing commits */

This document is for helping you get started on Moodle development with Git. For further details of Git, see [[:Category:Git]].

== General workflow ==

'''A reasonable knowledge of the Git basics is a good idea before you start to use it for development. If you are new to Git, you are encouraged to go to 'See also' for some more general reading.'''

[[image:git-pushpull-model.png|right|thumb|400px|Moodle development workflow with Git]]
Detailed explanation of the workflow can be found in the [[Process]] page. In short, the Moodle development with Git looks like this:

* You as the contributor commit changes into your personal repository at your computer
* You push the changes into your public repository and publish links to your changes in the Moodle Tracker
* You request a peer review of your code from another developer
* When peer reviewer is happy they submit issue for integration
* Moodle integrators pull the changes from your public repository and if they like them, they put them into Moodle integration repository
* The integrated change is tested and finally pushed into Moodle production repository
* You update your local repository with all changes from the production repository and the next cycle may start again

This workflow runs in roughly weekly cycles. The integration happens on Monday and Tuesday and the testing on Wednesday. On Thursday (or Friday if testing takes too long), the production repository moodle.git is usually updated with changes from the last development week.

Most Moodle developers have their public repositories hosted at [http://github.com/ Github]. Alternatively you may want to try [http://gitorious.org Gitorious] or the legendary [http://repo.or.cz repo.or.cz]. In the examples in this guide we assume you'll set up your public repository at Github.

When you first register on tracker you can not assign issues to yourself or send them for peer review. You will be added to the developers group after your first bug fix is integrated. Before that just comment on the issue with a link to your branch and component lead or another developer will send issue for peer review for you.

== Installing Git on your computer ==

Install Git on your computer. Most Linux distributions have Git available as a package to install. On Debian/Ubuntu, type ''''sudo apt-get install git'''' on the terminal. If you are on Mac, [http://code.google.com/p/git-osx-installer/ git-osx-installer] installs it in a few clicks.

Immediately after the installation, set your name and contact e-mail. The name and e-mail will become part of your commits and they can't be changed later once your commits are accepted into the Moodle code. Therefore we ask contributors to use their real names written in capital letters, eg "John Smith" and not "john smith" or even "john5677".

git config --global user.name "Your Name"
git config --global user.email yourmail@domain.tld

Unless you are the repository maintainer, it is wise to set your Git to not push changes in file permissions:

git config --global core.filemode false

Also, it's recommended to verify that the your git installation is not performing any transformation between LFs and CRLFs. All Moodle '''uses only LFs''' and you should '''fetch/edit and push''' it that way (may need to configure your editor/IDE too). Note that having any "magic" enabled is known to cause [[Common unit test problems#The_test_file_.22evolution.test.22_should_not_contain_section_named_.22.5Blots_of_content.5D.22|problems with unit tests]] execution. So we recommend you to set:

git config --global core.autocrlf false

== Setting-up the public repository ==

1. Go to [http://github.com/ Github] and create an account.

2. Go to the [http://github.com/moodle/moodle official Moodle Github repository] and click on the Fork button. You now have your own Github Moodle repository.

3. Now you need to set up your SSH public key, so you can push to your Github Moodle repository from your local Moodle repository. On Mac you can go on this [http://help.github.com/mac-key-setup/ Github help page]. If you are on another system, go to your Github administration page, to the section SSH Public Keys, and you should see a link to a help page. Done? Good! That was the most difficult part!

== Setting-up the local repository at your computer ==

Create a local clone repository of your Github repository. In a terminal:

git clone git://github.com/YOUR_GITHUB_USERNAME/moodle.git LOCALDIR

(or: git clone git@github.com:YOUR_GITHUB_USERNAME/moodle.git LOCALDIR)

This command does several jobs for you. It creates a new folder, initializes an empty Git repository in it, sets your Github repository as the remote repository called 'origin' and makes a local checkout of the branch 'master' from it. The important point to remember now is that your Github repository is aliased as 'origin' for your local clone.

Note that the format of the URL here is important. In the first example, the URL starts "git://github.com" and this will give read-only access to the repository at github.com. If you use this URL, the "git push origin" command that appears later in this document will not work. Therefore, if you want to be able to update the "origin" repository, you should use the URL that starts "git@github.com", i.e. the second of the two "git clone" commands given above. This will give you read and write access to the repository on github.com.

== Keeping your public repository up-to-date ==

[[image:git-sync-github.png|right|thumb|400px|Fetching changes from upstream and pushing them to github]]
Your fork at Github is not updated automatically. To keep it synced with the upstream Moodle repository, you have to fetch the recent changes from the official moodle.git and push them to your public repository. To avoid problems with this it is strongly recommended that you never modify the standard Moodle branches. ''Remember: never commit directly into master and MOODLE_xx_STABLE branches.'' In other words, always create topic branches to work on. In Gitspeak, the master branch and MOODLE_xx_STABLE branches should be always fast-forwardable.

To keep your public repository up-to-date, we will register remote repository git://git.moodle.org/moodle.git under 'upstream' alias. Then we create a script to be run regularly that fetches changes from the upstream repository and pushes them to your public repository. Note that this procedure will not affect your local working directory.

To register the upstream remote:

cd moodle
git remote add upstream git://git.moodle.org/moodle.git

The following commands can be used to keep the standard Moodle branches at your Github repository synced with the upstream repository. You may wish to store them in a script so that you can run it every week after the upstream repository is updated.

#!/bin/bash
git fetch upstream
for BRANCH in MOODLE_{19..27}_STABLE master; do
git push origin refs/remotes/upstream/$BRANCH:$BRANCH
done

=== How it works ===

The git-fetch command does not modify your current working dir (your checkout). It just downloads all recent changes from a remote repository and stores them into so called remote-tracking branches. The git-push command takes these remote-tracking branches from upstream and pushes them to Github under the same name. Understanding this fully requires a bit knowledge of Git internals - see gitrevisions(7) man page.

Note there is no need to switch the local branch during this. You can even execute this via cron at your machine. Just note that the upstream repository updates typically just once a week.

=== New branches ===

Occasionally, moodle.org will create a new branch that does not exist in your public (e.g. Github.com) repository. If you try to push this new branch, you will see an error such as the following:

error: unable to push to unqualified destination: MOODLE_99_STABLE
The destination refspec neither matches an existing ref on the remote
nor begins with refs/, and we are unable to guess a prefix based on the source ref.
error: failed to push some refs to 'git@github.com:YOUR_GITHUB_USERNAME/moodle.git'

In the above example, "MOODLE_99_STABLE", is the name of the new branch that does not exist in your public repository. To fix the error, you need to create the new branch on your public repository, using the following commands, replacing "MOODLE_99_STABLE" with the name of the new branch you wish to create:

git checkout MOODLE_99_STABLE
git push origin MOODLE_99_STABLE:MOODLE_99_STABLE

The above code will create a new copy of the "MOODLE_99_STABLE" branch in your local repository. If you do not need to keep a local copy of the new branch - and probably you do not need it, you then can remove it from your local repository as follows:

git checkout master
git branch -D MOODLE_99_STABLE

== Preparing a patch ==

As said earlier at this page, you never work on standard Moodle branches directly. Every time you are going to edit something, switch to a local branch. Fork the local branch off the standard branch you think it should be merged to. So if you are working on a patch for 1.9 or 2.0, fork the branch off MOODLE_19_STABLE or MOODLE_20_STABLE, respectively. Patches for the next [[Moodle versions|major version]] should be based on the master branch.

git checkout -b MDL-xxxxx-nasty-bug origin/master

Note that if you forget to specify the starting point, the branch is based on the currently checked-out branch. It may not be what you want. It is recommended to always specify the starting point.

To check the current branch, run

git branch

The current branch is highlighted.

Now go and fix the issue with your favorite IDE. Check the status of the files, view the change to be committed and finally commit the change:

vim filename.php
git status
git diff
git commit -a

Note that this is safe as the commit is recorded just locally, nothing is sent to any server yet (as it would in CVS). To see history of the commits, use

git log

Once your local branch contains the change (note that it may consists of several patches) and you are happy with it, publish the branch at your public repository:

git push origin MDL-xxxxx-nasty-bug

Now as your branch is published, you can ask Moodle core developers to review it and eventually integrate it into the standard Moodle repository.

=== Changing commit message, reordering and squashing commits ===

It often happens that you made a mistake in your patch or in the commit message and helpful CiBot pointed it out for you. You can "rewrite the history" and change the existing commits.

Option 1. Reset all the changes in the branch and commit again.

git reset --mixed origin/master

Now all your changes are still present but all commits on top of "master" branch are gone. You can create a new commit

Option 2. Discover '''git rebase''' - this is a powerful tool to change the sequence of commit, change the commit messages, squash commits, etc. We will not cover it here, there are many articles in the Internet about it.

Whatever option you chose, you have "rewritten the history" and you can not simply push the changes to github again because they would need to overwrite the commits that were already pushed. If you try "git push MDL-xxxxx-nasty-bug" you will get an error message suggesting you to force push.
To force push the changed commits use:

git push -f origin MDL-xxxxx-nasty-bug

If an error occurs because you are still using the git protocol (read only), use this command :

git remote set-url origin https://github.com/<user.name>/moodle.git

A prompt will ask for your credentials, if you previously setup your SSH public key you can also use this one :

git remote set-url origin git@github.com:<user.name>/moodle.git

=== Checking if a branch has already been merged ===

After some time contributing to Moodle you would have a lot of branches both in your local repository and in your public repository. To prune their list and delete those that were accepted by upstream, use the following

git fetch upstream (1)
git branch --merged upstream/master (2)
git branch --merged upstream/MOODLE_20_STABLE (3)

The command (1) fetches the changes from your upstream repository at git.moodle.org (remember that git-fetch does not modify your working dir so it is safe to run it whenever). Command (2) and (3) print all branches that are merged into the upstream master branch and MOODLE_20_STABLE branch, respectively. To delete these local branches, use

git branch -d MDL-xxxxx-accepted-branch

The similar approach can be used to check the branches published at your origin repository at github.com

git fetch origin (1)
git fetch upstream
git branch -r --merged upstream/master (2)
git branch -r --merged upstream/MOODLE_20_STABLE (3)

The command (1) makes sure that you have all your branches from github.com recorded as the remote tracking branch locally. Commands (2) and (3) work the same as in the previous example but they list remote tracking branches only ([http://www.kernel.org/pub/software/scm/git/docs/git-branch.html see -r param]). To delete a branch at github.com, use

git push origin :MDL-xxxx-branch-to-delete

This syntax may look weird to you. However it is pretty logical. The general syntax of the git-push command is

git push <repository> <source ref>:<target ref>

so deleting a remote branch can be understood as pushing an "empty (null) reference" to it.

== Peer-reviewing someone else's code ==

To review a branch that someone else pushed into their public repository, you do not need to register a new remote (unless you work with such repository frequently, of course). Let us imagine your friend Alice pushed a work-in-progress branch called 'wip-feature' into her Github repository and asked you to review it. You need to know the read-only address of the repository and the name of the branch.

git fetch git://github.com/alice/moodle.git wip-feature

This will download all required data and will keep the pointer to the tip of the wip-feature branch in a local symbolic reference FETCH_HEAD. To see what's there on that branch, use

git log -p FETCH_HEAD

To see how a particular file looks at Alice's branch

git show FETCH_HEAD:admin/blocks.php

To create a new local branch called 'alice-wip-feature' containing the work by Alice, use

git checkout -b alice-wip-feature FETCH_HEAD

To merge Alice's work into your current branch:

git merge FETCH_HEAD

To see what would be merged into the current branch without actually modifying anything:

git diff ...FETCH_HEAD

Once you are all set and reviewing code, this [[Peer_reviewing_checklist|checklist]] should prove to be useful.

== Rebasing a branch ==

Rebasing is a process when you cut off the branch from its current start point and transplant it to another point. Let us assume the following history exists:

A---B---C topic
/
D---E---F---G master

From this point, the result of the command:

git rebase master topic

would be:

A'--B'--C' topic
/
D---E---F---G master

and would end with 'topic' being your current branch.

You may be asked to rebase your branch submitted for the integration if the submitted branch was based on an outdated commit. The typical case is if you create a new branch as a fork off the upstream master branch on Tuesday. Then on Wednesday, the upstream master branch grows as all changes from the last integration cycle are merged to it. To make diff easy on Github for next weekly pull request review, you want to rebase your branch against the updated master.

git rebase master MDL-xxxxx-topic-branch

Note that rebasing effectively rewrites the history of the branch. '''Do not rebase the branch if there is a chance that somebody has already forked it and based their own branch on it.''' For this reason, many Git tutorials discourage from rebasing any branch that has been published. However in Moodle, all branches submitted for integration are potential subject of rebase (even though we try to not to do it often) and you should not base your own branches on them.

=== Conflicts during rebase ===

During the rebase procedure, conflicts may appear. git-status commands reports the conflicted files. Explore them carefully and fix them in your editor (like you would do with CVS). Then add the files with 'git add' command and continue.

vim conflicted.php
git add conflicted.php
git rebase --continue

== Applying changes from one branch to another ==

Most bugs are fixed at a stable branch (like MOODLE_20_STABLE) and the fix must be prepared for other branches, too (like MOODLE_21_STABLE and the main development branch - master). In Moodle, we do not merge stable branches into the master one. So usually the contributor prepares at least two branches - with the fix for the stable branch(es) and with the fix for the master branch.

If you have a patch prepared on a local branch (let us say MDL-xxxx-topic_20_STABLE), it is possible to re-apply it to another branch.

=== Cherry-picking a single commit ===

Let us have two local Git repositories ~/public_html/moodle21 containing local installation of Moodle 2.1 and ~/public_html/moodledev with the local installation of most recent development version of Moodle. They both use your public repository at github.com as the origin. You have a branch in moodle21 called MDL-xxxx-topic_21_STABLE that was forked off MOODLE_21_STABLE. It contains one commit. Now you want to re-apply this commit to a branch MDL-xxxx-topic in moodledev.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master (1)
git fetch ../moodle21 MDL-xxxx-topic_21_STABLE (2)
git cherry-pick FETCH_HEAD (3)

The command (1) creates new local branch forked off the CONTHERE The command (1) fetches all data needed to re-apply the topic branch and stores the pointer to the tip of that branch to FETCH_HEAD symbolic reference. The command (2) picks the tip of the branch (the top-most commit on it) and tries to apply it on the current branch.
There is also a variant of the cherry-pick command that supports multiple commits, shortly (see its man page for details): <code bash>$ git cherry-pick A^..B</code> if you want to include from A - see '''^''' - to B, A should be older than B. We will use another approach for cherry-picking multiple commits.

=== Applying a set of patches ===

If the branch MDL-xxxx-topic_21_STABLE from the previous example consists of several commits, it may be easier to use git-format-patch and git-am combo to re-apply the whole set of patches (aka patchset). Firstly you will export all commits from the topic branch to files.

cd ~/public_html/moodle21
mkdir .patches
git format-patch -o .patches MOODLE_21_STABLE..MDL-xxxx-topic_21_STABLE (1)

The command (1) takes all commits from the topic branch that are not in MOODLE_21_STABLE and exports them one by one to the output directory .patches. Look at the generated files. They contain the patch itself (in diff format) and additional information about the commit. You could eg send these files by email to a friend of yours for peer-review. We will use them in another repository.

cd ~/public_html/moodledev
git checkout -b MDL-xxxx-topic origin/master
git am -3 ../moodle21/.patches/* (1)

The command (1) applies all the files from the .patches directory. When a patch does not apply cleanly, the command tries fall back on 3-way merge (see the -3 parameter). If conflicts occur during the procedure, you can either deal with them and then use `git am --continue` or abort the whole procedure with `git am --abort`.

== See also ==

; Moodle forum discussions
* [http://moodle.org/mod/forum/discuss.php?d=168094 GIT help needed]
* [http://moodle.org/mod/forum/discuss.php?d=165236 Best way to manage CONTRIB code with GIT]
* [http://moodle.org/mod/forum/discuss.php?d=167063 Handy Git tip for tracking 3rd-party modules and plugins]
* [http://moodle.org/mod/forum/discuss.php?d=167730 Moodle Git repositories]
* [http://moodle.org/mod/forum/discuss.php?d=183409 Git help!! I don't understand rebase enough...]
* [http://moodle.org/mod/forum/discuss.php?d=217617 add MOODLE_24_STABLE to github.com repository]

; External resources
* [http://www.kernel.org/pub/software/scm/git/docs/everyday.html Everyday GIT With 20 Commands Or So]
* [http://gitref.org/ Git Reference]
* [http://progit.org/book/ Pro Git book]
* [http://vimeo.com/14629850 Getting git by Scott Chacon] - an recording of an excellent 1-hour presentation that introducing git, including a simple introduction to what is going on under the hood.
* [http://tjhunt.blogspot.co.uk/2012/03/fixing-bug-in-moodle-core-mechanics.html Tim Hunt's blog: Fixing a bug in Moodle core: the mechanics]

[[Category:Git]]

[[ja:開発者用Git]]

Messaging 2.0

2016-11-07T16:42:41Z

Gabrielros: /* Adding new message type */

{{Infobox Project
|name = Enhanced messaging configuration
|state = implemented, merged into repository
|tracker = MDL-27171
|discussion = http://moodle.org/mod/forum/discuss.php?d=172825
|assignee = [[User:kabalin|Ruslan Kabalin]]
}}
{{Moodle 2.0}}

==Enhanced messaging system==

The messaging system in 2.0 has been revamped significantly:
* it is now event-driven;
* it allows users to control exactly what messages they receive and how;
* it allows administrator to override user settings and set defaults.

Messaging behaviour is controlled by the combination of administrator settings, that define which message outputs are enabled, which outputs can, cannot and should be used for which messages, and user settings that defines which messages user will receive (given that the admin permitted user to control them). The system works graciously when things are not fully configured. For example, jabber notifications can only be send if a Jabber server has been configured, and user has specified his jabber ID in messaging configuration.

Messaging system is enabled by default and controlled via ''Site Administration > Advanced features > Enable messaging system''

==Configuration for administrator==

There is a dedicated menu item where administrator may configure messaging settings, it is located in ''Site Administration > Plugins -> Message outputs'' menu. The menu contains the items for managing messaging outputs, defining default outputs and items for configuring particular outputs like email or jabber.

===Manage message outputs===

This page summarises which messaging outputs (or processors) you have in the system. You may enable or disable a particular output and proceed to message output system configuration screen. The outputs that are not configured are highlighted and cannot be used in the system (they are not listed in messaging preferences configuration screens). Disabled outputs cannot be used in the system either.

[[File:Manage message outputs.jpg|600px]]

===Default message outputs===

Default message outputs page is a grid of message outputs (processors) across the top row and message types (providers) across the left column. The intersection cell of particular output and type contains default preferences for chosen messaging type and output.

[[File:Default message outputs.jpg|600px]]

The default preferences menu for each item is identical and allow administrator to choose permission and default setting when user is logged-in and offline. The possible preferences are:
* '''Disallowed''' - the message of chosen type will never be delivered through the chosen output, user is not allowed to change the personal preference for this combination of message type and output.
* '''Permitted''' - the message of chosen type is allowed to be delivered through the chosen output, default preferences can be set by administrator using the checkboxes below, user can control this preference on the messaging preferences page (and change the suggested defaults the most preferable way).
* '''Forced''' - the message of chosen type will be delivered through the chosen output, user is not allowed to change the personal preference for this combination of message type and output.

===Outputs configuration===

As it was mentioned earlier, the ''Message outputs'' menu contains the configuration for outputs that have system configuration settings. Unless output is configured, it cannot be used in the system.

'''Note:''' Former settings ''Admin > Server > Email'' and ''Admin -> Server -> Jabber'' have been moved to ''Site Administration > Plugins -> Message outputs''. Settings <tt>upportname</tt>, <tt>supportemail</tt> and <tt>supportpage</tt> that were on Email settings page were moved to ''Site Administration > Server -> Support contact''.

==Configuration for user==

Users may configure the messaging preferences in their profile settings ''My Profile settings > Messaging''. The message preferences are configured in "Configure destinations for incoming messages" box that contain a grid of enabled and configured message outputs and message types user has capabilities to access. If particular combination of message type and output is permitted by administrator, user may change the preferences by ticking off the corresponding boxes.

[[File:User message preferences.jpg|600px]]

Some message outputs may require user configuration (e.g. jabber needs ID to be specified), in which case user will not able to set the preferences for the output unless it is configured on the user level. Message output settings are listed at the bottom of messaging preferences page.

[[File:User message preferences settings.jpg|600px]]

==Under the bonnet==

===Capabilities===

In order to configure messaging settings in the site administration menu admin requires <tt>moodle/site:config</tt> permission. User is able to configure personal messaging preferences if <tt>moodle/user:editownmessageprofile</tt> is granted.

===Message types (providers)===

Any plugin can declare any number of message types which can be used on [[Messaging_2.0_improvements#Default_message_outputs|Default message preferences]] and [[Messaging_2.0_improvements#Configuration_for_user|user messaging preferences]] pages. When the particular message type is being [[Messaging_2.0_improvements#Message_dispatching|dispatched]], the delivery method will be chosen based on messaging permissions and preferences defined by admin and user.

====Adding new message type====

Message types for the plugins are declared in ''db/messages.php'' in plugin directory (or in ''lib/db/messages.php'' for the core components). This file contains an array of message types. Each type is presented as array with optional parameters:
*''capability'' that user require to receive the message dispatch by this component (plugin);
*''defaults'' optional default settings for some message output.

The file is processed during plugin installation and upgrade. The message type along with capability is stored in ''message_providers'' table.

For example (''[http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/quiz/db/messages.php;hb=HEAD mod/quiz/db/messages.php]''):
<code php>
$messageproviders = array (

// notify teacher that a student has submitted a quiz attempt
'submission' => array (
'capability' => 'mod/quiz:emailnotifysubmission'
),

// confirm a student's quiz attempt
'confirmation' => array (
'capability' => 'mod/quiz:emailconfirmsubmission'
)

);
</code>

The snippet above will create two message types: submission and confirmation. In the database these records will look like:

<pre>
id name component capability
12 submission mod_quiz mod/quiz:emailnotifysubmission
13 confirmation mod_quiz mod/quiz:emailconfirmsubmission
</pre>

Once the provider has been added to the database, it become visible on [[Messaging_2.0_improvements#Default_message_outputs|Default message preferences]] admin interface and, if permitted based on capabilities, on [[Messaging_2.0_improvements#Configuration_for_user|User messaging preferences]] page.

As it was mentioned above, it is also possible to set default message outputs settings in ''messages.php'' file. The optional ''default'' setting contains an array of message output names with the default settings. These settings define permission and defaults for online and offline states. The possible settings are:
{| class="wikitable"
! scope="col" | Type
! scope="col" | Constants
|-
! scope="row" style="text-align:left;" | Permissions
| |MESSAGE_DISALLOWED | MESSAGE_PERMITTED | MESSAGE_FORCED
|-
! scope="row" style="text-align:left;" | Defaults for loggedin state
| MESSAGE_DEFAULT_LOGGEDIN
|-
! scope="row" style="text-align:left;" | Defaults for loggedoff state
| MESSAGE_DEFAULT_LOGGEDOFF
|}
Using the combination of the settings above the permission and/or defaults can be defined in the ''messages.php'' file, e.g.:
<code php>
$messageproviders = array (

/// Ordinary single forum posts
'assignment_updates' => array (
'defaults' => array(
'popup' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN,
'email' => MESSAGE_FORCED,
),
),

);
</code>
Only one of '''Permissions''' constants should be used for single setting (e.g. <tt>'popup' => MESSAGE_PERMITTED + MESSAGE_DISALLOWED</tt> is invalid will result in having the suggested default setting for ''popup'' output ignored completely). The above snippet will set [[Messaging_2.0_improvements#Default_message_outputs|default message preferences]] to:

[[File:Default message outputs preset example.jpg]]

For those processors that are not listed in ''defaults'' array (like ''jabber'' in the code example above) or if plugin do not have defaults setting at all, or if default setting is invalid, the following defaults are set automatically:
<code php>
'email' => MESSAGE_PERMITTED + MESSAGE_DEFAULT_LOGGEDIN + MESSAGE_DEFAULT_LOGGEDOFF;
'anyotheroutput' => MESSAGE_PERMITTED;
</code>

====Message provider name====

The message provider should have a name defined in the corresponding language file. The string should have a key of the format ''messageprovider:'''provider_name''''', e.g.
(''[http://git.moodle.org/gw?p=moodle.git;a=blob;f=mod/quiz/lang/en/quiz.php;hb=HEAD mod/quiz/lang/en/quiz.php]''):

<code php>
$string['messageprovider:confirmation'] = 'Confirmation of your own quiz submissions';
$string['messageprovider:submission'] = 'Notification of quiz submissions';
</code>

===Message outputs (processors)===

Each message output is presented as a plugin (see [http://git.moodle.org/gw?p=moodle.git;a=tree;f=message/output;hb=HEAD /message/output]). The outputs for email, jabber and web-based popups already exist. A new plugin for different messaging delivery method (e.g. twitter or SMS) can be added quite easily.

The typical message output plugin directory looks like:
<pre>
message/output/jabber/
├── db
│   ├── install.php
│   └── upgrade.php
├── lang
│   └── en
│   └── message_jabber.php
├── lib.php
├── message_output_jabber.php
├── settings.php
└── version.php
</pre>

====message_output class====

The plugin should contain ''message_output_'''name'''.php file'' (e.g. [http://git.moodle.org/gw?p=moodle.git;a=blob;f=message/output/jabber/message_output_jabber.php;hb=HEAD /message/output/jabber/message_output_jabber.php]) with ''message_output_'''name''''' class (where '''name''' is the actual plugin name) that extends an abstract class called ''message_output'' in [http://git.moodle.org/gw?p=moodle.git;a=blob;f=message/output/lib.php;hb=HEAD /message/output/lib.php] with the methods:

<code php>
class message_output_name extends message_output {

public function send_message($message) {
// Given a message object and user info, this actually
// sends it. This function is called by send_message
// function in lib/messagelib.php
}

public function config_form($preferences) {
// This defines the config form fragment used on user
// messaging preferences interface (message/edit.php)
}

public function process_form($form, &$preferences) {
// This processes the data from the config form fragment
// (used in message/edit.php)
}

public function load_data(&$preferences, $userid) {
// This loads up user config for this plugin set via
// config form fragment (used in message/edit.php)
}

public function is_system_configured() {
// This is an optional method that is supposed to return
// true if output is configured on the system level
// for example jabber server settings for jabber plugin.
// Available as of Moodle 2.1
}

public function is_user_configured($user = null) {
// This is an optional method that is supposed to return
// true if output is configured on the user level
// for example user's jabber ID for jabber plugin.
// $user parameter defaults to $USER global
// Available as of Moodle 2.1
}

public function get_default_messaging_settings() {
// Allows you to specify what the default message
// settings should be for this output, in case
// the message provider supplying the message
// has not specified them in its messages.php file
// Available as of Moodle 2.1
}
}
</code>

====Settings file====

If messaging output plugin requires system configuration, it should provide ''settings.php'' file with configuration settings. The link to configuration page will be displayed as a part of admin menu tree (in ''Site Administration > Plugins -> Message outputs'') and in the [[Messaging_2.0_improvements#Manage_message_outputs|Manage message outputs]] page. See [[Admin_settings#Individual_settings|Admin_settings]] for more details.

====Lanuage file====

The plugin should have a ''message_'''name'''.php'' file (where '''name''' is the actual plugin name) in the correct language directory structure with at least one ''pluginname'' string with the name of the processor, e.g.:

<code php>
$string['pluginname'] = 'Jabber message';
</code>

====Installation and Upgrade====

Like in any other moodle plugin, the message processor plugin should have install and upgrade routines defined in ''install.php'' and ''upgrade.php'' respectively. At the very list the plugin should register itself in ''message_processors'' table which will make it listed on messaging configuration pages. The example content of ''install.php'' file for jabber messaging processor is:

<code php>
function xmldb_message_jabber_install(){
global $DB;

$result = true;

$provider = new stdClass();
$provider->name = 'jabber';
$DB->insert_record('message_processors', $provider);
return $result;
}
</code>

Also the plugin should contain the ''version.php'' file. e.g.:
<code php>
$plugin->version = 2008090900;
$plugin->requires = 2008091500;
</code>

===Message dispatching===
Messages are dispatched by calling /lib/messagelib.php message_send -method which returns the message ID or false for errors:

<code php>
$eventdata = new object();
$eventdata->component = 'mod_forum'; // the component sending the message. Along with name this must exist in the table message_providers
$eventdata->name = 'posts'; // type of message from that module (as module defines it). Along with component this must exist in the table message_providers
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = $postsubject; // very short one-line subject
$eventdata->fullmessage = $posttext; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = $posthtml; // html rendered version
$eventdata->smallmessage = ''; // useful for plugins like sms or twitter

$result = message_send($eventdata);
</code>

The name of each provider is a string with a name like ''messageprovider:'''name''''' from the component lang file (in this case, forum.php is derived automatically from mod/forum):

<code php>
$string['messageprovider:posts'] = 'Subscribed forum posts';
$string['messageprovider:digests'] = 'Subscribed forum digests';
</code>

More providers can be added throughout Moodle as necessary, it's quite easy. See the [[Events|Events API]] for info.

==See also==
* [[Messaging_consumers|Messaging Consumer Plugins]]
* [[:en:GSOC/2008]]
* [[Events|Events API]]
* MDL-10107
* MDL-27171 / [https://moodle.org/mod/forum/discuss.php?d=172825 forum thread about some changes that were made to the messaging system]

[[Category:Messaging]]

Local plugins

2016-03-18T11:01:41Z

Gabrielros: little fix of core deprecated extension function name

{{Infobox Project
|name = Local customisations
|state = Implemented
|tracker = MDL-17376, MDL-16438
|discussion = http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]], some parts were originally proposed and implemented in 1.9 by Penny Leach
}}
{{Moodle 2.0}}

The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

== Custom /local/ plugins ==

Local plugins are used in cases when no standard plugin fits, examples are:
* event consumers communicating with external systems
* custom definitions of web services and external functions
* applications that extend moodle at the system level (hub server, amos server, etc.)
* new database tables used in core hacks (discouraged)
* new capability definitions used in core hacks
* custom admin settings
* extending the navigation block with custom menus [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095]

=== Standard plugin features: ===
* /local/xxx/[[version.php]] - version of script (must be incremented after changes)
* /local/xxx/db/install.xml - executed during install (new version.php found)
* /local/xxx/db/install.php - executed right after install.xml
* /local/xxx/db/uninstall.php - executed during uninstallation
* /local/xxx/db/upgrade.php - executed after version.php change
* /local/xxx/db/access.php - definition of capabilities
* /local/xxx/db/events.php - event handlers and subscripts
* /local/xxx/db/messages.php - messaging registration
* /local/xxx/db/external.php - web services and external functions descriptions
* /local/xxx/cron.php - cron job, run at the interval defined in version.php. Alternatively, you can define <tt>local_xxx_cron()</tt> in lib.php. (The lib.php method is now preferred.)
* /local/xxx/lang/en/local_pluginname.php - language file
* /local/xxx/lib.php - function library, automatically included with by config.php. Hook functions local_pluginname_extend_navigation() and local_pluginname_extend_settings_navigation() can be used to add items to the navigation and settings blocks
* /local/xxx/settings.php - configuration options. These get added to the admin menu.

The ''xxx'' is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

=== List of differences from normal plugins: ===
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
* are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
* can add admin settings to any settings page - loaded last when constructing admin tree
* do not need to have any UI - other plugins are usually visible somewhere
* some extra hooks (not implemented yet)

== /local/xxx/db/messages.php ==
Example File Structure:
<code php>
<?php

/**
* Defines message providers (types of messages being sent)
*
* @package mod-forum
* @copyright 1999 onwards Martin Dougiamas http://moodle.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

$messageproviders = array (

/// Ordinary single forum posts
'posts' => array (
)

);
</code>

== Other /local/ customisation files==

===Customised site defaults===

Different default site settings can be stored in file /local/defaults.php.
These new defaults are used during installation, upgrade and later are
displayed as default values in admin settings. This means that the content
of the defaults files is usually updated BEFORE installation or upgrade.

These customised defaults are useful especially when using CLI tools
for installation and upgrade.

Sample /local/defaults.php file content:
<code php>
<?php
$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
$defaults['moodlecourse']['numsections'] = 11;
$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
</code>
First bracket contains string from column plugin of config_plugins table.
Second bracket is the name of setting. In the admin settings UI the plugin and
name of setting is separated by "|".

The values usually correspond to the raw string in config table, with the exception
of comma separated lists that are usually entered as real arrays.

Please note that not all settings are converted to admin_tree,
they are mostly intended to be set directly in config.php.

=== 2.0 pre-upgrade script===

You can use /local/upgrade_pre20.php script for any code that needs to
be executed before the main upgrade to 2.0. Most probably this will
be used for undoing of old hacks that would otherwise break normal
2.0 upgrade.

This file is just included directly, there does not need to be any
function inside. If the execution stops the script is executed again
during the next upgrade. The first execution of lib/db/upgrade.php
increments the version number and the pre upgrade script is not
executed any more.

== Customisations outside of /local/ directory==

=== Forced settings===

Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.

In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.

Sample code in config.php
<code php>
$CFG->allowobjectembed = 0;
$CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>array('requiremodintro'=>1));
</code>

=== Local language customisations===

Moodle supports other type of local customisation of standard language
packs. If you want to create your own language pack based on another
language create new dataroot directory with "_local" suffix, for example
following file with content changes string "Login" to "Sign in":
moodledata/lang/en_local
<code php>
<?php
$string['login'] = 'Sign in';
</code>
See also https://docs.moodle.org/en/Language_editing

=== Custom script injection===

Very old customisation option that allows you to modify scripts by injecting
code right after the require 'config.php' call.

This setting is enabled by manually setting $CFG->customscripts variable
in config.php script. The value is expected to be full path to directory
with the same structure as dirroot. Please note this hack only affects
files that actually include the config.php!

; Examples:
* disable one specific moodle page without code modification
* alter page parameters on the fly

=== Direct code modifications===
This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

=== Direct database modifications===
Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

== Examples ==

=== Adding an element to the settings menu ===

In local/*pluginname*/lib.php, define a function named local_*pluginname*_extend_settings_navigation, this will get called when Moodle builds the settings block.
This example adds a link to the bottom of the course administration section of the settings block.
<code php>
function local_myplugin_extend_settings_navigation($settingsnav, $context) {
global $CFG, $PAGE;

// Only add this settings item on non-site course pages.
if (!$PAGE->course or $PAGE->course->id == 1) {
return;
}

// Only let users with the appropriate capability see this settings item.
if (!has_capability('moodle/backup:backupcourse', context_course::instance($PAGE->course->id))) {
return;
}

if ($settingnode = $settingsnav->find('courseadmin', navigation_node::TYPE_COURSE)) {
$strfoo = get_string('foo', 'local_myplugin');
$url = new moodle_url('/local/myplugin/foo.php', array('id' => $PAGE->course->id));
$foonode = navigation_node::create(
$strfoo,
$url,
navigation_node::NODETYPE_LEAF,
'myplugin',
'myplugin',
new pix_icon('t/addcontact', $strfoo)
);
if ($PAGE->url->compare($url, URL_MATCH_BASE)) {
$foonode->make_active();
}
$settingnode->add_node($foonode);
}
}
</code>

=== Removing the "Site Home" link from the navigation menu ===
<code php>
function local_xxx_extend_navigation(global_navigation $navigation) {
if ($home = $navigation->find('home', global_navigation::TYPE_SETTING)) {
$home->remove();
}
}
</code>

== Local customisations in previous versions ==
Previous versions include only partial support for customisations in /local/ directory.

=== List of local customisations in 1.9.x: ===
* /local/cron.php - custom cron jobs
* /local/settings.php - custom admin settings
* /local/db/upgrade.php - general modifications
* /local/lang/* - custom strings
* /local/lib.php - local_delete_course()

=== Migration from old 1.9.x /local/: ===
* <code>local/*</code> needs to be copied to new directory
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
* events are used instead of hooks
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

==See also==

* [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Extending navigation block]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* http://cvs.moodle.org/moodle/local/readme.txt?view=markup
* [[Local customisation (Moodle 1.9)]]

[[Category:Plugins]]

Setting up xhprof on Moodle

2015-02-16T14:19:05Z

Gabrielros:

The following instructions are for setting up xhprof for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.

==Installing xhprof with Linux==

===Debian/Ubuntu package===
apt-get install php5-xhprof
The current LTS Ubuntu package is version 0.9.4-1build1

===Build manually===
<code bash>
mkdir ~/src/
cd ~/src/
wget http://pecl.php.net/get/xhprof-0.9.2.tgz
tar xvf xhprof-0.9.2.tgz
cd xhprof-0.9.2/extension/
phpize
./configure
make
sudo make install
</code>

Note: The version downloaded via these instructions is not compatible with PHP 5.4 - instead you should download the latest version of the code from https://github.com/facebook/xhprof (before following the instructions from 'cd xhprof-0.9.2/extension/' onwards).

Note: It is available now, the 0.9.3 version from the pecl website. You can run wget http://pecl.php.net/get/xhprof-0.9.3.tgz, if you have PHP 5.4 version.

Add the following to the apache version of you php.ini file

<code ini>
[xhprof]
extension=xhprof.so
xhprof.output_dir="/var/tmp/xhprof"
</code>

Restart Apache
<code bash>
sudo service apache2 restart
</code>

Create a file in your web root that makes a call to phpinfo(); and then view the result in your browser to make sure that xhprof is enabled in PHP. Checking the output of '''php -m''' would also work if you are sure that the command line version of PHP uses the same php.ini file as your web server.

===Troubleshooting===
If you see a '''failed to shell execute cmd=" dot -Tpng''' error when you follow the '''View Full Callgraph''' link you may need to install graphviz ('''sudo apt-get install graphviz''').

Into Windows environment this error can be caused by a path hardcoded into "\lib\xhprof\xhprof_lib\utils\callgraph_utils.php", you must replace one parameter of the proc_open function which is a Linux path "/tmp" by a Windows one, like "c:/temp".

==Installing xhprof with Windows==

You will need to download PHP extensions compiled for your version of PHP. [http://dev.freshsite.pl/php-extensions/xhprof.html Here is one source...]

Extract the contained dll file to the ext directory of your server. With XAMPP this is in xampp\php\ext

Add a line to your php.ini file that matches dll filename you are using. This goes in the Dynamic Extensions section.

<code>
extension=xhprof_0.10.3_php54_vc9.dll
</code>

Stop and restart Apache through your server control interface. If it complains, you probably don't have the correct extension for your version of PHP, or the extension entry in your php.ini file doesn't match the dll file.

To test that the extension is installed, log in to Moodle as an administrator and navigate to Administration > Site administration > Server > PHP info. Search for information about the xhprof extension. It should be present and enabled.

==Configuring Moodle to use xhprof==
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]
Once the xhprof php extension is correctly installed you will find a new "Profiling" option available under Settings > Site administration > Development

When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you mearly need to check the "Enable profiling" box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol ('''*''') while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.

After you have enabled profiling you should load some pages within the "Profile these" filter that you set in the step above. Once you have done these go to Settings > Site administration > Development > Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the "View profiling details" will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more ineresting breakdown of this by then clicking on the "View Full Callgraph" link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]

==Using XHProf==

MDL-39443 shows the kind of thing that can be done using XHProf.

[http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html This blog post] talks about the process.

Since Moodle 2.5.1 it's possible to export and import any profiling run. That enables some interesting uses like, comparisons along the time, between different systems and sharing or runs in other systems like the Tracker when optimization issues are being fixed.

Setting up xhprof on Moodle

2015-02-16T14:16:10Z

Gabrielros: adding indication on Troubleshooting part for windows installs

The following instructions are for setting up xhprof for Moodle under a Ubuntu/Debian environment. The process should be similar for other linux enviroments, but will need some tweaking if you wish to do this under windows. Please update this document if you find any major problems.

==Installing xhprof with Linux==

===Debian/Ubuntu package===
apt-get install php5-xhprof
The current LTS Ubuntu package is version 0.9.4-1build1

===Build manually===
<code bash>
mkdir ~/src/
cd ~/src/
wget http://pecl.php.net/get/xhprof-0.9.2.tgz
tar xvf xhprof-0.9.2.tgz
cd xhprof-0.9.2/extension/
phpize
./configure
make
sudo make install
</code>

Note: The version downloaded via these instructions is not compatible with PHP 5.4 - instead you should download the latest version of the code from https://github.com/facebook/xhprof (before following the instructions from 'cd xhprof-0.9.2/extension/' onwards).

Note: It is available now, the 0.9.3 version from the pecl website. You can run wget http://pecl.php.net/get/xhprof-0.9.3.tgz, if you have PHP 5.4 version.

Add the following to the apache version of you php.ini file

<code ini>
[xhprof]
extension=xhprof.so
xhprof.output_dir="/var/tmp/xhprof"
</code>

Restart Apache
<code bash>
sudo service apache2 restart
</code>

Create a file in your web root that makes a call to phpinfo(); and then view the result in your browser to make sure that xhprof is enabled in PHP. Checking the output of '''php -m''' would also work if you are sure that the command line version of PHP uses the same php.ini file as your web server.

===Troubleshooting===
If you see a '''failed to shell execute cmd=" dot -Tpng''' error when you follow the '''View Full Callgraph''' link you may need to install graphviz ('''sudo apt-get install graphviz''').
Into Windows environnement this error can be caused by a path hardcoded into "\lib\xhprof\xhprof_lib\utils\callgraph_utils.php", you must replace one parameter of the proc_open function which is a Linux path "/tmp" by a Windows one, like "c:/temp".

==Installing xhprof with Windows==

You will need to download PHP extensions compiled for your version of PHP. [http://dev.freshsite.pl/php-extensions/xhprof.html Here is one source...]

Extract the contained dll file to the ext directory of your server. With XAMPP this is in xampp\php\ext

Add a line to your php.ini file that matches dll filename you are using. This goes in the Dynamic Extensions section.

<code>
extension=xhprof_0.10.3_php54_vc9.dll
</code>

Stop and restart Apache through your server control interface. If it complains, you probably don't have the correct extension for your version of PHP, or the extension entry in your php.ini file doesn't match the dll file.

To test that the extension is installed, log in to Moodle as an administrator and navigate to Administration > Site administration > Server > PHP info. Search for information about the xhprof extension. It should be present and enabled.

==Configuring Moodle to use xhprof==
[[Image:profilingOption.png|thumb|left|The profiling option is displayed when the php xhprof extension is installed]]
[[Image:profilingOutput.png|thumb|right|Tabular profiling output produced by xhprof]]
[[Image:callgraph.png|thumb|right|An example call graph showing slow parts of the profiled run]]
Once the xhprof php extension is correctly installed you will find a new "Profiling" option available under Settings > Site administration > Development

When you load the profiling settings page you are confronted with several options. In order to get xhprof up and running with minimal fuss you mearly need to check the "Enable profiling" box and set a path that you wish to be profiled. You can simply set this to a wildcard using the asterisk symbol ('''*''') while you are testing profiling. Afterwards you can come back and set this to a more restrictive setting once you know profiling is working. Note the paths need to be specified relative to your Moodle directory and not the web root.

After you have enabled profiling you should load some pages within the "Profile these" filter that you set in the step above. Once you have done these go to Settings > Site administration > Development > Profiling runs and you should see a list of the pages you visited. Clicking on one of these and then clicking on the "View profiling details" will take you to a profiling table full of helpful stats for tracking down slow pages and functions. You can get an even more ineresting breakdown of this by then clicking on the "View Full Callgraph" link. This callgraph makes it easy to see where the slow parts of each particular run are and functions which individually may not take a long time to run but which are run thousands of times and thus resulting in a great deal of slowdown.
[[Image:profilingSettings.png|frame|center|Enabling profiling and setting it to run on all pages via a wildcard]]
[[Image:profilingRuns.png|frame|left|A profiling runs option can be seen after enabling profiling]]

==Using XHProf==

MDL-39443 shows the kind of thing that can be done using XHProf.

[http://tjhunt.blogspot.co.uk/2013/05/performance-testing-moodle.html This blog post] talks about the process.

Since Moodle 2.5.1 it's possible to export and import any profiling run. That enables some interesting uses like, comparisons along the time, between different systems and sharing or runs in other systems like the Tracker when optimization issues are being fixed.