Merge branch 'MDL-34035' of git://github.com/timhunt/moodle

lib/setuplib.php

@@ -565,20 +565,49 @@ function get_exception_info($ex) {
 }
 
 /**
- * Returns the Moodle Docs URL in the users language
+ * Returns the Moodle Docs URL in the users language for a given 'More help' link.
  *
- * @global object
+ * There are three cases:
- * @param string $path the end of the URL.
+ *
- * @return string The MoodleDocs URL in the user's language. for example {@link http://docs.moodle.org/en/ http://docs.moodle.org/en/$path}
+ * 1. In the normal case, $path will be a short relative path 'component/thing',
+ * like 'mod/folder/view' 'group/import'. This gets turned into an link to
+ * MoodleDocs in the user's language, and for the appropriate Moodle version.
+ * E.g. 'group/import' may become 'http://docs.moodle.org/2x/en/group/import'.
+ * The 'http://docs.moodle.org' bit comes from $CFG->docroot.
+ *
+ * This is the only option that should be used in standard Moodle code. The other
+ * two options have been implemented because they are useful for third-party plugins.
+ *
+ * 2. $path may be an absolute URL, starting http:// or http://. In this case,
+ * the link is used as is.
+ *
+ * 3. $path may start %%WWWROOT%%, in which case that is replaced by
+ * $CFG->wwwroot to make the link.
+ *
+ * @param string $path the place to link to. See above for details.
+ * @return string The MoodleDocs URL in the user's language. for example @link http://docs.moodle.org/2x/en/$path}
  */
-function get_docs_url($path=null) {
+function get_docs_url($path = null) {
     global $CFG;
+
+    // Absolute URLs are used unmodified.
+    if (substr($path, 0, 7) === 'http://' || substr($path, 0, 8) === 'https://') {
+        return $path;
+    }
+
+    // Paths starting %%WWWROOT%% have that replaced by $CFG->wwwroot.
+    if (substr($path, 0, 11) === '%%WWWROOT%%') {
+        return $CFG->wwwroot . substr($path, 11);
+    }
+
+    // Otherwise we do the normal case, and construct a MoodleDocs URL relative to $CFG->docroot.
+
     // Check that $CFG->branch has been set up, during installation it won't be.
     if (empty($CFG->branch)) {
-        // It's not there yet so look at version.php
+        // It's not there yet so look at version.php.
         include($CFG->dirroot.'/version.php');
     } else {
-        // We can use $CFG->branch and avoid having to include version.php
+        // We can use $CFG->branch and avoid having to include version.php.
         $branch = $CFG->branch;
     }
     // ensure branch is valid.
@@ -592,7 +621,7 @@ function get_docs_url($path=null) {
     if (!empty($CFG->docroot)) {
         return $CFG->docroot . '/' . $branch . '/' . current_language() . '/' . $path;
     } else {
-        return 'http://docs.moodle.org/'. $branch . '/en/' . $path;
+        return 'http://docs.moodle.org/'. $branch . '/' . current_language() . '/' . $path;
     }
 }
 

lib/tests/setuplib_test.php

@@ -0,0 +1,74 @@
+<?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/>.
+
+/**
+ * Unit tests for setuplib.php
+ *
+ * @package   core_phpunit
+ * @copyright 2012 The Open University
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+
+/**
+ * Unit tests for setuplib.php
+ *
+ * @copyright 2012 The Open University
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+class core_setuplib_testcase extends basic_testcase {
+
+    /**
+     * Test get_docs_url_standard in the normal case when we should link to Moodle docs.
+     */
+    public function test_get_docs_url_standard() {
+        global $CFG;
+        if (empty($CFG->docroot)) {
+            $docroot = 'http://docs.moodle.org/';
+        } else {
+            $docroot = $CFG->docroot;
+        }
+        $this->assertRegExp('~^' . preg_quote($docroot, '') . '/2\d/' . current_language() . '/course/editing$~',
+                get_docs_url('course/editing'));
+    }
+
+    /**
+     * Test get_docs_url_standard in the special case of an absolute HTTP URL.
+     */
+    public function test_get_docs_url_http() {
+        $url = 'http://moodle.org/';
+        $this->assertEquals($url, get_docs_url($url));
+    }
+
+    /**
+     * Test get_docs_url_standard in the special case of an absolute HTTPS URL.
+     */
+    public function test_get_docs_url_https() {
+        $url = 'https://moodle.org/';
+        $this->assertEquals($url, get_docs_url($url));
+    }
+
+    /**
+     * Test get_docs_url_standard in the special case of a link relative to wwwroot.
+     */
+    public function test_get_docs_url_wwwroot() {
+        global $CFG;
+        $this->assertEquals($CFG->wwwroot . '/lib/tests/setuplib_test.php',
+                get_docs_url('%%WWWROOT%%/lib/tests/setuplib_test.php'));
+    }
+}