Environment checking

When you install or upgrade Moodle, before the install actually changes anything, it takes you to the /admin/environment.php page, to check that various aspects of your server meets the minimum requirement. For example, it checks PHP version, database version, various PHP extensions, and so on.

The code to actually do the checking is in lib/environmentlib.php. The main entry point is the check_moodle_environment function, which runs the appropriate check using environment_check, then displays the results using print_moodle_environment.

Configuration file overview

The process is controlled by the the /admin/environment.xml file, which looks roughly like this:

<?xml version="1.0" encoding="UTF-8" ?>
<COMPATIBILITY_MATRIX>
  <MOODLE version="3.0">
    <!-- Various conditions -->
  </MOODLE>
  <MOODLE version="3.1">
    <!-- Various conditions -->
  </MOODLE>
  <!-- etc. -->
</COMPATIBILITY_MATRIX>

The 'Various conditions' that can be tested are described below.

Moodle 2.8

Note that, since Moodle 2.6.5, 2.7.2 and 2.8 it's possible, for additional plugins, never for core, to have their own environment.xml files (under own root directory) where any other environment check can be added, following the same rules than the main /admin/environment.xml one (see MDL-39840 for more details).

Moodle 2.9

Also, since Moodle 2.9, within additional plugins environment.xml files, it's possible to replace the <MOODLE version="x.y"> element by a simpler <PLUGIN name="frankenstyle_name"> that will be applied for all the versions of the plugin. The use of this new tag gets precedence over any <MOODLE> tag so usually you must decide between the versioned or un-versioned alternatives (see MDL-48177 for more details).

Things that apply to all tests

Required or optional

The element in the XML file that define the conditions each need to have a level="..." attribute, with value required or optional. This is read by the get_level function in lib/environmentlib.php.

Feedback messages

Inside any of the conditions elements, you can specify a feedback string

        <FEEDBACK>
          <ON_ERROR message="failmessage" />
          <ON_OK message="passmessage" />
        </FEEDBACK>

If level="required" it must be <ON_ERROR>, but if level="optional", you have to use <ON_CHECK>. I don't know why. The whole <FEEDBACK> element is optional, as are any or all of the <ON_ERROR>, <ON_CHECK> or <ON_OK> elements. Any messages you provide will be displayed, if appropriate, otherwise not.

In plugins, the message can be taken from lang/admin.php or from the plugin itself. Example:

        <FEEDBACK>
          <ON_ERROR message="failmessage" plugin="plugintype_plugin_name_where_string_is_defined"/>
        </FEEDBACK>

The message is looked up using get_string($stringtouse, 'admin', $rec), where $rec holds a bunch of information. This is done in the print_moodle_environment function in lib/environmentlib.php.

Bypassing and restricting

Both bypassing and restricting are two methods to change the result of one test. They are used to introduce some exception mechanism to some simple version checking tests like the DATABASE or PHP explained below.

For example, for Moodle 1.8, min required PHP version is 4.3.0, so any 5.x version should be enough. But we have found that PHP versions 5.0.x have some unsolved problems preventing Moodle to run properly. So one mechanism to RESTRICT the official (relaxed) 4.3.0 requirement is needed. (you can read more about this at [https://tracker.moodle.org/browse/MDL-5653 MDL-5653]).

Exactly the opposite happens with the BYPASS mechanism, that can be used to relax some stronger requirement.

Note that both these features should be used in core-core exclusively and only to introduce exceptions to version checking tests whenever we found some important problem with any DATABASE or PHP version as explained above.

So, any non-core-core plugin shouldn't use this at all. Use the new Custom checks explained below instead.

Types of test

Database type and version

For example

    <DATABASE level="required">
      <VENDOR name="mysql" version="3.23" />
      <VENDOR name="postgres" version="7.4" />
    </DATABASE>

PHP version

For example

    <PHP version="4.3.0" level="required" />

PHP extensions

For example

    <PHP_EXTENSIONS>
      <PHP_EXTENSION name="iconv" level="optional">
        <FEEDBACK>
          <ON_CHECK message="iconvrecommended" />
        </FEEDBACK>
      </PHP_EXTENSION>
      <!-- etc. -->
    </PHP_EXTENSIONS>

Unicode

This checks that the database is set to use the Unicode character encoding.

    <UNICODE level="optional">
      <FEEDBACK>
        <ON_CHECK message="unicoderecommended" />
      </FEEDBACK>
    </UNICODE>

Custom checks

Moodle1.9

This runs a custom PHP function that returns true or false.

    <CUSTOM_CHECKS>
      <CUSTOM_CHECK file="question/environmentchecks.php" function="question_check_norqpquestions" level="optional">
      <FEEDBACK>
        <ON_CHECK message="rqpdeprecatedmessage" />
      </FEEDBACK>
      </CUSTOM_CHECK>
      <!-- etc. -->
    </CUSTOM_CHECKS>

This will cause the "$CFG->dirroot/question/environmentchecks.php" to be included, and question_check_something($result) to be called. This should update the $result object (probably by calling $result->setStatus([true/false])) are return it. Alternatively, it may return NULL if the check is not relevant on this server. For example if it is only relevant if some plugin is installed.

I propose these naming conventions:

• If you need environment checks,
  • if your code has a db/upgrade.php file, you should put your check function in there.
  • otherwise create an environmentchecks.php to hold any checks.
  • proposed alternative: create an environmentchecks.php to hold any checks for your plugin (Eloy Lafuente (stronk7) 13:16, 27 April 2007 (CDT)This is proposed in order to avoid get confused with the xxx/db/upgrade.php file that is present inside each plugin).
• Functions in that file are given names like mymodule_check_something, where the something explains briefly what is being checked. (Eloy Lafuente (stronk7) 13:16, 27 April 2007 (CDT)I would propose to test that function name contains "_check_" in order to avoid arbitrary code execution with a hacked xml file).

Note: please do not abuse custom checks when you are doing something that should actually be implemented as a new type of check in environment lib. It's highly recommended to comment about your new custom check at General Developer Forum before implementing it.