Requirements::themedJavascript() - Code Metrics - Inspection of "Merge branch '3'" - silverstripe/silverstripe-framework - Measure and Improve Code Quality continuously with Scrutinizer

Completed
Push — master ( c7767b...f548dd )

by Daniel
created 2016-07-20 21:16 UTC
Requirements::themedJavascript() A

↳ Parent: Requirements
Complexity

Conditions	1
Paths	1
Size

Total Lines	3
Code Lines	2
Duplication

Lines	0
Ratio	0 %
Importance

Changes
Metric	Value
cc	1
eloc	2
c	0
b	0
f	0
nc	1
nop	3
dl	0
loc	3
rs	10
<?php

use SilverStripe\Filesystem\Storage\GeneratedAssetHandler;
use SilverStripe\View\TemplateLoader;

/**
 * Requirements tracker for JavaScript and CSS.
 *
 * @package framework
 * @subpackage view
 */
class Requirements implements Flushable {

	/**
	 * Flag whether combined files should be deleted on flush.
	 *
	 * By default all combined files are deleted on flush. If combined files are stored in source control,
	 * and thus updated manually, you might want to turn this on to disable this behaviour.
	 *
	 * @config
	 * @var bool
	 */
	private static $disable_flush_combined = false;

	/**
	 * Triggered early in the request when a flush is requested
	 */
	public static function flush() {
		$disabled = Config::inst()->get(static::class, 'disable_flush_combined');
		if(!$disabled) {
			self::delete_all_combined_files();
		}
	}

	/**
	 * Enable combining of css/javascript files.
	 *
	 * @param bool $enable
	 */
	public static function set_combined_files_enabled($enable) {
		self::backend()->setCombinedFilesEnabled($enable);
	}

	/**
	 * Checks whether combining of css/javascript files is enabled.
	 *
	 * @return bool
	 */
	public static function get_combined_files_enabled() {
		return self::backend()->getCombinedFilesEnabled();
	}

	/**
	 * Set the relative folder e.g. 'assets' for where to store combined files
	 *
	 * @param string $folder Path to folder
	 */
	public static function set_combined_files_folder($folder) {
		self::backend()->setCombinedFilesFolder($folder);
	}

	/**
	 * Set whether to add caching query params to the requests for file-based requirements.
	 * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
	 * filemtime. This has the benefit of allowing the browser to cache the URL infinitely,
	 * while automatically busting this cache every time the file is changed.
	 *
	 * @param bool
	 */
	public static function set_suffix_requirements($var) {
		self::backend()->setSuffixRequirements($var);
	}

	/**
	 * Check whether we want to suffix requirements
	 *
	 * @return bool
	 */
	public static function get_suffix_requirements() {
		return self::backend()->getSuffixRequirements();
	}

	/**
	 * Instance of the requirements for storage. You can create your own backend to change the
	 * default JS and CSS inclusion behaviour.
	 *
	 * @var Requirements_Backend
	 */
	private static $backend = null;

	/**
	 * @return Requirements_Backend
	 */
	public static function backend() {
		if(!self::$backend) {
			self::$backend = Injector::inst()->create('Requirements_Backend');
		}
		return self::$backend;
	}

	/**
	 * Setter method for changing the Requirements backend
	 *
	 * @param Requirements_Backend $backend
	 */
	public static function set_backend(Requirements_Backend $backend) {
		self::$backend = $backend;
	}

	/**
	 * Register the given JavaScript file as required.
	 *
	 * @param string $file Relative to docroot
	 * @param array $options List of options. Available options include:
	 * - 'provides' : List of scripts files included in this file
	 * - 'async' : Boolean value to set async attribute to script tag
	 * - 'defer' : Boolean value to set defer attribute to script tag
	 */
	public static function javascript($file, $options = array()) {
		self::backend()->javascript($file, $options);
	}

	/**
	 * Register the given JavaScript code into the list of requirements
	 *
	 * @param string     $script       The script content as a string (without enclosing <script> tag)
	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public static function customScript($script, $uniquenessID = null) {
		self::backend()->customScript($script, $uniquenessID);
	}

	/**
	 * Return all registered custom scripts
	 *
	 * @return array
	 */
	public static function get_custom_scripts() {
		return self::backend()->getCustomScripts();
	}

	/**
	 * Register the given CSS styles into the list of requirements
	 *
	 * @param string     $script       CSS selectors as a string (without enclosing <style> tag)
	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public static function customCSS($script, $uniquenessID = null) {
		self::backend()->customCSS($script, $uniquenessID);
	}

	/**
	 * Add the following custom HTML code to the <head> section of the page
	 *
	 * @param string     $html         Custom HTML code
	 * @param string|int $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public static function insertHeadTags($html, $uniquenessID = null) {
		self::backend()->insertHeadTags($html, $uniquenessID);
	}

	/**
	 * Include the content of the given JavaScript file in the list of requirements. Dollar-sign
	 * variables will be interpolated with values from $vars similar to a .ss template.
	 *
	 * @param string         $file         The template file to load, relative to docroot
	 * @param string[]|int[] $vars         The array of variables to interpolate.
	 * @param string|int     $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public static function javascriptTemplate($file, $vars, $uniquenessID = null) {
		self::backend()->javascriptTemplate($file, $vars, $uniquenessID);
	}

	/**
	 * Register the given stylesheet into the list of requirements.
	 *
	 * @param string $file  The CSS file to load, relative to site root
	 * @param string $media Comma-separated list of media types to use in the link tag
	 *                      (e.g. 'screen,projector')
	 */
	public static function css($file, $media = null) {
		self::backend()->css($file, $media);
	}

	/**
	 * Registers the given themeable stylesheet as required.
	 *
	 * A CSS file in the current theme path name 'themename/css/$name.css' is first searched for,
	 * and it that doesn't exist and the module parameter is set then a CSS file with that name in
	 * the module is used.
	 *
	 * @param string $name   The name of the file - eg '/css/File.css' would have the name 'File'
	 * @param string $module The module to fall back to if the css file does not exist in the
	 *                       current theme.
	 * @param string $media  Comma-separated list of media types to use in the link tag
	 *                       (e.g. 'screen,projector')
	 */
	public static function themedCSS($name, $module = null, $media = null) {
		self::backend()->themedCSS($name, $module, $media);
	}

	/**
	 * Registers the given themeable javascript as required.
	 *
	 * A javascript file in the current theme path name 'themename/javascript/$name.js' is first searched for,
	 * and it that doesn't exist and the module parameter is set then a javascript file with that name in
	 * the module is used.
	 *
	 * @param string $name   The name of the file - eg '/javascript/File.js' would have the name 'File'
	 * @param string $module The module to fall back to if the javascript file does not exist in the
	 *                       current theme.
	 * @param string $type  Comma-separated list of types to use in the script tag
	 *                       (e.g. 'text/javascript,text/ecmascript')
	 */
	public static function themedJavascript($name, $module = null, $type = null) {
		return self::backend()->themedJavascript($name, $module, $type);
	}

	/**
	 * Clear either a single or all requirements
	 *
	 * Caution: Clearing single rules added via customCSS and customScript only works if you
	 * originally specified a $uniquenessID.
	 *
	 * @param string|int $fileOrID
	 */
	public static function clear($fileOrID = null) {
		self::backend()->clear($fileOrID);
	}

	/**
	 * Restore requirements cleared by call to Requirements::clear
	 */
	public static function restore() {
		self::backend()->restore();
	}

	/**
	 * Block inclusion of a specific file
	 *
	 * The difference between this and {@link clear} is that the calling order does not matter;
	 * {@link clear} must be called after the initial registration, whereas {@link block} can be
	 * used in advance. This is useful, for example, to block scripts included by a superclass
	 * without having to override entire functions and duplicate a lot of code.
	 *
	 * Note that blocking should be used sparingly because it's hard to trace where an file is
	 * being blocked from.
	 *
	 * @param string|int $fileOrID
	 */
	public static function block($fileOrID) {
		self::backend()->block($fileOrID);
	}

	/**
	 * Remove an item from the block list
	 *
	 * @param string|int $fileOrID
	 */
	public static function unblock($fileOrID) {
		self::backend()->unblock($fileOrID);
	}

	/**
	 * Removes all items from the block list
	 */
	public static function unblock_all() {
		self::backend()->unblockAll();
	}

	/**
	 * Update the given HTML content with the appropriate include tags for the registered
	 * requirements. Needs to receive a valid HTML/XHTML template in the $content parameter,
	 * including a head and body tag.
	 *
	 * @param string $content      HTML content that has already been parsed from the $templateFile
	 *                             through {@link SSViewer}
	 * @return string HTML content augmented with the requirements tags
	 */
	public static function includeInHTML($content) {
		if(func_num_args() > 1) {
			Deprecation::notice(
				'5.0',
				'$templateFile argument is deprecated. includeInHTML takes a sole $content parameter now.'
			);
			$content = func_get_arg(1);
		}

		return self::backend()->includeInHTML($content);
	}

	/**
	 * Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given
	 * HTTP Response
	 *
	 * @param SS_HTTPResponse $response
	 */
	public static function include_in_response(SS_HTTPResponse $response) {
		self::backend()->includeInResponse($response);
	}

	/**
	 * Add i18n files from the given javascript directory. SilverStripe expects that the given
	 * directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js,
	 * etc.
	 *
	 * @param string $langDir  The JavaScript lang directory, relative to the site root, e.g.,
	 *                         'framework/javascript/lang'
	 * @param bool   $return   Return all relative file paths rather than including them in
	 *                         requirements
	 * @param bool   $langOnly Only include language files, not the base libraries
	 *
	 * @return array
	 */
	public static function add_i18n_javascript($langDir, $return = false, $langOnly = false) {
		return self::backend()->add_i18n_javascript($langDir, $return, $langOnly);
	}

	/**
	 * Concatenate several css or javascript files into a single dynamically generated file. This
	 * increases performance by fewer HTTP requests.
	 *
	 * The combined file is regenerated based on every file modification time. Optionally a
	 * rebuild can be triggered by appending ?flush=1 to the URL.
	 *
	 * All combined files will have a comment on the start of each concatenated file denoting their
	 * original position.
	 *
	 * CAUTION: You're responsible for ensuring that the load order for combined files is
	 * retained - otherwise combining JavaScript files can lead to functional errors in the
	 * JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also
	 * only include each file once across all includes and comibinations in a single page load.
	 *
	 * CAUTION: Combining CSS Files discards any "media" information.
	 *
	 * Example for combined JavaScript:
	 * <code>
	 * Requirements::combine_files(
	 *  'foobar.js',
	 *  array(
	 *        'mysite/javascript/foo.js',
	 *        'mysite/javascript/bar.js',
	 *    )
	 * );
	 * </code>
	 *
	 * Example for combined CSS:
	 * <code>
	 * Requirements::combine_files(
	 *  'foobar.css',
	 *    array(
	 *        'mysite/javascript/foo.css',
	 *        'mysite/javascript/bar.css',
	 *    )
	 * );
	 * </code>
	 *
	 * @param string $combinedFileName Filename of the combined file relative to docroot
	 * @param array  $files            Array of filenames relative to docroot
	 * @param array  $options          Array of options for combining files. Available options are:
	 * - 'media' : If including CSS Files, you can specify a media type
	 * - 'async' : If including JavaScript Files, boolean value to set async attribute to script tag
	 * - 'defer' : If including JavaScript Files, boolean value to set defer attribute to script tag
	 *
	 * @return bool|void
	 */
	public static function combine_files($combinedFileName, $files, $options = array()) {
        if(is_string($options))  {
            Deprecation::notice('4.0', 'Parameter media is deprecated. Use options array instead.');
            $options = array('media' => $options);
        }
		self::backend()->combineFiles($combinedFileName, $files, $options);
	}

	/**
	 * Return all combined files; keys are the combined file names, values are lists of
	 * associative arrays with 'files', 'type', and 'media' keys for details about this
	 * combined file.
	 *
	 * @return array
	 */
	public static function get_combine_files() {
		return self::backend()->getCombinedFiles();
	}

	/**
	 * Deletes all generated combined files in the configured combined files directory,
	 * but doesn't delete the directory itself
	 */
	public static function delete_all_combined_files() {
		self::backend()->deleteAllCombinedFiles();
	}

	/**
	 * Re-sets the combined files definition. See {@link Requirements_Backend::clear_combined_files()}
	 */
	public static function clear_combined_files() {
		self::backend()->clearCombinedFiles();
	}

	/**
	 * Do the heavy lifting involved in combining the combined files.
 	 */
	public static function process_combined_files() {
		self::backend()->processCombinedFiles();
	}

	/**
	 * Set whether you want to write the JS to the body of the page rather than at the end of the
	 * head tag.
	 *
	 * @return bool
	 */
	public static function get_write_js_to_body() {
		return self::backend()->getWriteJavascriptToBody();
	}

	/**
	 * Set whether you want to write the JS to the body of the page rather than at the end of the
	 * head tag.
	 *
	 * @param bool
	 */
	public static function set_write_js_to_body($var) {
		self::backend()->setWriteJavascriptToBody($var);
	}

	/**
	 * Get whether to force the JavaScript to end of the body. Useful if you use inline script tags
	 * that don't rely on scripts included via {@link Requirements::javascript()).
	 *
	 * @return bool
	 */
	public static function get_force_js_to_bottom() {
		return self::backend()->getForceJSToBottom();
	}

	/**
	 * Set whether to force the JavaScript to end of the body. Useful if you use inline script tags
	 * that don't rely on scripts included via {@link Requirements::javascript()).
	 *
	 * @param bool $var If true, force the JavaScript to be included at the bottom of the page
	 */
	public static function set_force_js_to_bottom($var) {
		self::backend()->setForceJSToBottom($var);
	}

	/**
	 * Check if JS minification is enabled
	 *
	 * @return bool
	 */
	public static function get_minify_combined_js_files() {
		return self::backend()->getMinifyCombinedJSFiles();
	}

	/**
	 * Enable or disable js minification
	 *
	 * @param bool $minify
	 */
	public static function set_minify_combined_js_files($minify) {
		self::backend()->setMinifyCombinedJSFiles($minify);
	}

	/**
	 * Check if header comments are written
	 *
	 * @return bool
	 */
	public static function get_write_header_comments() {
		return self::backend()->getWriteHeaderComment();
	}

	/**
	 * Flag whether header comments should be written for each combined file
	 *
	 * @param bool $write
	 */
	public function set_write_header_comments($write) {
		self::backend()->setWriteHeaderComment($write);
	}


	/**
	 * Output debugging information
	 */
	public static function debug() {
		self::backend()->debug();
	}

}

/**
 * @package framework
 * @subpackage view
 */
class Requirements_Backend
{

	/**
	 * Whether to add caching query params to the requests for file-based requirements.
	 * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
	 * filemtime. This has the benefit of allowing the browser to cache the URL infinitely,
	 * while automatically busting this cache every time the file is changed.
	 *
	 * @var bool
	 */
	protected $suffixRequirements = true;

	/**
	 * Whether to combine CSS and JavaScript files
	 *
	 * @var bool
	 */
	protected $combinedFilesEnabled = true;

	/**
	 * Determine if files should be combined automatically on dev mode.
	 *
	 * By default combined files will not be combined except in test or
	 * live environments. Turning this on will allow for pre-combining of files in development mode.
	 *
	 * @config
	 * @var bool
	 */
	private static $combine_in_dev = false;

	/**
	 * Paths to all required JavaScript files relative to docroot
	 *
	 * @var array
	 */
	protected $javascript = array();

	/**
	 * Map of included scripts to array of contained files.
	 * To be used alongside front-end combination mechanisms.
	 *
	 * @var array Map of providing filepath => array(provided filepaths)
	 */
	protected $providedJavascript = array();

	/**
	 * Paths to all required CSS files relative to the docroot.
	 *
	 * @var array
	 */
	protected $css = array();

	/**
	 * All custom javascript code that is inserted into the page's HTML
	 *
	 * @var array
	 */
	protected $customScript = array();

	/**
	 * All custom CSS rules which are inserted directly at the bottom of the HTML <head> tag
	 *
	 * @var array
	 */
	protected $customCSS = array();

	/**
	 * All custom HTML markup which is added before the closing <head> tag, e.g. additional
	 * metatags.
	 *
	 * @var array
	 */
	protected $customHeadTags = array();

	/**
	 * Remembers the file paths or uniquenessIDs of all Requirements cleared through
	 * {@link clear()}, so that they can be restored later.
	 *
	 * @var array
	 */
	protected $disabled = array();

	/**
	 * The file paths (relative to docroot) or uniquenessIDs of any included requirements which
	 * should be blocked when executing {@link inlcudeInHTML()}. This is useful, for example,
	 * to block scripts included by a superclass without having to override entire functions and
	 * duplicate a lot of code.
	 *
	 * Use {@link unblock()} or {@link unblock_all()} to revert changes.
	 *
	 * @var array
	 */
	protected $blocked = array();

	/**
	 * A list of combined files registered via {@link combine_files()}. Keys are the output file
	 * names, values are lists of input files.
	 *
	 * @var array
	 */
	protected $combinedFiles = array();

	/**
	 * Use the JSMin library to minify any javascript file passed to {@link combine_files()}.
	 *
	 * @var bool
	 */
	protected $minifyCombinedJSFiles = true;

	/**
	 * Whether or not file headers should be written when combining files
	 *
	 * @var boolean
	 */
	protected $writeHeaderComment = true;

	/**
	 * Where to save combined files. By default they're placed in assets/_combinedfiles, however
	 * this may be an issue depending on your setup, especially for CSS files which often contain
	 * relative paths.
	 *
	 * @var string
	 */
	protected $combinedFilesFolder = null;

	/**
	 * Put all JavaScript includes at the bottom of the template before the closing <body> tag,
	 * rather than the default behaviour of placing them at the end of the <head> tag. This means
	 * script downloads won't block other HTTP requests, which can be a performance improvement.
	 *
	 * @var bool
	 */
	public $writeJavascriptToBody = true;

	/**
	 * Force the JavaScript to the bottom of the page, even if there's a script tag in the body already
	 *
	 * @var boolean
	 */
	protected $forceJSToBottom = false;

	/**
	 * Configures the default prefix for combined files.
	 *
	 * This defaults to `_combinedfiles`, and is the folder within the configured asset backend that
	 * combined files will be stored in. If using a backend shared with other systems, it is usually
	 * necessary to distinguish combined files from other assets.
	 *
	 * @config
	 * @var string
	 */
	private static $default_combined_files_folder = '_combinedfiles';

	/**
	 * Flag to include the hash in the querystring instead of the filename for combined files.
	 *
	 * By default the `<hash>` of the source files is appended to the end of the combined file
	 * (prior to the file extension). If combined files are versioned in source control or running
	 * in a distributed environment (such as one where the newest version of a file may not always be
	 * immediately available) then it may sometimes be necessary to disable this. When this is set to true,
	 * the hash will instead be appended via a querystring parameter to enable cache busting, but not in
	 * the filename itself. I.e. `assets/_combinedfiles/name.js?m=<hash>`
	 *
	 * @config
	 * @var bool
	 */
	private static $combine_hash_querystring = false;

	/**
	 * @var GeneratedAssetHandler
	 */
	protected $assetHandler = null;

	/**
	 * Gets the backend storage for generated files
	 *
	 * @return GeneratedAssetHandler
	 */
	public function getAssetHandler() {
		return $this->assetHandler;
	}

	/**
	 * Set a new asset handler for this backend
	 *
	 * @param GeneratedAssetHandler $handler
	 */
	public function setAssetHandler(GeneratedAssetHandler $handler) {
		$this->assetHandler = $handler;
	}

	/**
	 * Enable or disable the combination of CSS and JavaScript files
	 *
	 * @param bool $enable
	 */
	public function setCombinedFilesEnabled($enable) {
		$this->combinedFilesEnabled = (bool) $enable;
	}

	/**
	 * Check if header comments are written
	 *
	 * @return bool
	 */
	public function getWriteHeaderComment() {
		return $this->writeHeaderComment;
	}

	/**
	 * Flag whether header comments should be written for each combined file
	 *
	 * @param bool $write
	 * @return $this
	 */
	public function setWriteHeaderComment($write) {
		$this->writeHeaderComment = $write;
		return $this;
	}

	/**
	 * Set the folder to save combined files in. By default they're placed in _combinedfiles,
	 * however this may be an issue depending on your setup, especially for CSS files which often
	 * contain relative paths.
	 *
	 * This must not include any 'assets' prefix
	 *
	 * @param string $folder
	 */
	public function setCombinedFilesFolder($folder) {
		$this->combinedFilesFolder = $folder;
	}

	/**
	 * Retrieve the combined files folder prefix
	 *
	 * @return string
	 */
	public function getCombinedFilesFolder() {
		if($this->combinedFilesFolder) {
			return $this->combinedFilesFolder;
		}
		return Config::inst()->get(__CLASS__, 'default_combined_files_folder');
	}

	/**
	 * Set whether to add caching query params to the requests for file-based requirements.
	 * Eg: themes/myTheme/js/main.js?m=123456789. The parameter is a timestamp generated by
	 * filemtime. This has the benefit of allowing the browser to cache the URL infinitely,
	 * while automatically busting this cache every time the file is changed.
	 *
	 * @param bool
	 */
	public function setSuffixRequirements($var) {
		$this->suffixRequirements = $var;
	}

	/**
	 * Check whether we want to suffix requirements
	 *
	 * @return bool
	 */
	public function getSuffixRequirements() {
		return $this->suffixRequirements;
	}

	/**
	 * Set whether you want to write the JS to the body of the page rather than at the end of the
	 * head tag.
	 *
	 * @param bool
	 * @return $this
	 */
	public function setWriteJavascriptToBody($var) {
		$this->writeJavascriptToBody = $var;
		return $this;
	}

	/**
	 * Check whether you want to write the JS to the body of the page rather than at the end of the
	 * head tag.
	 *
	 * @return bool
	 */
	public function getWriteJavascriptToBody() {
		return $this->writeJavascriptToBody;
	}

	/**
	 * Forces the JavaScript requirements to the end of the body, right before the closing tag
	 *
	 * @param bool
	 * @return $this
	 */
	public function setForceJSToBottom($var) {
		$this->forceJSToBottom = $var;
		return $this;
	}

	/**
	 * Check if the JavaScript requirements are written to the end of the body, right before the closing tag
	 *
	 * @return bool
	 */
	public function getForceJSToBottom() {
		return $this->forceJSToBottom;
	}

	/**
	 * Check if minify js files should be combined
	 *
	 * @return bool
	 */
	public function getMinifyCombinedJSFiles() {
		return $this->minifyCombinedJSFiles;
	}

	/**
	 * Set if combined js files should be minified
	 *
	 * @param bool $minify
	 * @return $this
	 */
	public function setMinifyCombinedJSFiles($minify) {
		$this->minifyCombinedJSFiles = $minify;
		return $this;
	}

	/**
	 * Register the given JavaScript file as required.
	 *
	 * @param string $file Relative to docroot
	 * @param array $options List of options. Available options include:
	 * - 'provides' : List of scripts files included in this file
	 * - 'async' : Boolean value to set async attribute to script tag
	 * - 'defer' : Boolean value to set defer attribute to script tag
	 */
	public function javascript($file, $options = array()) {
	    // make sure that async/defer is set if it is set once even if file is included multiple times
        $async = (
            isset($options['async']) && isset($options['async']) == true

            || (
                isset($this->javascript[$file])
                && isset($this->javascript[$file]['async'])
                && $this->javascript[$file]['async'] == true
            )
        );
        $defer = (
            isset($options['defer']) && isset($options['defer']) == true

            || (
                isset($this->javascript[$file])
                && isset($this->javascript[$file]['defer'])
                && $this->javascript[$file]['defer'] == true
            )
        );
        $this->javascript[$file] = array(
            'async' => $async,
            'defer' => $defer,
        );

		// Record scripts included in this file
		if(isset($options['provides'])) {
			$this->providedJavascript[$file] = array_values($options['provides']);
	    }

	}

	/**
	 * Remove a javascript requirement
	 *
	 * @param string $file
	 */
	protected function unsetJavascript($file) {
		unset($this->javascript[$file]);
	}

	/**
	 * Gets all scripts that are already provided by prior scripts.
	 * This follows these rules:
	 *  - Files will not be considered provided if they are separately
	 *    included prior to the providing file.
	 *  - Providing files can be blocked, and don't provide anything
	 *  - Provided files can't be blocked (you need to block the provider)
	 *  - If a combined file includes files that are provided by prior
	 *    scripts, then these should be excluded from the combined file.
	 *  - If a combined file includes files that are provided by later
	 *    scripts, then these files should be included in the combined
	 *    file, but we can't block the later script either (possible double
	 *    up of file).
	 *
	 * @return array Array of provided files (map of $path => $path)
	 */
	public function getProvidedScripts() {
		$providedScripts = array();
		$includedScripts = array();
		foreach($this->javascript as $script => $options) {
			// Ignore scripts that are explicitly blocked
			if(isset($this->blocked[$script])) {
				continue;
			}
			// At this point, the file is included.
			// This might also be combined at this point, potentially.
			$includedScripts[$script] = true;

			// Record any files this provides, EXCEPT those already included by now
			if(isset($this->providedJavascript[$script])) {
				foreach($this->providedJavascript[$script] as $provided) {
					if(!isset($includedScripts[$provided])) {
						$providedScripts[$provided] = $provided;
					}
				}
			}
		}
		return $providedScripts;
	}

	/**
	 * Returns an array of required JavaScript, excluding blocked
	 * and duplicates of provided files.
	 *
	 * @return array
	 */
	public function getJavascript() {
		return array_diff_key(
			$this->javascript,
			$this->getBlocked(),
			$this->getProvidedScripts()
		);
	}

	/**
	 * Gets all javascript, including blocked files. Unwraps the array into a non-associative list
	 *
	 * @return array Indexed array of javascript files
	 */
	protected function getAllJavascript() {
		return $this->javascript;
	}

	/**
	 * Register the given JavaScript code into the list of requirements
	 *
	 * @param string     $script       The script content as a string (without enclosing <script> tag)
	 * @param string $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public function customScript($script, $uniquenessID = null) {
		if($uniquenessID) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
			$this->customScript[$uniquenessID] = $script;
		} else {
			$this->customScript[] = $script;
		}
	}

	/**
	 * Return all registered custom scripts
	 *
	 * @return array
	 */
	public function getCustomScripts() {
		return array_diff_key($this->customScript, $this->blocked);
	}

	/**
	 * Register the given CSS styles into the list of requirements
	 *
	 * @param string     $script       CSS selectors as a string (without enclosing <style> tag)
	 * @param string $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public function customCSS($script, $uniquenessID = null) {
		if($uniquenessID) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
			$this->customCSS[$uniquenessID] = $script;
		} else {
			$this->customCSS[] = $script;
		}
	}

	/**
	 * Return all registered custom CSS
	 *
	 * @return array
	 */
	public function getCustomCSS() {
		return array_diff_key($this->customCSS, $this->blocked);
	}

	/**
	 * Add the following custom HTML code to the <head> section of the page
	 *
	 * @param string     $html         Custom HTML code
	 * @param string $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public function insertHeadTags($html, $uniquenessID = null) {
		if($uniquenessID) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
			$this->customHeadTags[$uniquenessID] = $html;
		} else {
			$this->customHeadTags[] = $html;
		}
	}

	/**
	 * Return all custom head tags
	 *
	 * @return array
	 */
	public function getCustomHeadTags() {
		return array_diff_key($this->customHeadTags, $this->blocked);
	}

	/**
	 * Include the content of the given JavaScript file in the list of requirements. Dollar-sign
	 * variables will be interpolated with values from $vars similar to a .ss template.
	 *
	 * @param string         $file         The template file to load, relative to docroot
	 * @param string[] $vars The array of variables to interpolate.
	 * @param string $uniquenessID A unique ID that ensures a piece of code is only added once
	 */
	public function javascriptTemplate($file, $vars, $uniquenessID = null) {
		$script = file_get_contents(Director::getAbsFile($file));
		$search = array();
		$replace = array();

		if($vars) foreach($vars as $k => $v) {

			$search[] = '$' . $k;
			$replace[] = str_replace("\\'","'", Convert::raw2js($v));
		}

		$script = str_replace($search, $replace, $script);
		$this->customScript($script, $uniquenessID);
	}

	/**
	 * Register the given stylesheet into the list of requirements.
	 *
	 * @param string $file  The CSS file to load, relative to site root
	 * @param string $media Comma-separated list of media types to use in the link tag
	 *                      (e.g. 'screen,projector')
	 */
	public function css($file, $media = null) {
		$this->css[$file] = array(
			"media" => $media
		);
	}

	/**
	 * Remove a css requirement
	 *
	 * @param string $file
	 */
	protected function unsetCSS($file) {
		unset($this->css[$file]);
	}

	/**
	 * Get the list of registered CSS file requirements, excluding blocked files
	 *
	 * @return array Associative array of file to spec
	 */
	public function getCSS() {
		return array_diff_key($this->css, $this->blocked);
	}

	/**
	 * Gets all CSS files requirements, including blocked
	 *
	 * @return array Associative array of file to spec
	 */
	protected function getAllCSS() {
		return $this->css;
	}

	/**
	 * Gets the list of all blocked files
	 *
	 * @return array
	 */
	public function getBlocked() {
		return $this->blocked;
	}

	/**
	 * Clear either a single or all requirements
	 *
	 * Caution: Clearing single rules added via customCSS and customScript only works if you
	 * originally specified a $uniquenessID.
	 *
	 * @param string|int $fileOrID
	 */
	public function clear($fileOrID = null) {
		if($fileOrID) {
			foreach(array('javascript','css', 'customScript', 'customCSS', 'customHeadTags') as $type) {
				if(isset($this->{$type}[$fileOrID])) {
					$this->disabled[$type][$fileOrID] = $this->{$type}[$fileOrID];
					unset($this->{$type}[$fileOrID]);
				}
			}
		} else {
			$this->disabled['javascript'] = $this->javascript;
			$this->disabled['css'] = $this->css;
			$this->disabled['customScript'] = $this->customScript;
			$this->disabled['customCSS'] = $this->customCSS;
			$this->disabled['customHeadTags'] = $this->customHeadTags;

			$this->javascript = array();
			$this->css = array();
			$this->customScript = array();
			$this->customCSS = array();
			$this->customHeadTags = array();
		}
	}

	/**
	 * Restore requirements cleared by call to Requirements::clear
	 */
	public function restore() {
		$this->javascript = $this->disabled['javascript'];
		$this->css = $this->disabled['css'];
		$this->customScript = $this->disabled['customScript'];
		$this->customCSS = $this->disabled['customCSS'];
		$this->customHeadTags = $this->disabled['customHeadTags'];
	}

	/**
	 * Block inclusion of a specific file
	 *
	 * The difference between this and {@link clear} is that the calling order does not matter;
	 * {@link clear} must be called after the initial registration, whereas {@link block} can be
	 * used in advance. This is useful, for example, to block scripts included by a superclass
	 * without having to override entire functions and duplicate a lot of code.
	 *
	 * Note that blocking should be used sparingly because it's hard to trace where an file is
	 * being blocked from.
	 *
	 * @param string|int $fileOrID
	 */
	public function block($fileOrID) {
		$this->blocked[$fileOrID] = $fileOrID;
	}

	/**
	 * Remove an item from the block list
	 *
	 * @param string|int $fileOrID
	 */
	public function unblock($fileOrID) {
		unset($this->blocked[$fileOrID]);
	}

	/**
	 * Removes all items from the block list
	 */
	public function unblockAll() {
		$this->blocked = array();
	}

	/**
	 * Update the given HTML content with the appropriate include tags for the registered
	 * requirements. Needs to receive a valid HTML/XHTML template in the $content parameter,
	 * including a head and body tag.
	 *
	 * @param string $content      HTML content that has already been parsed from the $templateFile
	 *                             through {@link SSViewer}
	 * @return string HTML content augmented with the requirements tags
	 */
	public function includeInHTML($content) {
		if(func_num_args() > 1) {
			Deprecation::notice(
				'5.0',
				'$templateFile argument is deprecated. includeInHTML takes a sole $content parameter now.'
			);
			$content = func_get_arg(1);
		}

		// Skip if content isn't injectable, or there is nothing to inject
		$tagsAvailable = preg_match('#</head\b#', $content);
		$hasFiles = $this->css || $this->javascript || $this->customCSS || $this->customScript || $this->customHeadTags;

		if(!$tagsAvailable || !$hasFiles) {
			return $content;
		}
		$requirements = '';
		$jsRequirements = '';

		// Combine files - updates $this->javascript and $this->css
		$this->processCombinedFiles();

		foreach($this->getJavascript() as $file => $attributes) {
		    $async = (isset($attributes['async']) && $attributes['async'] == true) ? " async" : "";
		    $defer = (isset($attributes['defer']) && $attributes['defer'] == true) ? " defer" : "";
			$path = Convert::raw2att($this->pathForFile($file));

			if($path) {
				$jsRequirements .= "<script type=\"application/javascript\" src=\"$path\"{$async}{$defer}></script>";
			}
		}

		// Add all inline JavaScript *after* including external files they might rely on
		foreach($this->getCustomScripts() as $script) {
			$jsRequirements .= "<script type=\"application/javascript\">//<![CDATA[\n";
			$jsRequirements .= "$script\n";
			$jsRequirements .= "//]]></script>";
		}

		foreach($this->getCSS() as $file => $params) {
			$path = Convert::raw2att($this->pathForFile($file));

			if($path) {
				$media = (isset($params['media']) && !empty($params['media']))
					? " media=\"{$params['media']}\"" : "";
				$requirements .= "<link rel=\"stylesheet\" type=\"text/css\" {$media} href=\"$path\" />\n";
			}
		}

		foreach($this->getCustomCSS() as $css) {
			$requirements .= "<style type=\"text/css\">\n$css\n</style>\n";
		}

		foreach($this->getCustomHeadTags() as $customHeadTag) {
			$requirements .= "$customHeadTag\n";
		}

		// Inject CSS  into body
		$content = $this->insertTagsIntoHead($requirements, $content);

		// Inject scripts
		if ($this->getForceJSToBottom()) {
			$content = $this->insertScriptsAtBottom($jsRequirements, $content);
		} elseif($this->getWriteJavascriptToBody()) {
			$content = $this->insertScriptsIntoBody($jsRequirements, $content);
		} else {
			$content = $this->insertTagsIntoHead($jsRequirements, $content);
		}
		return $content;
	}

	/**
	 * Given a block of HTML, insert the given scripts at the bottom before
	 * the closing </body> tag
	 *
	 * @param string $jsRequirements String containing one or more javascript <script /> tags
	 * @param string $content HTML body
	 * @return string Merged HTML
	 */
	protected function insertScriptsAtBottom($jsRequirements, $content) {
		// Forcefully put the scripts at the bottom of the body instead of before the first
		// script tag.
		$content = preg_replace(
			'/(<\/body[^>]*>)/i',
			$this->escapeReplacement($jsRequirements) . '\\1',
			$content
		);
		return $content;
	}

	/**
	 * Given a block of HTML, insert the given scripts inside the <body></body>
	 *
	 * @param string $jsRequirements String containing one or more javascript <script /> tags
	 * @param string $content HTML body
	 * @return string Merged HTML
	 */
	protected function insertScriptsIntoBody($jsRequirements, $content) {
		// If your template already has script tags in the body, then we try to put our script
		// tags just before those. Otherwise, we put it at the bottom.
		$bodyTagPosition = stripos($content, '<body');
		$scriptTagPosition = stripos($content, '<script', $bodyTagPosition);

		$commentTags = array();
		$canWriteToBody = ($scriptTagPosition !== false)
			&&
			// Check that the script tag is not inside a html comment tag
			!(
				preg_match('/.*(?|(<!--)|(-->))/U', $content, $commentTags, 0, $scriptTagPosition)
				&&
				$commentTags[1] == '-->'
			);

		if($canWriteToBody) {
			// Insert content before existing script tags
			$content = substr($content, 0, $scriptTagPosition)
				. $jsRequirements
				. substr($content, $scriptTagPosition);
		} else {
			// Insert content at bottom of page otherwise
			$content = $this->insertScriptsAtBottom($jsRequirements, $content);
		}

		return $content;
	}

	/**
	 * Given a block of HTML, insert the given code inside the <head></head> block
	 *
	 * @param string $jsRequirements String containing one or more html tags
	 * @param string $content HTML body
	 * @return string Merged HTML
	 */
	protected function insertTagsIntoHead($jsRequirements, $content) {
		$content = preg_replace(
			'/(<\/head>)/i',
			$this->escapeReplacement($jsRequirements) . '\\1',
			$content
		);
		return $content;
	}

	/**
	 * Safely escape a literal string for use in preg_replace replacement
	 *
	 * @param string $replacement
	 * @return string
	 */
	protected function escapeReplacement($replacement) {
		return addcslashes($replacement, '\\$');
	}

	/**
	 * Attach requirements inclusion to X-Include-JS and X-Include-CSS headers on the given
	 * HTTP Response
	 *
	 * @param SS_HTTPResponse $response
	 */
	public function includeInResponse(SS_HTTPResponse $response) {
		$this->processCombinedFiles();
		$jsRequirements = array();
		$cssRequirements = array();

		foreach($this->getJavascript() as $file => $attributes) {
			$path = $this->pathForFile($file);
			if($path) {
				$jsRequirements[] = str_replace(',', '%2C', $path);
			}
		}

		if(count($jsRequirements)) {
			$response->addHeader('X-Include-JS', implode(',', $jsRequirements));
		}

		foreach($this->getCSS() as $file => $params) {
			$path = $this->pathForFile($file);
			if($path) {
				$path = str_replace(',', '%2C', $path);
				$cssRequirements[] = isset($params['media']) ? "$path:##:$params[media]" : $path;
			}
		}

		if(count($cssRequirements)) {
			$response->addHeader('X-Include-CSS', implode(',', $cssRequirements));
		}
	}

	/**
	 * Add i18n files from the given javascript directory. SilverStripe expects that the given
	 * directory will contain a number of JavaScript files named by language: en_US.js, de_DE.js,
	 * etc.
	 *
	 * @param string $langDir  The JavaScript lang directory, relative to the site root, e.g.,
	 *                         'framework/javascript/lang'
	 * @param bool   $return   Return all relative file paths rather than including them in
	 *                         requirements
	 * @param bool   $langOnly Only include language files, not the base libraries
	 *
	 * @return array|null All relative files if $return is true, or null otherwise
	 */
	public function add_i18n_javascript($langDir, $return = false, $langOnly = false) {
		$files = array();
		$base = Director::baseFolder() . '/';
		if(i18n::config()->js_i18n) {
			// Include i18n.js even if no languages are found.  The fact that
			// add_i18n_javascript() was called indicates that the methods in
			// here are needed.
			if(!$langOnly) $files[] = FRAMEWORK_DIR . '/client/dist/js/i18n.js';

			if(substr($langDir,-1) != '/') $langDir .= '/';

			$candidates = array(
				'en.js',
				'en_US.js',
				i18n::get_lang_from_locale(i18n::config()->default_locale) . '.js',
				i18n::config()->default_locale . '.js',
				i18n::get_lang_from_locale(i18n::get_locale()) . '.js',
				i18n::get_locale() . '.js',
			);
			foreach($candidates as $candidate) {
				if(file_exists($base . DIRECTORY_SEPARATOR . $langDir . $candidate)) {
					$files[] = $langDir . $candidate;
				}
			}
		} else {
			// Stub i18n implementation for when i18n is disabled.
			if(!$langOnly) {
				$files[] = FRAMEWORK_DIR . '/client/dist/js/i18nx.js';
			}
		}

		if($return) {
			return $files;
		} else {
			foreach($files as $file) {
				$this->javascript($file);
			}
			return null;
		}
	}

	/**
	 * Finds the path for specified file
	 *
	 * @param string $fileOrUrl
	 * @return string|bool
	 */
	protected function pathForFile($fileOrUrl) {
		// Since combined urls could be root relative, treat them as urls here.
		if(preg_match('{^(//)|(http[s]?:)}', $fileOrUrl) || Director::is_root_relative_url($fileOrUrl)) {
			return $fileOrUrl;
		} elseif(Director::fileExists($fileOrUrl)) {
			$filePath = preg_replace('/\?.*/', '', Director::baseFolder() . '/' . $fileOrUrl);
			$prefix = Director::baseURL();
			$mtimesuffix = "";
			$suffix = '';
			if($this->getSuffixRequirements()) {
				$mtimesuffix = "?m=" . filemtime($filePath);
				$suffix = '&';
			}
			if(strpos($fileOrUrl, '?') !== false) {
				if (strlen($suffix) == 0) {
					$suffix = '?';
				}
				$suffix .= substr($fileOrUrl, strpos($fileOrUrl, '?')+1);
				$fileOrUrl = substr($fileOrUrl, 0, strpos($fileOrUrl, '?'));
			} else {
				$suffix = '';
			}
			return "{$prefix}{$fileOrUrl}{$mtimesuffix}{$suffix}";
		} else {
			throw new InvalidArgumentException("File {$fileOrUrl} does not exist");
		}
	}

	/**
	 * Concatenate several css or javascript files into a single dynamically generated file. This
	 * increases performance by fewer HTTP requests.
	 *
	 * The combined file is regenerated based on every file modification time. Optionally a
	 * rebuild can be triggered by appending ?flush=1 to the URL.
	 *
	 * All combined files will have a comment on the start of each concatenated file denoting their
	 * original position.
	 *
	 * CAUTION: You're responsible for ensuring that the load order for combined files is
	 * retained - otherwise combining JavaScript files can lead to functional errors in the
	 * JavaScript logic, and combining CSS can lead to incorrect inheritance. You can also
	 * only include each file once across all includes and combinations in a single page load.
	 *
	 * CAUTION: Combining CSS Files discards any "media" information.
	 *
	 * Example for combined JavaScript:
	 * <code>
	 * Requirements::combine_files(
	 *    'foobar.js',
	 *    array(
	 *        'mysite/javascript/foo.js',
	 *        'mysite/javascript/bar.js',
	 *    ),
	 *    array(
	 *        'async' => true,
	 *        'defer' => true,
	 *    )
	 * );
	 * </code>
	 *
	 * Example for combined CSS:
	 * <code>
	 * Requirements::combine_files(
	 *    'foobar.css',
	 *    array(
	 *        'mysite/javascript/foo.css',
	 *        'mysite/javascript/bar.css',
	 *    ),
	 *    array(
	 *        'media' => 'print',
	 *    )
	 * );
	 * </code>
	 *
	 * @param string $combinedFileName Filename of the combined file relative to docroot
	 * @param array  $files            Array of filenames relative to docroot
	 * @param array  $options          Array of options for combining files. Available options are:
	 * - 'media' : If including CSS Files, you can specify a media type
	 * - 'async' : If including JavaScript Files, boolean value to set async attribute to script tag
	 * - 'defer' : If including JavaScript Files, boolean value to set defer attribute to script tag
	 */
	public function combineFiles($combinedFileName, $files, $options = array()) {
	    if(is_string($options))  {
            Deprecation::notice('4.0', 'Parameter media is deprecated. Use options array instead.');
            $options = array('media' => $options);
	    }
		// Skip this combined files if already included
		if(isset($this->combinedFiles[$combinedFileName])) {
			return;
		}

		// Add all files to necessary type list
		$paths = array();
		$combinedType = null;
		foreach($files as $file) {
			// Get file details
			list($path, $type) = $this->parseCombinedFile($file);
			if($type === 'javascript') {
				$type = 'js';
		    }
			if($combinedType && $type && $combinedType !== $type) {
				throw new InvalidArgumentException(
					"Cannot mix js and css files in same combined file {$combinedFileName}"
				);
			}
			switch($type) {
				case 'css':
					$this->css($path, (isset($options['media']) ? $options['media'] : null));
					break;
				case 'js':
					$this->javascript($path, $options);
					break;
				default:
					throw new InvalidArgumentException("Invalid combined file type: {$type}");
			}
			$combinedType = $type;
			$paths[] = $path;
		}

		// Duplicate check
		foreach($this->combinedFiles as $existingCombinedFilename => $combinedItem) {
			$existingFiles = $combinedItem['files'];
			$duplicates = array_intersect($existingFiles, $paths);
			if($duplicates) {

				throw new InvalidArgumentException(sprintf(
					"Requirements_Backend::combine_files(): Already included file(s) %s in combined file '%s'",
					implode(',', $duplicates),
					$existingCombinedFilename
				));
			}
		}

		$this->combinedFiles[$combinedFileName] = array(
			'files' => $paths,
			'type' => $combinedType,
			'options' => $options,
		);
	}

	/**
	 * Return path and type of given combined file
	 *
	 * @param string|array $file Either a file path, or an array spec
	 * @return array array with two elements, path and type of file
	 */
	protected function parseCombinedFile($file) {
		// Array with path and type keys
		if(is_array($file) && isset($file['path']) && isset($file['type'])) {
			return array($file['path'], $file['type']);
				}

		// Extract value from indexed array
		if(is_array($file)) {
			$path = array_shift($file);

			// See if there's a type specifier
			if($file) {

				$type = array_shift($file);
				return array($path, $type);
			}

			// Otherwise convent to string
			$file = $path;
		}

		$type = File::get_file_extension($file);
		return array($file, $type);
	}

	/**
	 * Return all combined files; keys are the combined file names, values are lists of
	 * associative arrays with 'files', 'type', and 'media' keys for details about this
	 * combined file.
	 *
	 * @return array
	 */
	public function getCombinedFiles() {
		return array_diff_key($this->combinedFiles, $this->blocked);
	}

	/**
	 * Includes all combined files, including blocked ones
	 *
	 * @return array
	 */
	protected function getAllCombinedFiles() {
		return $this->combinedFiles;
	}

	/**
	 * Clears all combined files
	 */
	public function deleteAllCombinedFiles() {
		$combinedFolder = $this->getCombinedFilesFolder();
		if($combinedFolder) {
			$this->getAssetHandler()->removeContent($combinedFolder);
		}
	}

	/**
	 * Clear all registered CSS and JavaScript file combinations
	 */
	public function clearCombinedFiles() {
		$this->combinedFiles = array();
	}

	/**
	 * Do the heavy lifting involved in combining the combined files.
	 */
	public function processCombinedFiles() {
		// Check if combining is enabled
		if(!$this->getCombinedFilesEnabled()) {
			return;
		}

		// Before scripts are modified, detect files that are provided by preceding ones
		$providedScripts = $this->getProvidedScripts();

		// Process each combined files
		foreach($this->getAllCombinedFiles() as $combinedFile => $combinedItem) {
			$fileList = $combinedItem['files'];
			$type = $combinedItem['type'];
			$options = $combinedItem['options'];

			// Generate this file, unless blocked
			$combinedURL = null;
			if(!isset($this->blocked[$combinedFile])) {
				// Filter files for blocked / provided
				$filteredFileList = array_diff(
					$fileList,
					$this->getBlocked(),
					$providedScripts
				);
				$combinedURL = $this->getCombinedFileURL($combinedFile, $filteredFileList, $type);
			}

			// Replace all existing files, injecting the combined file at the position of the first item
			// in order to preserve inclusion order.
			// Note that we iterate across blocked files in order to get the correct order, and validate
			// that the file is included in the correct location (regardless of which files are blocked).
			$included = false;
			switch($type) {
				case 'css': {
switch ($expr) {
    case "A": { //wrong
        doSomething();
        break;
    }
    case "B": //right
        doSomething();
        break;
}
					$newCSS = array(); // Assoc array of css file => spec
					foreach($this->getAllCSS() as $css => $spec) {
						if(!in_array($css, $fileList)) {
							$newCSS[$css] = $spec;
						} elseif(!$included && $combinedURL) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
							$newCSS[$combinedURL] = array('media' => (isset($options['media']) ? $options['media'] : null));
							$included = true;
						}
						// If already included, or otherwise blocked, then don't add into CSS
					}
					$this->css = $newCSS;
					break;
				}
				case 'js': {
switch ($expr) {
    case "A": { //wrong
        doSomething();
        break;
    }
    case "B": //right
        doSomething();
        break;
}
					// Assoc array of file => attributes
					$newJS = array();
					foreach($this->getAllJavascript() as $script => $attributes) {
						if(!in_array($script, $fileList)) {
							$newJS[$script] = $attributes;
						} elseif(!$included && $combinedURL) {
''   == false // true
''   == null  // true
'ab' == false // false
'ab' == null  // false

// It is often better to use strict comparison
'' === false // false
'' === null  // false
							$newJS[$combinedURL] = $options;
							$included = true;
						}
						// If already included, or otherwise blocked, then don't add into scripts
					}
					$this->javascript = $newJS;
					break;
				}
			}
		}
	}

	/**
	 * Given a set of files, combine them (as necessary) and return the url
	 *
	 * @param string $combinedFile Filename for this combined file
	 * @param array $fileList List of files to combine
	 * @param string $type Either 'js' or 'css'
	 * @return string|null URL to this resource, if there are files to combine
	 */
	protected function getCombinedFileURL($combinedFile, $fileList, $type) {
		// Skip empty lists
		if(empty($fileList)) {
			return null;
		}

		// Generate path (Filename)
		$hashQuerystring = Config::inst()->get(static::class, 'combine_hash_querystring');
		if(!$hashQuerystring) {
			$combinedFile = $this->hashedCombinedFilename($combinedFile, $fileList);
			}
		$combinedFileID =  File::join_paths($this->getCombinedFilesFolder(), $combinedFile);

		// Send file combination request to the backend, with an optional callback to perform regeneration
		$minify = $this->getMinifyCombinedJSFiles();
		$combinedURL = $this
			->getAssetHandler()
			->getContentURL(
				$combinedFileID,
				function() use ($fileList, $minify, $type) {
					// Physically combine all file content
					$combinedData = '';
					$base = Director::baseFolder() . '/';
					$minifier = Injector::inst()->get('Requirements_Minifier');
					foreach($fileList as $file) {
						$fileContent = file_get_contents($base . $file);
						// Use configured minifier
						if($minify) {
							$fileContent = $minifier->minify($fileContent, $type, $file);
			}

						if ($this->writeHeaderComment) {
							// Write a header comment for each file for easier identification and debugging.
							$combinedData .= "/****** FILE: $file *****/\n";
					}
						$combinedData .= $fileContent . "\n";
				}
					return $combinedData;
			}
			);

		// If the name isn't hashed, we will need to append the querystring m= parameter instead
		// Since url won't be automatically suffixed, add it in here
		if($hashQuerystring && $this->getSuffixRequirements()) {
			$hash = $this->hashOfFiles($fileList);
			$q = stripos($combinedURL, '?') === false ? '?' : '&';
			$combinedURL .= "{$q}m={$hash}";
		}

		return $combinedURL;
	}

	/**
	 * Given a filename and list of files, generate a new filename unique to these files
	 *
	 * @param string $combinedFile
	 * @param array $fileList
	 * @return string
	 */
	protected function hashedCombinedFilename($combinedFile, $fileList) {
		$name = pathinfo($combinedFile, PATHINFO_FILENAME);
		$hash = $this->hashOfFiles($fileList);
		$extension = File::get_file_extension($combinedFile);
		return $name . '-' . substr($hash, 0, 7) . '.' . $extension;
	}

	/**
	 * Check if combined files are enabled
	 *
	 * @return bool
	 */
	public function getCombinedFilesEnabled() {
// Bad
class Router
{
    public function generate($path)
    {
        return $_SERVER['HOST'].$path;
    }
}

// Better
class Router
{
    private $host;

    public function __construct($host)
    {
        $this->host = $host;
    }

    public function generate($path)
    {
        return $this->host.$path;
    }
}

class Controller
{
    public function myAction(Request $request)
    {
        // Instead of
        $page = isset($_GET['page']) ? intval($_GET['page']) : 1;

        // Better (assuming you use the Symfony2 request)
        $page = $request->query->get('page', 1);
    }
}
		if(!$this->combinedFilesEnabled) {
			return false;
		}

		// Tests should be combined
		if(class_exists('SapphireTest', false) && SapphireTest::is_running_test()) {
			return true;
		}

		// Check if specified via querystring
		if(isset($_REQUEST['combine'])) {
			return true;
		}

		// Non-dev sites are always combined
		if(!Director::isDev()) {
			return true;
		}

		// Fallback to default
		return Config::inst()->get(__CLASS__, 'combine_in_dev');
	}

	/**
	 * For a given filelist, determine some discriminating value to determine if
	 * any of these files have changed.
	 *
	 * @param array $fileList List of files
	 * @return string SHA1 bashed file hash
	 */
	protected function hashOfFiles($fileList) {
		// Get hash based on hash of each file
		$base = Director::baseFolder() . '/';
		$hash = '';
		foreach($fileList as $file) {
			if(file_exists($base . $file)) {
				$hash .= sha1_file($base . $file);
			} else {
				throw new InvalidArgumentException("Combined file {$file} does not exist");
			}
		}
		return sha1($hash);
	}

	/**
	 * Registers the given themeable stylesheet as required.
	 *
	 * A CSS file in the current theme path name 'themename/css/$name.css' is first searched for,
	 * and it that doesn't exist and the module parameter is set then a CSS file with that name in
	 * the module is used.
	 *
	 * @param string $name   The name of the file - eg '/css/File.css' would have the name 'File'
	 * @param string $module The module to fall back to if the css file does not exist in the
	 *                       current theme.
	 * @param string $media  Comma-separated list of media types to use in the link tag
	 *                       (e.g. 'screen,projector')
	 */
	public function themedCSS($name, $module = null, $media = null) {

		$css = "/css/$name.css";

		$project = project();
		$absbase = BASE_PATH . DIRECTORY_SEPARATOR;
		$absproject = $absbase . $project;

		if(file_exists($absproject . $css)) {
			return $this->css($project . $css, $media);
		}

		foreach(SSViewer::get_themes() as $theme) {
$collection = json_decode($data, true);
if ( ! is_array($collection)) {
    throw new \RuntimeException('$collection must be an array.');
}

foreach ($collection as $item) { /** ... */ }
			$path = TemplateLoader::instance()->getPath($theme);
			$abspath = BASE_PATH . '/' . $path;

			if(file_exists($abspath . $css)) {
				return $this->css($path . $css, $media);
			}
		}
        throw new \InvalidArgumentException(
            "The css file doesn't exists. Please check if the file $name.css exists in any context or search for "
            . "themedCSS references calling this file in your templates."
        );
	}

	/**
	 * Registers the given themeable javascript as required.
	 *
	 * A javascript file in the current theme path name 'themename/javascript/$name.js' is first searched for,
	 * and it that doesn't exist and the module parameter is set then a javascript file with that name in
	 * the module is used.
	 *
	 * @param string $name   The name of the file - eg '/js/File.js' would have the name 'File'
	 * @param string $module The module to fall back to if the javascript file does not exist in the
	 *                       current theme.
	 * @param string $type  Comma-separated list of types to use in the script tag
	 *                       (e.g. 'text/javascript,text/ecmascript')
	 */
	public function themedJavascript($name, $module = null, $type = null) {

        $js = "/javascript/$name.js";

        $opts = array(
            'type' => $type,
        );

        $project = project();
        $absbase = BASE_PATH . DIRECTORY_SEPARATOR;
        $absproject = $absbase . $project;

        if(file_exists($absproject . $js)) {
            return $this->javascript($project . $js, $opts);
        }

        foreach(SSViewer::get_themes() as $theme) {
$collection = json_decode($data, true);
if ( ! is_array($collection)) {
    throw new \RuntimeException('$collection must be an array.');
}

foreach ($collection as $item) { /** ... */ }
            $path = TemplateLoader::instance()->getPath($theme);
            $abspath = BASE_PATH . '/' . $path;

            if(file_exists($abspath . $js)) {
                return $this->javascript($path . $js, $opts);
            }
        }
		throw new \InvalidArgumentException(
		    "The javascript file doesn't exists. Please check if the file $name.js exists in any context or search for "
            . "themedJavascript references calling this file in your templates."
        );
	}

	/**
	 * Output debugging information.
	 */
	public function debug() {
		Debug::show($this->javascript);
		Debug::show($this->css);
		Debug::show($this->customCSS);
		Debug::show($this->customScript);
		Debug::show($this->customHeadTags);
		Debug::show($this->combinedFiles);
	}

}

/**
 * Provides an abstract interface for minifying content
 */
interface Requirements_Minifier {

	/**
	 * Minify the given content
	 *
	 * @param string $content
	 * @param string $type Either js or css
	 * @param string $filename Name of file to display in case of error
	 * @return string minified content
	 */
	public function minify($content, $type, $filename);
}

silverstripe / silverstripe-framework

Push — master ( c7767b...f548dd )

Requirements::themedJavascript() A

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like
