MDL-59123 admin: add cli script to compile theme CSS
authorRyan Wyllie <ryan@moodle.com>
Wed, 14 Jun 2017 07:35:36 +0000 (07:35 +0000)
committerRyan Wyllie <ryan@moodle.com>
Tue, 27 Jun 2017 06:48:45 +0000 (06:48 +0000)
Added a script to selectively compile theme CSS. In order to allow
compiling on per theme basis without purging all theme CSS in the
local cache I have made some changes to how CSS is compiled and
how it is accessed via local cache.

admin/cli/build_theme_css.php [new file with mode: 0644]
lib/outputlib.php
theme/styles.php

diff --git a/admin/cli/build_theme_css.php b/admin/cli/build_theme_css.php
new file mode 100644 (file)
index 0000000..30cd996
--- /dev/null
@@ -0,0 +1,119 @@
+<?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/>.
+
+/**
+ * Build and store theme CSS.
+ *
+ * @package    core
+ * @subpackage cli
+ * @copyright  2017 Ryan Wyllie <ryan@moodle.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+define('CLI_SCRIPT', true);
+
+require(__DIR__.'/../../config.php');
+require_once("$CFG->libdir/clilib.php");
+require_once("$CFG->libdir/csslib.php");
+require_once("$CFG->libdir/outputlib.php");
+
+$longparams = [
+    'themes'    => null,
+    'direction' => null,
+    'help'      => false,
+    'verbose'   => false
+];
+
+$shortmappings = [
+    't' => 'themes',
+    'd' => 'direction',
+    'h' => 'help',
+    'v' => 'verbose'
+];
+
+// Get CLI params.
+list($options, $unrecognized) = cli_get_params($longparams, $shortmappings);
+
+if ($unrecognized) {
+    $unrecognized = implode("\n  ", $unrecognized);
+    cli_error(get_string('cliunknowoption', 'admin', $unrecognized));
+}
+
+if ($options['help']) {
+    echo
+"Compile the CSS for one or more installed themes.
+Existing CSS caches will replaced.
+By default all themes will be recompiled unless otherwise specified.
+
+Options:
+-t, --themes    A comma separated list of themes to be compiled
+-d, --direction Only compile a single direction (either ltr or rtl)
+-v, --verbose   Print info comments to stdout
+-h, --help      Print out this help
+
+Example:
+\$ sudo -u www-data /usr/bin/php admin/cli/build_theme_css.php --themes=boost --direction=ltr
+";
+
+    die;
+}
+
+if (empty($options['verbose'])) {
+    $trace = new null_progress_trace();
+} else {
+    $trace = new text_progress_trace();
+}
+
+cli_heading('Build theme css');
+
+// Determine which themes we need to build.
+$themenames = [];
+if (is_null($options['themes'])) {
+    $trace->output('No themes specified. Finding all installed themes.');
+    $themenames = array_keys(core_component::get_plugin_list('theme'));
+} else {
+    if (is_string($options['themes'])) {
+        $themenames = explode(',', $options['themes']);
+    } else {
+        cli_error('--themes must be a comma separated list of theme names');
+    }
+}
+
+$trace->output('Checking that each theme is correctly installed...');
+$themeconfigs = [];
+foreach ($themenames as $themename) {
+    if (is_null(theme_get_config_file_path($themename))) {
+        cli_error("Unable to find theme config for {$themename}");
+    }
+
+    // Load the config for the theme.
+    $themeconfigs[] = theme_config::load($themename);
+}
+
+$directions = ['ltr', 'rtl'];
+
+if (!is_null($options['direction'])) {
+    if (!in_array($options['direction'], $directions)) {
+         cli_error("--direction must be either ltr or rtl");
+    }
+
+    $directions = [$options['direction']];
+}
+
+$trace->output('Building CSS for themes: ' . implode(', ', $themenames));
+theme_build_css_for_themes($themeconfigs, $directions);
+
+exit(0);
index 34b54e6..d91e27e 100644 (file)
@@ -35,15 +35,58 @@ require_once($CFG->libdir.'/outputrenderers.php');
 require_once($CFG->libdir.'/outputrequirementslib.php');
 
 /**
- * Invalidate all server and client side caches.
+ * Returns current theme revision number.
  *
- * This method deletes the physical directory that is used to cache the theme
- * files used for serving.
- * Because it deletes the main theme cache directory all themes are reset by
- * this function.
+ * @return int
  */
-function theme_reset_all_caches() {
-    global $CFG, $PAGE;
+function theme_get_revision() {
+    global $CFG;
+
+    if (empty($CFG->themedesignermode)) {
+        if (empty($CFG->themerev)) {
+            // This only happens during install. It doesn't matter what themerev we use as long as it's positive.
+            return 1;
+        } else {
+            return $CFG->themerev;
+        }
+
+    } else {
+        return -1;
+    }
+}
+
+/**
+ * Returns current theme sub revision number. This is the revision for
+ * this theme exclusively, not the global theme revision.
+ *
+ * @param string $themename The non-frankenstyle name of the theme
+ * @return int
+ */
+function theme_get_sub_revision_for_theme($themename) {
+    global $CFG;
+
+    if (empty($CFG->themedesignermode)) {
+        $pluginname = "theme_{$themename}";
+        $revision = get_config($pluginname, 'themerev');
+
+        if (empty($revision)) {
+            // This only happens during install. It doesn't matter what themerev we use as long as it's positive.
+            return 1;
+        } else {
+            return $revision;
+        }
+    } else {
+        return -1;
+    }
+}
+
+/**
+ * Calculates and returns the next theme revision number.
+ *
+ * @return int
+ */
+function theme_get_next_revision() {
+    global $CFG;
 
     $next = time();
     if (isset($CFG->themerev) and $next <= $CFG->themerev and $CFG->themerev - $next < 60*60) {
@@ -53,7 +96,155 @@ function theme_reset_all_caches() {
         $next = $CFG->themerev+1;
     }
 
-    set_config('themerev', $next); // time is unique even when you reset/switch database
+    return $next;
+}
+
+/**
+ * Calculates and returns the next theme revision number.
+ *
+ * @param string $themename The non-frankenstyle name of the theme
+ * @return int
+ */
+function theme_get_next_sub_revision_for_theme($themename) {
+    global $CFG;
+
+    $next = time();
+    $current = theme_get_sub_revision_for_theme($themename);
+    if ($next <= $current and $current - $next < 60 * 60) {
+        // This resolves problems when reset is requested repeatedly within 1s,
+        // the < 1h condition prevents accidental switching to future dates
+        // because we might not recover from it.
+        $next = $current + 1;
+    }
+
+    return $next;
+}
+
+/**
+ * Sets the current theme revision number.
+ *
+ * @param int $revision The new theme revision number
+ */
+function theme_set_revision($revision) {
+    set_config('themerev', $revision);
+}
+
+/**
+ * Sets the current theme revision number for a specific theme.
+ * This does not affect the global themerev value.
+ *
+ * @param string $themename The non-frankenstyle name of the theme
+ * @param int    $revision  The new theme revision number
+ */
+function theme_set_sub_revision_for_theme($themename, $revision) {
+    set_config('themerev', $revision, "theme_{$themename}");
+}
+
+/**
+ * Get the path to a theme config.php file.
+ *
+ * @param string $themename The non-frankenstyle name of the theme to check
+ */
+function theme_get_config_file_path($themename) {
+    global $CFG;
+
+    if (file_exists("{$CFG->dirroot}/theme/{$themename}/config.php")) {
+        return "{$CFG->dirroot}/theme/{$themename}/config.php";
+    } else if (!empty($CFG->themedir) and file_exists("{$CFG->themedir}/{$themename}/config.php")) {
+        return "{$CFG->themedir}/{$themename}/config.php";
+    } else {
+        return null;
+    }
+}
+
+/**
+ * Get the path to the local cached CSS file.
+ *
+ * @param string $themename      The non-frankenstyle theme name.
+ * @param int    $globalrevision The global theme revision.
+ * @param int    $themerevision  The theme specific revision.
+ * @param string $direction      Either 'ltr' or 'rtl' (case sensitive).
+ */
+function theme_get_css_filename($themename, $globalrevision, $themerevision, $direction) {
+    global $CFG;
+
+    $path = "{$CFG->localcachedir}/theme/{$globalrevision}/{$themename}/css";
+    $filename = $direction == 'rtl' ? "all-rtl_{$themerevision}" : "all_{$themerevision}";
+    return "{$path}/{$filename}.css";
+}
+
+/**
+ * Generates and saves the CSS files for the given theme configs.
+ *
+ * @param theme_config[] $themeconfigs An array of theme_config instances.
+ * @param array          $directions   Must be a subset of ['rtl', 'ltr'].
+ * @param bool           $cache        Should the generated files be stored in local cache.
+ */
+function theme_build_css_for_themes($themeconfigs = [], $directions = ['rtl', 'ltr'], $cache = true) {
+    global $CFG;
+
+    if (empty($themeconfigs)) {
+        return;
+    }
+
+    require_once("{$CFG->libdir}/csslib.php");
+
+    $themescss = [];
+    $themerev = theme_get_revision();
+    // Make sure the local cache directory exists.
+    make_localcache_directory('theme');
+
+    foreach ($themeconfigs as $themeconfig) {
+        $themecss = [];
+        $oldrevision = theme_get_sub_revision_for_theme($themeconfig->name);
+        $newrevision = theme_get_next_sub_revision_for_theme($themeconfig->name);
+
+        // First generate all the new css.
+        foreach ($directions as $direction) {
+            $themeconfig->set_rtl_mode(($direction === 'rtl'));
+
+            $themecss[$direction] = $themeconfig->get_css_content();
+            if ($cache) {
+                $filename = theme_get_css_filename($themeconfig->name, $themerev, $newrevision, $direction);
+                css_store_css($themeconfig, $filename, $themecss[$direction]);
+            }
+        }
+        $themescss[] = $themecss;
+
+        if ($cache) {
+            // Only update the theme revision after we've successfully created the
+            // new CSS cache.
+            theme_set_sub_revision_for_theme($themeconfig->name, $newrevision);
+
+            // Now purge old files. We must purge all old files in the local cache
+            // because we've incremented the theme sub revision. This will leave any
+            // files with the old revision inaccessbile so we might as well removed
+            // them from disk.
+            foreach (['ltr', 'rtl'] as $direction) {
+                $oldcss = theme_get_css_filename($themeconfig->name, $themerev, $oldrevision, $direction);
+                if (file_exists($oldcss)) {
+                    unlink($oldcss);
+                }
+            }
+        }
+    }
+
+    return $themescss;
+}
+
+/**
+ * Invalidate all server and client side caches.
+ *
+ * This method deletes the physical directory that is used to cache the theme
+ * files used for serving.
+ * Because it deletes the main theme cache directory all themes are reset by
+ * this function.
+ */
+function theme_reset_all_caches() {
+    global $CFG, $PAGE;
+
+    $next = theme_get_next_revision();
+    theme_set_revision($next);
 
     if (!empty($CFG->themedesignermode)) {
         $cache = cache::make_from_params(cache_store::MODE_APPLICATION, 'core', 'themedesigner');
@@ -79,27 +270,6 @@ function theme_set_designer_mod($state) {
     theme_reset_all_caches();
 }
 
-/**
- * Returns current theme revision number.
- *
- * @return int
- */
-function theme_get_revision() {
-    global $CFG;
-
-    if (empty($CFG->themedesignermode)) {
-        if (empty($CFG->themerev)) {
-            // This only happens during install. It doesn't matter what themerev we use as long as it's positive.
-            return 1;
-        } else {
-            return $CFG->themerev;
-        }
-
-    } else {
-        return -1;
-    }
-}
-
 /**
  * Checks if the given device has a theme defined in config.php.
  *
@@ -375,7 +545,7 @@ class theme_config {
      * @var stdClass Theme settings stored in config_plugins table.
      * This can not be set in theme config.php
      */
-    public $setting = null;
+    public $settings = null;
 
     /**
      * @var bool If set to true and the theme enables the dock then  blocks will be able
@@ -791,6 +961,14 @@ class theme_config {
         if ($rev > -1) {
             $filename = right_to_left() ? 'all-rtl' : 'all';
             $url = new moodle_url("$CFG->httpswwwroot/theme/styles.php");
+            $themesubrevision = theme_get_sub_revision_for_theme($this->name);
+
+            // Provide the sub revision to allow us to invalidate cached theme CSS
+            // on a per theme basis, rather than globally.
+            if ($themesubrevision && $themesubrevision > 0) {
+                $rev .= "_{$themesubrevision}";
+            }
+
             if (!empty($CFG->slasharguments)) {
                 $slashargs = '';
                 if (!$svg) {
index cc2714f..36daa03 100644 (file)
@@ -52,17 +52,31 @@ if ($slashargument = min_get_slash_argument()) {
 
     list($themename, $rev, $type) = explode('/', $slashargument, 3);
     $themename = min_clean_param($themename, 'SAFEDIR');
-    $rev       = min_clean_param($rev, 'INT');
+    $rev       = min_clean_param($rev, 'RAW');
     $type      = min_clean_param($type, 'SAFEDIR');
 
 } else {
     $themename = min_optional_param('theme', 'standard', 'SAFEDIR');
-    $rev       = min_optional_param('rev', 0, 'INT');
+    $rev       = min_optional_param('rev', 0, 'RAW');
     $type      = min_optional_param('type', 'all', 'SAFEDIR');
     $chunk     = min_optional_param('chunk', null, 'INT');
     $usesvg    = (bool)min_optional_param('svg', '1', 'INT');
 }
 
+// Check if we received a theme sub revision which allows us
+// to handle local caching on a per theme basis.
+$values = explode('_', $rev);
+$rev = min_clean_param(array_shift($values), 'INT');
+$themesubrev = array_shift($values);
+
+if (is_null($themesubrev)) {
+    // Default to the current theme subrevision if one isn't
+    // provided in the URL.
+    $themesubrev = theme_get_sub_revision_for_theme($themename);
+} else {
+    $themesubrev = min_clean_param($themesubrev, 'INT');
+}
+
 if ($type === 'editor') {
     // The editor CSS is never chunked.
     $chunk = null;
@@ -82,8 +96,8 @@ if (file_exists("$CFG->dirroot/theme/$themename/config.php")) {
 }
 
 $candidatedir = "$CFG->localcachedir/theme/$rev/$themename/css";
-$etag = "$rev/$themename/$type";
-$candidatename = $type;
+$etag = "$rev/$themename/$type/$themesubrev";
+$candidatename = ($themesubrev > 0) ? "{$type}_{$themesubrev}" : $type;
 if (!$usesvg) {
     // Add to the sheet name, one day we'll be able to just drop this.
     $candidatedir .= '/nosvg';
@@ -119,15 +133,20 @@ $theme->force_svg_use($usesvg);
 $theme->set_rtl_mode($type === 'all-rtl' ? true : false);
 
 $themerev = theme_get_revision();
+$currentthemesubrev = theme_get_sub_revision_for_theme($themename);
 
 $cache = true;
-if ($themerev <= 0 or $themerev != $rev) {
+// If the client is requesting a revision that doesn't match both
+// the global theme revision and the theme specific revision then
+// tell the browser not to cache this style sheet because it's
+// likely being regnerated.
+if ($themerev <= 0 or $themerev != $rev or $themesubrev != $currentthemesubrev) {
     $rev = $themerev;
     $cache = false;
 
     $candidatedir = "$CFG->localcachedir/theme/$rev/$themename/css";
-    $etag = "$rev/$themename/$type";
-    $candidatename = $type;
+    $etag = "$rev/$themename/$type/$themesubrev";
+    $candidatename = ($themesubrev > 0) ? "{$type}_{$themesubrev}" : $type;
     if (!$usesvg) {
         // Add to the sheet name, one day we'll be able to just drop this.
         $candidatedir .= '/nosvg';
@@ -189,7 +208,7 @@ if ($type === 'editor') {
         }
     }
 
-    css_store_css($theme, "$candidatedir/$type.css", $csscontent, true, $chunkurl);
+    css_store_css($theme, "$candidatedir/$candidatename.css", $csscontent, true, $chunkurl);
 
     if ($lock) {
         // Now that the CSS has been generated and/or stored, release the lock.