Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Environment checking

From MoodleDocs

When you install or upgrade Moodle, before 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:

<COMPATIBILITY_MATRIX>
  <MOODLE version="1.5">
    <!-- Various conditions -->
  </MOODLE>
  <MOODLE version="1.6">
    <!-- Various conditions -->
  </MOODLE>
  <!-- etc. -->
</COMPATIBILITY_MATRIX>

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

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.

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

I don't understand this.Tim Hunt 06:59, 26 April 2007 (CDT)

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

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($version) to be called which should return

true
false

$version will be a string like '1.8', should you need it.

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.
  • Functions in that file are given names like mymodule_check_something, where the something explains briefly what is being checked.

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.