Phiki Documentation

Phiki is a pure PHP package for syntax highlighting code using TextMate grammar files and Visual Studio Code themes. It is designed as a high-performance, zero-dependency alternative to Shiki and Highlight.php.

Key Advantages:

• High Quality: Uses the same TextMate/VS Code logic as modern editors.
• Pure PHP: Unlike Shiki, it does not require spawning a Node.js process, making it suitable for live-rendered PHP applications.
• Zero Dependencies: Easy to integrate into any PHP project without managing third-party requirements.

You can highlight or focus specific lines by adding braces to the Markdown code block info string. The format is {highlight_lines}{focus_lines}.

• Highlighting: Use {line_numbers} to highlight specific lines.
• Focusing: Use {}{line_numbers} to focus specific lines. When lines are focused, Phiki adds a focus class to the <pre> element.

// Highlight lines 2 and 4-8
```php {2,4-8}

// Focus lines 2 and 4-8 (no highlights)

Transformers allow you to modify data at various stages of the syntax highlighting process. They can intercept and alter the input code, individual tokens, the HTML AST (Abstract Syntax Tree), or the final HTML output.

Transformers are applied sequentially: the return value from one transformer is passed as the input to the next.

Important considerations:

• Order matters: Transformers are applied in the order they are added.
• AST Integrity: When modifying the HTML AST (using hooks like root, pre, code, etc.), be cautious when adding or removing elements, as this can break the structure expected by subsequent transformers in the pipeline.

You can target specific lines to add custom CSS classes (e.g., for highlighting or focusing) using LineDecoration::forLine(index)->class('your-class'). Note that line indices are zero-based.

use Phiki\Transformers\Decorations\LineDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->decoration(
        LineDecoration::forLine(0)->class('focus'),
    );

To add custom CSS classes to the gutter element (the area containing line numbers), ensure you have enabled the gutter with withGutter() and then use GutterDecoration::make()->class('your-class') via the PendingHtmlOutput::decoration() method.

use Phiki\Transformers\Decorations\GutterDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->withGutter()
    ->decoration(
        GutterDecoration::make()->class('gutter-class'),
    );

You can add custom CSS classes to the <pre> element that wraps the entire code block by using PreDecoration::make()->class('your-class') within the PendingHtmlOutput::decoration() method.

use Phiki\Transformers\Decorations\PreDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->decoration(
        PreDecoration::make()->class('pre-class'),
    );

To add custom CSS classes to the <code> element that wraps the code content, use CodeDecoration::make()->class('your-class') via the PendingHtmlOutput::decoration() method.

use Phiki\Transformers\Decorations\CodeDecoration;

$output = (new Phiki)
    ->codeToHtml('<?php echo ...', Grammar::Php, Theme::GithubLight)
    ->decoration(
        CodeDecoration::make()->class('code-class'),
    );

To bundle custom grammars and themes for reuse, create a PHP class that implements the Phiki\Contracts\ExtensionInterface.

Inside the register(Environment $environment): void method, use the $environment object to register your assets. You can use the grammar() method to register a new language grammar and the theme() method to register a new theme, both pointing to the file paths of your JSON definitions.

use Phiki\Contracts\ExtensionInterface;
use Phiki\Environment;

class MyExtension implements ExtensionInterface
{
    public function register(Environment $environment): void
    {
        $environment
            ->grammar('my-language', __DIR__ . '/grammars/my-language.json')
            ->theme('my-theme', __DIR__ . '/themes/my-theme.json');
    }
}