diff --git a/wire/config.php b/wire/config.php index 16c479c9..e2714647 100644 --- a/wire/config.php +++ b/wire/config.php @@ -226,6 +226,36 @@ $config->usePageClasses = false; */ $config->useLazyLoading = true; +/** + * Default value for $useVersion argument of $config->versionUrls() method + * + * Controls the cache busting behavior of the `$config->versionUrls()` method as used by + * ProcessWire’s admin themes (but may be used independently as well). When no + * `$useVersion` argument is specified to the versionUrls() method, it will use the + * default value specified here. If not specified, null is the default. + * + * - `true` (bool): Get version from filemtime. + * - `false` (bool): Never get file version, just use `$config->version`. + * - `foobar` (string): Specify any string to be the version to use on all URLs needing it. + * - `?foo=bar` (string): Optionally specify your own query string variable=value. + * - `null` (null): Auto-detect: use file version in debug mode or dev branch only, + * otherwise use `$config->version`. + * + * ~~~~~ + * // choose one to start with, copy and place in /site/config.php to enable + * $config->useVersionUrls = null; // default setting + * $config->useVersionUrls = true; // always use filemtime based version URLs + * $config->useVersionUrls = false; // only use core version in URLs + * $config->versionUrls = 'hello-world'; // always use this string as the version + * $config->versionUrls = '?version=123'; // optionally specify query string var and value + * ~~~~~ + * + * @var null|bool|string + * @since 3.0.227 + * + * $config->useVersionUrls = null; + */ + /** * Disable all HTTPS requirements? * @@ -700,7 +730,7 @@ $config->contentTypes = array( 'txt' => 'text/plain', 'json' => 'application/json', 'xml' => 'application/xml', - ); +); /** * File content types @@ -733,7 +763,7 @@ $config->fileContentTypes = array( 'webp' => 'image/webp', 'zip' => '+application/zip', 'mp3' => 'audio/mpeg', - ); +); /** * Named predefined image sizes and options @@ -797,7 +827,7 @@ $config->imageSizerOptions = array( 'hidpiQuality' => 60, // Same as above quality setting, but specific to hidpi images 'defaultGamma' => 2.0, // defaultGamma: 0.5 to 4.0 or -1 to disable gamma correction (default=2.0) 'webpAdd' => false, // set this to true, if the imagesizer engines should create a Webp copy with every (new) image variation - ); +); /** * Options for webp images @@ -815,7 +845,7 @@ $config->webpOptions = array( 'useSrcExt' => false, // Use source file extension in webp filename? (file.jpg.webp rather than file.webp) 'useSrcUrlOnSize' => true, // Fallback to source file URL when webp file is larger than source? 'useSrcUrlOnFail' => true, // Fallback to source file URL when webp file fails for some reason? - ); +); /** * Admin thumbnail image options @@ -846,7 +876,7 @@ $config->adminThumbOptions = array( 'sharpening' => 'soft', // sharpening: none | soft | medium | strong 'quality' => 90, 'suffix' => '', - ); +); /** * File compiler options (as used by FileCompiler class) @@ -875,7 +905,7 @@ $config->fileCompilerOptions = array( 'exclusions' => array(), // exclude filenames or paths that start with any of these 'extensions' => array('php', 'module', 'inc'), // file extensions we compile 'cachePath' => '', // path where compiled files are stored, or blank for $config->paths->cache . 'FileCompiler/' - ); +); /** * Temporary directory for uploads diff --git a/wire/core/Config.php b/wire/core/Config.php index f018e554..b8c67870 100644 --- a/wire/core/Config.php +++ b/wire/core/Config.php @@ -151,6 +151,7 @@ * @property bool $useMarkupRegions Enable support for front-end markup regions? #pw-group-system * @property bool|array $useLazyLoading Delay loading of fields (and templates/fieldgroups) till requested? Can improve performance on systems with lots of fields or templates. #pw-group-system @since 3.0.193 * @property bool $usePageClasses Use custom Page classes in `/site/classes/[TemplateName]Page.php`? #pw-group-system @since 3.0.152 + * @property bool|int|string|null $useVersionUrls Default value for $useVersion argument of $config->versionUrls() method #pw-group-system @since 3.0.227 * @property int $lazyPageChunkSize Chunk size for for $pages->findMany() calls. #pw-group-system * * @property string $userAuthSalt Salt generated at install time to be used as a secondary/non-database salt for the password system. #pw-group-session @@ -957,10 +958,17 @@ class Config extends WireData { /** * Given array of file asset URLs return them with cache-busting version strings * - * URLs that aready have query strings or URLs with scheme (i.e. https://) are ignored. + * URLs that aready have query strings or URLs with scheme (i.e. https://) are ignored, + * except for URLs that already have a core version query string, i.e. `?v=3.0.227` + * may be converted to a different version string when appropriate. + * * URLs that do not resolve to a physical file on the file system, relative URLs, or * URLs that are outside of ProcessWire’s web root, are only eligible to receive a * common/shared version in the URL (like the core version). + * + * To set a different default value for the `$useVersion` argument, you can populate + * the `$config->useVersionUrls` setting in your /site/config.php with the default + * value you want to substitute. * * ~~~~~ * foreach($config->versionUrls($config->styles) as $url) { @@ -980,7 +988,9 @@ class Config extends WireData { * - `true` (bool): Get version from filemtime. * - `false` (bool): Never get file version, just use $config->version. * - `null` (null): Auto-detect: use file version in debug mode or dev branch only, $config->version otherwise. - * - `str` (string): Specify any string to be the version to use on all URLs needing it. + * - `foobar` (string): Specify any string to be the version to use on all URLs needing it. + * `- ?foo=bar` (string): Optionally specify your own query string variable=value. + * - The default value (null) can be overridden by the `$config->useVersionUrls` setting. * @return array Array of URLs updated with version strings where needed * @since 3.0.227 * @@ -990,24 +1000,50 @@ class Config extends WireData { $a = array(); $rootUrl = $this->urls->root; $rootPath = $this->paths->root; - $versionStr = "?v=" . (is_string($useVersion) ? $useVersion : $this->version); + $coreVersionStr = "?v=$this->version"; if($useVersion === null) { - $useVersion = ($this->debug || ProcessWire::versionSuffix === 'dev'); + // if useVersion argument not specified pull from $config->useVersionUrls + $useVersion = $this->useVersionUrls; + if($useVersion === null) { + // if null or still not specified, auto-detect what to use + $useVersion = ($this->debug || ProcessWire::versionSuffix === 'dev'); + } + } + + if(is_string($useVersion)) { + // custom version string specified + if(!ctype_alnum(str_replace(array('.', '-', '_', '?', '='), '', $useVersion))) { + // if it fails sanitization then fallback to core version + $useVersion = false; + $versionStr = $coreVersionStr; + } else { + // use custom version str + $versionStr = $useVersion; + if(strpos($versionStr, '?') === false) $versionStr = "?v=$versionStr"; + } + } else { + // use core version when appropriate + $versionStr = $coreVersionStr; } foreach($urls as $url) { - if(strpos($url, $versionStr)) { + if(strpos($url, $coreVersionStr)) { + // url already has core version present in it if($useVersion === false) { + // use as-is since this is already what's requested $a[] = $url; continue; } - list($u, $r) = explode($versionStr, $url, 2); + // remove existing core-version query string + list($u, $r) = explode($coreVersionStr, $url, 2); if(!strlen($r)) $url = $u; } if(strpos($url, '?') !== false || strpos($url, '//') !== false) { + // leave URL with query string or scheme:// alone $a[] = $url; } else if($useVersion === true && strpos($url, $rootUrl) === 0) { + // use filemtime based version $f = $rootPath . substr($url, strlen($rootUrl)); if(is_readable($f)) { $a[] = "$url?" . base_convert((int) filemtime($f), 10, 36); @@ -1015,6 +1051,7 @@ class Config extends WireData { $a[] = $url . $versionStr; } } else { + // use standard or specified versino string $a[] = $url . $versionStr; } }