Compiling Workspaces

Compiling workspaces is similar to compiling individual documents. The main difference is that the workspace compiler will save the results to a directory on the filesystem.

The output directory should already exist, and the PHP process compiling the workspace should have read, write, modify, and delete privileges to the directory.

The following example demonstrates how we might compile a workspace:

 1<?php
 2 
 3use Stillat\BladeParser\Document\DocumentCompilerOptions;
 4use Stillat\BladeParser\Workspaces\TempPathFormatter;
 5use Stillat\BladeParser\Workspaces\Workspace;
 6 
 7$workspace = new Workspace();
 8$workspace->addDirectory(resource_path('views'));
 9 
10 
11// Set any custom compiler options, if desired.
12$workspace->withCompilerOptions(new DocumentCompilerOptions(
13    failOnParserErrors: true,
14));
15 
16// Set the path name formatter.
17$workspace->withPathFormatter(new TempPathFormatter);
18 
19// Compile all templates in the workspace.
20$workspace->compile(storage_path('tmp/output'));

When compiling workspaces, we must always specify a path formatter. A path formatter implements the Stillat\BladeParser\Contracts\PathFormatter interface:

 1<?php
 2 
 3namespace Stillat\BladeParser\Contracts;
 4 
 5use Stillat\BladeParser\Document\Document;
 6 
 7interface PathFormatter
 8{
 9    public function getPath(Document $document): string;
10}

Instances of this interface are used internally to determine the compiled file name emitted by the workspace. For example, the following is the implementation of the provided TempPathFormatter:

 1<?php
 2 
 3namespace Stillat\BladeParser\Workspaces;
 4 
 5use Stillat\BladeParser\Contracts\PathFormatter;
 6use Stillat\BladeParser\Document\Document;
 7 
 8class TempPathFormatter implements PathFormatter
 9{
10    public function getPath(Document $document): string
11    {
12        return 'temp_'.sha1($document->getFilePath()).'.php';
13    }
14}

#Available Methods

#compile

Compiles all discovered Blade templates within the workspace.

Argument	Description
$outputDirectory	Where to store compiled files.

1<?php
2 
3public function compile(
4    string $outputDirectory
5): void;

#withCompilerOptions

Sets the workspace compiler options.

Argument	Description
$options	The compiler options.

1<?php
2 
3use Stillat\BladeParser\Document\DocumentCompilerOptions;
4use Stillat\BladeParser\Workspaces\Workspace;
5 
6public function withCompilerOptions(
7    DocumentCompilerOptions $options
8): Workspace;

#withPathFormatter

Sets the PathFormatter implementation used by the workspace.

PathFormatter implementations are used to determine what the final output file paths look like.

Argument	Description
$formatter	The path formatter.

1<?php
2 
3use Stillat\BladeParser\Contracts\PathFormatter;
4use Stillat\BladeParser\Workspaces\Workspace;
5 
6public function withPathFormatter(
7    PathFormatter $formatter
8): Workspace;

#removeCompiledFiles

Attempts to remove all compiled files produced by the workspace.

1<?php
2 
3use Stillat\BladeParser\Workspaces\Workspace;
4 
5public function removeCompiledFiles(): Workspace;

#withDefaultCompilerOptions

Removes any custom compiler options and restores the workspace to defaults.

1<?php
2 
3use Stillat\BladeParser\Workspaces\Workspace;
4 
5public function withDefaultCompilerOptions(): Workspace;

#getCompilerOptions

Returns the currently configured compiler options.

If no custom compiler options were configured, a set of default options will be created.

1<?php
2 
3use Stillat\BladeParser\Document\DocumentCompilerOptions;
4 
5public function getCompilerOptions(): DocumentCompilerOptions;

#getSourceLine

Retrieves the original Blade template line number for the given compiled PHP line.

Argument	Description
$docPath	The compiled path.
$phpLine	The target PHP line.

1<?php
2 
3public function getSourceLine(string $docPath,
4                              int $phpLine): int;

#getCompiledDocument

Retrieves a Document instance using the provided compiled path name.

Argument	Description
$path	The compiled path.

1<?php
2 
3use Stillat\BladeParser\Document\Document;
4 
5public function getCompiledDocument(
6    string $path
7): Document;