class LessCompiler extends RevisionCompiler
Traits
Constants
| EMPTY_REVISION |
|
Properties
| protected callable[] | $sourcesCallbacks | from HasSources |
|
|
| protected array<string, string> | $pendingSidecars | Sidecar files (e.g. JsCompiler's `.map`) queued by renderOutput() during the current commit, written only if the primary file is — so an unchanged bundle rewrites nothing at all. | from RevisionCompiler |
|
| protected string | $cacheDir |
|
||
| protected array | $importDirs |
|
||
| protected array | $customFunctions |
|
||
| protected Collection|null | $lessImportOverrides |
|
||
| protected Collection|null | $fileSourceOverrides |
|
||
| protected string|null | $fontsDir |
|
Methods
No description
Recompile this asset and record its revision. Files are only written when the compiled output actually differs from what the revision manifest says is on disk (or the file has gone missing) — so routine rebuilds of unchanged assets are complete no-ops with zero writes.
Whether the committed file is really the output its revision claims.
Produce the exact bytes to write to the primary asset file, or null when there is nothing to write (empty sources). This is what the revision is hashed from, so it must be identical to what gets committed — subclasses that transform or add to the output (e.g. JsCompiler's sourcemap handling) override this and queue any sidecar files (like the `.map`) on {$pendingSidecars} rather than writing them, so sidecars are only written when the bundle itself is.
The directory holding the webfonts that get published to `assets/fonts`.
Resolve an `@import` against the permitted directories, and refuse it otherwise.
Empty `$_SERVER['DOCUMENT_ROOT']` for the length of a compile, and return the value to restore afterwards.
Point font URLs at the published `assets/fonts` directory, and stamp each with a revision derived from the font file itself.
A short hash of a webfont's contents, or null when it can't be read — fonts are published separately, so a compile must never fail just because the directory isn't there yet.
Details
in HasSources
at
line 25
void
addSources(callable $callback)
in HasSources
at
line 33
protected array
getSources()
in HasSources
at
line 44
abstract protected array
allowedSourceTypes()
in RevisionCompiler
at
line 28
__construct( Cloud $assetsDir, string $filename, SettingsRepositoryInterface $settings, VersionerInterface $versioner)
in RevisionCompiler
at
line 36
string|null
getFilename()
in RevisionCompiler
at
line 41
void
setFilename(string $filename)
in RevisionCompiler
at
line 57
void
commit(bool $force = false)
Recompile this asset and record its revision. Files are only written when the compiled output actually differs from what the revision manifest says is on disk (or the file has gone missing) — so routine rebuilds of unchanged assets are complete no-ops with zero writes.
in RevisionCompiler
at
line 111
protected void
writePendingSidecars()
in RevisionCompiler
at
line 118
protected string
outputFilename(string $revision)
in RevisionCompiler
at
line 123
protected string
hashOutput(string $content)
in RevisionCompiler
at
line 134
protected bool
committedFileMatches(string $output)
Whether the committed file is really the output its revision claims.
Read back and compared rather than assumed: a recorded revision is only evidence about the file if the write that recorded it also landed.
in RevisionCompiler
at
line 158
protected string|null
renderOutput(array $sources)
Produce the exact bytes to write to the primary asset file, or null when there is nothing to write (empty sources). This is what the revision is hashed from, so it must be identical to what gets committed — subclasses that transform or add to the output (e.g. JsCompiler's sourcemap handling) override this and queue any sidecar files (like the `.map`) on {$pendingSidecars} rather than writing them, so sidecars are only written when the bundle itself is.
in RevisionCompiler
at
line 165
string|null
getUrl()
at
line 163
protected string
compile(array $sources)
in RevisionCompiler
at
line 204
protected string
format(string $string)
in RevisionCompiler
at
line 209
void
flush()
in RevisionCompiler
at
line 218
protected void
delete(string $file)
at
line 30
string
getCacheDir()
at
line 39
void
setFontsDir(string|null $fontsDir)
The directory holding the webfonts that get published to `assets/fonts`.
Used to revision the font URLs emitted into the compiled CSS.
at
line 44
void
setCacheDir(string $cacheDir)
at
line 49
array
getImportDirs()
at
line 54
void
setImportDirs(array $importDirs)
at
line 59
void
setLessImportOverrides(array $lessImportOverrides)
at
line 64
void
setFileSourceOverrides(array $fileSourceOverrides)
at
line 69
void
setCustomFunctions(array $customFunctions)
at
line 108
protected array|null
containImports(string $path)
Resolve an `@import` against the permitted directories, and refuse it otherwise.
Raw LESS can read any file the process can reach — `@import (inline)` pastes it in verbatim, and `data-uri()` encodes it into the stylesheet — and custom LESS is written by an administrator but compiled into the *public* stylesheet. That has to be contained here rather than by rejecting spellings in the setting: less.php's import directive is matched as `@import?`, so `@impor` parses identically, and any blocklist only ever chases the parser's grammar. Registered as the sole entry in less.php's `import_dirs`. A closure there is asked to resolve the path and may decline by returning null — but for a local path declining lets less.php fall back to reading the raw path, so an import we will not resolve has to throw instead. `import_dirs` is only less.php's last resort, though. It first tries the importing file's own directory for a relative path, and the entry path and `$_SERVER['DOCUMENT_ROOT']` for an absolute one. The first that holds a file wins, and the path is joined on unresolved, so `/../..` climbs out of either. Custom LESS has no directory of its own, as it is a string source, and compile() empties the other two, so this is the only resolver a path written in custom LESS can reach. That does not extend to a path written in a trusted file. A `data-uri()`, an image function or an `@import "@{var}"` there resolves against that file's own directory first, and custom LESS can redefine a variable it uses. No LESS that ships with Flarum does this.
at
line 278
protected string|null
clearDocumentRoot()
Empty `$_SERVER['DOCUMENT_ROOT']` for the length of a compile, and return the value to restore afterwards.
less.php tries an absolute import against the document root before it consults `import_dirs`, and has no option to turn that off, so a path that climbs out of it would never reach containImports(). less.php skips an empty value. It is emptied rather than unset, because less.php reads the key without checking that it exists.
at
line 304
protected string
finalize(string $parsedCss)
Point font URLs at the published `assets/fonts` directory, and stamp each with a revision derived from the font file itself.
The stylesheet is already cache-busted (`forum.css?v=<rev>`), but the font URLs inside it were not. On a FontAwesome major upgrade every browser therefore picked up the new CSS immediately while continuing to serve the *previous* font file from cache — same filename, same URL, long max-age. The new CSS asks for codepoints the old font doesn't contain, so every icon rendered as a placeholder box until that cache entry happened to expire. Revisioning the URL means a changed font is always a new URL, for browser and CDN caches alike. Because the asset revision is a hash of this compiled output, a font change also moves the stylesheet's own revision — so connected clients get the usual "reload for the new version" prompt without any extra wiring.
at
line 325
protected string|null
fontRevision(string $file)
at
line 340
static string|null
fontRevisionIn(string|null $fontsDir, string $file)
A short hash of a webfont's contents, or null when it can't be read — fonts are published separately, so a compile must never fail just because the directory isn't there yet.
This is the one place the revision is worked out: anything else that links to a bundled font (the font preloads) goes through {[\Flarum\Frontend\Assets::fontRevision()},](../../../Flarum/Frontend/Assets.html) which calls this with the same directory, so its URL is the one the stylesheet requests.