Download the PHP package torchlight/engine without Composer

On this page you can find all versions of the php package torchlight/engine. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package engine

Torchlight Engine brings Torchlight's code annotation syntax to PHP, built on top of the excellent Phiki syntax highlighting package. No node or API required.

Torchlight enables you to add annotations to your code, drawing your reader's attention to specific parts, highlighting lines, visualizing diffs, and much more. Combined with the syntax highlighting provided by Phiki, Torchlight is a perfect fit for technical blogs, documentation, and so much more.

Torchlight annotations are written as comments in the language of your code sample, eliminating red squigglies and errors within your editor or IDE.

As an example, here is how we could focus our reader's attention on lines 6 and 7:

When rendered, our readers would be presented with something like the following:

How simple is that? We're pretty proud of it and know you'll love it, too.

Installation

You may install Torchlight Engine via Composer:

Torchlight Engine requires at least PHP 8.2, but PHP 8.4+ is recommended.

Getting Started

Torchlight Engine provides a league/commonmark extension, making it simple to start using Torchlight in your markdown content.

You may register the extension with any CommonMark Environment object like so:

`php

`

Modifying the CommonMark Extension

The CommonMark extension provides a few different ways to modify its behavior.

Specifying the Extension's Default Language

To change the extension's default language that should be used when author's omit the language on a code block, we can call the setDefaultGrammar on the underlying renderer:

This code block would now use PHP by default. `

Caching Highlighted Code

A custom cache may be used to cache highlighted code blocks. Integrators may implement the Torchlight\Engine\CommonMark\BlockCache interface:

The cache implementation may be set on the extension by calling the setBlockCache on the underling renderer:

Laravel

[!NOTE] This section highlights using the provided CommonMark extension with Laravel. Updated versions of the Laravel client are planned for the future.

You may use the provided CommonMark extension with Laravel's Str::markdown() or str()->markdown() methods by adding the extension to your method call:

Statamic

To integrate Torchlight Engine with Statamic, you may add the CommonMark extension like so:

Rendering Code Manually

You may also use the engine "manually". The following code example provides the minimum amount of code to use the Engine to render code:

Notes on User Provided Content

Phiki and Torchlight Engine, while incredibly powerful, are still early projects, and it is possible to encounter infinite loops with some grammars and input. As always, you should exercise caution when rendering any user-provided content.

If you encounter one of these scenarios please create an issue so it can be looked into.

Frequently Asked Questions

Is the Torchlight API going away now?

The Torchlight API will remain as-is for now. Any changes to the hosted service will be communicated ahead of time.

How much does Torchlight Engine cost?

Torchlight Engine is free.

Does Torchlight Engine require an API key or network access?

No. Torchlight Engine is a PHP-based, offline renderer built on top of Phiki.

What about the Laravel and CommonMark packages?

There are plans to upgrade both of these packages to support Torchlight Engine. More information on this topic will come in the future.

Will this package replace the existing CommonMark package?

No, there are no immediate plans to deprecate the existing CommonMark package as it provides additional features not currently available in the extension shipped with this package (notably integration with the torchlight.php configuration file and replacers). However, if you need a CommonMark extension that has no Laravel dependency, the extension provided by this package is what you are looking for.

Some themes are missing compared to the API version. How come?

Some themes available via. Torchlight API are not available with Torchlight Engine; this is largely due to them not being distributed any longer, or licensing information was not readily available. More information on adding custom themes to Torchlight will be coming in the future.

Can I add custom themes to Torchlight Engine?

Technically yes, but it is a slightly involved process to account for the Torchlight colors. More information on adding custom themes will be coming in the future once the process is a bit simpler.

Are the custom grammars from the API version supported?

Yes, even the files grammar!

Some of my highlighting looks different now. How come?

There may be differences in highlighting due to the underlying tokenizer and theme system. Please report any egregious issues and we will work to help get them resolved.

Are there breaking changes?

Great care has been taken to avoid breaking changes, and adhere to the existing HTML structure as closely as possible. However, there are some scenarios where behavior has been changed.

Please refer to the Differences Between Torchlight Engine and Torchlight API section for more information.

Differences Between Torchlight Engine and Torchlight API

There are a small number of differences when comparing Torchlight Engine and the Torchlight API versions:

CSS and Theming

Torchlight handles the highlighting of all of your code for you, but there are a few styles that you will likely need to add to your CSS to make it just right.

This is the CSS we prefer, which sets up some line padding, margin off of the line numbers, and overflow scrolling. Your CSS is totally up to you though!

Standard CSS

This is the vanilla CSS version, see below for the TailwindCSS version.

Tailwind

Here is the Tailwind version:

Dark Mode

Torchlight Engine utilizes Phiki for syntax highlighting, and recommends using it's multi-theme support for dark mode.

When instantiating an instance of the CommonMark extension, you may supply multiple themes like so:

The first entry, light in this case, will be used as the default theme. Other themes in the array may be conditionally rendered with CSS.

Query-based dark mode:

Class-based dark mode:

You can learn more about rendering multiple themes with Phiki here. The only change when rendering multiple themes with Torchlight Engine is the placement of the background-color property, to prevent conflicts with some annotations, such as diff add and remove.

Available Themes

The following themes are available:

Annotations

One of the things that makes Torchlight such a joy to author with is that you can control how your code is rendered via comments in the code you're writing.

If you want to highlight a specific line, you can add a code comment with the magic syntax [tl! highglight] and that line will be highlighted.

Gone are the days of inscrutable line number definitions at the top of your file, only to have them become outdated the moment you add or remove a line.

Most other tools use a series of line numbers up front to denote highlight or focus lines: `

If you don't have the syntax memorized, it's hard to tell what those numbers mean. And of course when you add a line or remove a line, everything changes and you have to recalculate!

With Torchlight, you control your display with inline annotations in comments.

All inline annotations are wrapped within square brackets and start with tl!, leaving you with the following format: [tl! ... ... ...].

For example, if you are using Torchlight to render the following block of PHP:

and you wanted to draw attention to lines 6 & 7, you could focus those lines by using the focus annotation:

Resulting in the following:

Notice that Torchlight is smart enough to not only strip the annotation from line 6, but the annotation and comment syntax from line 7, leaving your code pristine.

If the entirety of the comment is Torchlight annotations, the comment will be removed from the rendered code. If there is additional content in the comment, that content will remain and the annotation will be stripped out.

Because annotations are actual code comments, it doesn't mess up your authoring experience by throwing invalid characters in your code.

Inline annotations support different keywords, modifiers, and range definitions

Remember that the comment syntax varies based on what language you are highlighting, so be sure to use actual comments.

For example if you're highlighting HTML, you would use HTML comment tags <!-- -->. See the example on line 5.

Annotations can be used with plain text and JSON, despite them having no "official" comment support as a language.

Plain Text Annotations

For plain text, everything is treated "as if" it's a comment, so you can just put the annotation on any line.

JSON Annotations

JSON uses the double slash // comment style, even though it's not official spec. Forgive us.

Ranges

Sometimes you want to apply an annotation to a whole set of lines, without having to add dozens of comments.

We have provided several different methods to achieve this, so you may pick the one that best fits your use case.

Annotation Range Cheat Sheet

Single Lines

By default, every annotation applies only to the line that it lives on.

For example, this will only highlight the line it is on, line number 2.

N-Many Lines

To highlight the current line, and the next N lines, you may use the :N modifier.

In this example, we will highlight the current line (2) and the next two lines (3 & 4).

This also works with negative numbers :-N

Offset and Length

If you have a bit of code that is hard to reach with a comment, perhaps a heredoc, you can use the focus:M,N syntax where M is the number of lines above or below the current line, and N is the number of lines to highlight.

Here we're going to start 6 lines down, and highlight 3 lines total.

You can also start from the bottom by using a negative offset. We'll start 7 lines up and highlight 3 lines again.

Applying an Annotation to All Lines

You may use the all modifier to apply an annotation to all lines. For example, the following would apply the autolinks annotation to every line:

Start and End

Sometimes you want to define a start and end line, and annotate everything in the middle.

You may do this with the :start and :end modifiers.

Supported Annotations

All of them! Ranges are supported for all of the Torchlight annotation keywords:

Custom classes and IDs are supported as well.

Torchlight also plays nicely with prefixed Tailwind classes:

Remember that an HTML ID must be unique on the page, so while it's unlikely that you'd want to apply an ID to a range of lines, you may want to apply it to a line you cannot reach.

For example, to reach four lines down and add an ID of popover-trigger, you could do the following:

Highlighting Lines

The highlight annotation will pull the line highlight background color from your chosen theme, and apply it to the background of the line, drawing focus to that specific line:

It also applies a line-highlight class to the line.

If you have any lines highlighted, Torchlight will add a has-highlight-lines class to your code tag.

Every theme is different in the way that it chooses to represent highlighted lines, so be sure to try a few out.

Alternative Highlight Class

If you don't like the highlight color that your theme uses, you can apply a custom class instead, e.g. .highlight or .foobar:

Highlight Shorthand

If you find typing highlight prohibitively slow (who has the time?), you can use ~~ as a shorthand.

Focusing

The focus annotation adds a line-focus class to the line, and a has-focus-lines class to your code tag.

Used in conjunction with the CSS below, every line that you've applied [tl! focus] to will be sharp and clear, and the rest will be blurry and dim. If a user hovers over the code block, everything will come into focus.

Focusing Shorthand

As an alternative to focus, you can use **.

Focusing CSS

Here is the CSS required to achieve the focus effect:

Collapsing

Sometimes in your documentation or a blog post, you want to focus the reader on a specific block of code, but allow them to see the rest of the code if they need to.

One way you can achieve that is by using the focus annotation to blur the irrelevant code, but you can also use Torchlight to collapse blocks of code using native HTML, no JavaScript required.

In this example, we're going to collapse the heading_permalink options, as they might distract from the point of the example.

We can do this by using the collapse annotation:

Collapsed section closed:

Collapsed section open:

These lines will now be wrapped in a summary / detail pair of tags, that allows the user to natively toggle the open and closed start of the block. Torchlight will also add a has-summaries class to your code tag anytime you define a summary range.

You can use the start end method of defining a range, or any of the other range modifiers.

Here's an example using the N-many modifier to collapse the 5 lines following the annotation:

Customizing the Summary Text

By default, Torchlight will add a subtle ... in place of the collapsed text, but you can customize that by passing in the summaryCollapsedIndicator options:

Collapsing Required CSS

You will need to add the following CSS to your page to accomplish the hiding:

Default to Open

By default, when you define a collapse range it will be collapsed. If you want to define the range but default it to open, you can add the open keyword:

Removing Summary Carets

You can disable summary carets by setting the showSummaryCarets block option:

Setting this to false will disable the collapse gutter entirely:

Diffs

To demonstrate the addition and removal of lines, you can use the add and remove keywords.

Torchlight will look through your theme to find the appropriate foreground and background colors to apply to the specific lines.

It will also apply line-add and line-remove classes to the individual lines. To the code element it will apply the has-diff-lines class, and potentially has-add-lines and has-remove-lines.

Diff Shorthand

You can use ++ and -- as shorthand for add and remove.

Removing Diff Indicators

Here is an example of a diff, with no indicators.

Notice that the colors of the lines just change to the standard colors you expect to see.

If you'd like to show the +/- indicators, you can do so by turning them on at the block level, or globally in your client's configuration.

For these examples we'll do it at the block level so we can see how it works.

Let's change the behavior by sending diffIndicators: true to the API.

Take a look where the line numbers are and notice the indicators:

[!NOTE] If you'd like to reindex the line numbers after a diff, you can do that.

Standalone Diff Indicators

By default, we swap them in place of the line numbers, but you can also disable that behavior by using the extremely descriptive, verbose option diffIndicatorsInPlaceOfLineNumbers.

Now the line numbers remain, and the indicators get their own column.

Each standalone indicator has the diff-indicator class applied, along with one of the following:

Diff Indicators Without Line Numbers

In the scenario where you:

Your indicators will still show up in the line-number classes, not the standalone classes mentioned above.

The reason we have chosen this approach is so that you don't have to add the diff-indicator styles ever when you choose to put your indicators in the line number column.

Diff Ranges

The diff annotations support the entire set of range modifiers to help you quickly annotate a whole set of lines.

Check out the range docs for more details, but here is a quick cheat sheet.

Preserving Syntax Colors

By default, the diff add and remove annotations will apply the corresponding text color, replacing the original token colors:

Notice how the text color has changed to red and green? We can disable this by setting the diffPreserveSyntaxColors block option:

Classes and IDs

You can add your own custom classes by preceding them with a ., or add an ID with a #.

You can space out your classes like we did above, or just run them all together: .font-bold.italic.animate-pulse#pulse

Torchlight also supports Tailwind + the Tailwind JIT syntax, so you can do pretty much anything you can think of:

Using Range Modifiers

You can also apply any range modifiers to custom classes.

Check out the range docs for more details, but here is a quick cheat sheet.

Remember that an HTML ID must be unique on the page, so while it's unlikely that you'd want to apply an ID to a range of lines, you may want to apply it to a line you cannot reach.

For example, to reach four lines down and add an ID of popover-trigger, you could do the following:

Character Ranges

You may also apply classes and IDs to character ranges on the current line by prefixing your range with the c character. Instead of supplying a range of line numbers, we supply the character range.

For example, the range .inner-highlight:c26,34 instructs Torchlight to wrap the tokens from characters 26 through 34 with the inner-highlight class:

[!NOTE] You will need to add the desired CSS to style your character range classes.

Auto-linking URLs

Sometimes your code contains URLs to other supporting documentation. It's a nice experience for the reader if those URLs were actually links instead of having to copy-paste them.

It's a little thing, but Torchlight sweats the little things so you don't have to.

Using the autolink annotation, Torchlight will look for URLs and turn them into links for you.

The resulting link will look like this (color will change depending on your theme):

Torchlight adds a torchlight-link class, and rel + target attributes.

The rel=noopener attribute ensures that no a malicious website doesn't have access to the window.opener property. Although this is less of a concern now with modern browsers, we still want you to be covered.

Read more about rel=noopener at mathiasbynens.github.io/rel-noopener.

Link Requirements

Your URL must start with one of the following in order to match:

Link Ranges

The auto-link annotation supports the entire set of range modifiers to help you quickly annotate a whole set of lines.

Check out the range docs for more details, but here is a quick cheat sheet.

Reindexing Line Numbers

Now we're really getting into the weeds, but that's exactly what Torchlight is here for.

Sometimes it really matters what the line number is that goes along with your code sample. In the case where you can't get it right, you might be tempted to turn them off altogether.

Torchlight offers a few ways to reindex the lines, using the reindex annotation.

To reindex a line, you will add the reindex annotation. This annotation is a little bit different than the others, because it accepts an argument in parenthesis.

Here are a few examples:

Manually Setting a New Number

To just outright set a new number, use the reindex(N) style:

Torchlight will continue with the next number after the one you set.

No Line Number at All

If you want a line to have no line number, use the reindex(null) annotation:

If you don't immediately reindex, Torchlight just treats that line as if it doesn't exist for numbering purposes.

Relative Line Number Changes

Often times it's easiest to think in terms of "increment" or "decrement" instead of thinking in absolutes. Especially as time goes on and your samples may change, it's nice to have the relative numbers always work.

This can be a really nice touch when showing diffs, to keep the numbering legit.

To change the numbers relatively, use the reindex(+N) and reindex(-N) styles.

Of course, it doesn't have to just be 1, it could be any number.

Reindexing with Range Modifiers

The reindex annotation does work with the annotation range modifiers, so you can do some pretty wacky stuff.

If you wanted to reach down several lines and apply a reindex, you totally could!

Here we are going to reach down 6 lines, and apply a +5 reindex to 1 line only.

Or if you wanted to null out the second stanza, you could do that also.

Why you would ever want to do this, I have no idea. But if you want to, you can!

Vim-style Relative Line Numbers

[!IMPORTANT]
The vim.relative and vim.preserve annotations were not designed to work in conjunction with other reindex annotations. Because of this, their use in combination with other reindex annotations is considered undefined behavior.

You may reindex your line numbers similar to Vim's relative line numbers. When you do this, the line numbers will count how far away they are from the annotation:

The annotation's line will be reindex to 0, since that is the distance away from the annotation. If you'd like to preserve the current line number, you may use the vim.preserve annotation instead:

Reindex Differences Between Torchlight API

Torchlight Engine makes some breaking changes when compared to the behavior of the Torchlight API. This was done to make the behavior of reindexing with annotation ranges more predictable and consistent with the other annotations; there should be little to no impact on your code examples unless you are doing some crazy things.

Be sure to double check any reindex examples if you are migrating from the Torchlight API!

Highlighting Files and Directory Structures

Torchlight provides a custom files language that can be used to highlight files and directory structures:

files // torchlight! { "lineNumbers": false, "fileStyle": "ascii" } resources/ name with space/

Full line comment

blueprints/ # Partial comment
    collections/
        blog/
            post.yaml       # Old name [tl! --]
            basic_post.yaml # New name [tl! ++]
            art_directed_post.yaml
    taxonomies/
        tags/
            tag.yaml
    globals/
        global.yaml
        company.yaml
    assets/
        main.yaml
    forms/
        contact.yaml
    user.yaml

`

The files language supports two modes or styles:

Options

Each of these is covered in detail on its own page, but here is an overview of each option and what it does.

Setting Default Options Globally

When using Torchlight Engine without any clients, or helper packages, we need to tell it how to resolve any default global options. This is done by specifying a callback function that returns the default options:

If you have an array of options, you may also use the static fromArray helper method:

As an example, if you are working in a Laravel project that already has a torchlight.php configuration file, you can continue using those options like so (this will become unnecessary once the Laravel client has been updated):

Setting Default Themes Globally

Like with global options, we need to specify a callback letting Torchlight Engine's CommonMark extension know which theme to use. This only applies if you do not specify a theme when instantiating the extension instance.

For example, we can specify default themes that will be used if the extension is not configured when instantiated:

As another example, we could use the torchlight.theme configuration value within an existing Laravel application like so:

Setting Options Per Block

Some blocks you'll want to set options individually. Any options you set on the block level will override that same option on the global level.

To set block level options, the first line of your block must be a comment, in the language of the block.

The comment must begin with torchlight! and be followed valid JSON.

Here is an example turning line numbers off for a single block:

Any option that you can set at the global level, you can set at the block level.

Line Numbers

Torchlight add line numbers by default, but you can disable them globally or on the block level by changing the lineNumbers option to false.

Here's an example of the block level change:

Changing the Starting Line Number

To change the starting number of a block, you may use the lineNumbersStart option:

Note: we also have a reindex annotation to control the line number line by line.

Changing Line Number Styles

By default, Torchlight applies a reasonable set of CSS style to your line numbers:

If you want to control that, you can pass in a lineNumbersStyle option.

There are a couple of things to note when using this option.

The first is that you will likely want to include the -webkit-user-select: none; user-select: none; styles, so that when your visitors copy your code they don't get the line numbers. Because that's the worst.

Copy the code above and notice that the line numbers will be selected, versus the block right above it (Torchlight default).

The other thing to note is that you'll need to be thoughtful when adding color declarations.

Torchlight uses the theme's color scheme to handle insert and remove lines, so it's probably best to leave the color declaration off altogether.

Adding Line Number Right Padding

You may add right padding to your line numbers using the lineNumberAndDiffIndicatorRightPadding block option:

If you are using standalone diff indicators, right padding will be applied to the right of those:

Right padding being applied to the right of diff indicators is a small change in behavior compared to Torchlight API.

Summary Indicator

When using the collapse annotation, Torchlight will add an ellipses ... to indicate where the collapsed code is.

This is the default behavior:

If you'd like to change the ... to something else, you can do so by changing the summaryCollapsedIndicator option:

Adding Extra Classes to the Torchlight Code Element

You may add extra classes to the code element by using the classes block option:

When Torchlight renders the code block it will add those classes to the generated code block:

The Copyable Option

You can use the copyable block option to instruct Torchlight to add a hidden HTML element with the torchlight-copy-target class to the generated output. This hidden element will contain the raw text that may be used to implement a copy & paste feature:

Disabling Torchlight Annotations

If for whatever reason you want to disable all of the Torchlight annotations, you may do so with the torchlightAnnotations option.

This option was added specifically for these docs. We don't expect you'll need it unless you're trying to show how Torchlight works!

Reporting Issues

When reporting issues, please include all of the following information:

If you know an issue is related to Phiki and not the Torchlight renderer, please create an issue here. If you are not sure, feel free to create an issue in this repository and it will eventually end up in the right place 🙂

Some issues may be difficult to resolve and take time to implement. Everyone involved thanks you in advance for your patience.

Contributing

Community contributions are welcome! However, if you are contributing additional themes or grammars, please take care to ensure their license allows it.

If you spot a grammar or theme that is being improperly used, please create an issue and it will be addressed.

Credits

License

The Torchlight Engine is free software, released under the MIT license.

Themes and grammars may be governed by their own license.


All versions of engine with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
phiki/phiki Version ^1.1.4
league/commonmark Version ^2.5.3
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package torchlight/engine contains the following files

Loading the files please wait ....