PHP runtime for Teal

Usage no npm install needed!

<script type="module">
  import tealPhp from 'https://cdn.skypack.dev/teal-php';


Use teal-php to compile your .tl files to PHP.

Getting started

In the follwing guide we'll create four files to get the first Teal-PHP Hello World app running.

1. package.json

Create an empty directory for your project and call:

npm init

This will create an empty package.json file. In order to add teal-php run:

npm i -S teal-php

Create a directory called site in your project root where you put your PHP files.

Inside this directory create a folder called _tl. This is where the Teal templates will be placed.

├── build.js
├── package.json
└─┬ site/
  ├─┬ _tl/
  │ └── page.tl
  └── index.php

2. /site/index.php

In order to render a Teal template in PHP you have to include /_tl/init.php and call the tl() function:


require '_tl/init.php';

echo tl('/page',
  [ 'title' => 'Hello' ],
  'Hello World!'

Note: Don't worry that the init.php doesn't exist yet. Teal will create for you in the next step.

3. /site/_tl/page.tl

html {
  head {
    title { $title }
  body {
    background: teal;
    color: #fff;

4. /build.js

Now create a file called build.js in your project's root directory (not the site folder). This is the place where you can configure Teal and set up additional plugins like teal-autoprefixer or teal-browserify.

var teal = require('teal-php');

var tl = teal({
  docroot: './site'

// add the autoprefixer plugin:
// tl.use(require('teal-autoprefixer'));

You can now build your project by running:

node build

This will create a folder called .site. All php sources will be copied there and all .tl will be compiled to .tl.php files. After this step your directory should look like this:

├─┬ .site/
│ ├─┬ _tl/
│ │ ├── init.php
│ │ └── page.tl.php
│ └─ index.php
├── build.json
├── package.json
└─┬ site/

Starting a development server

Teal-php comes with a built-in development server. If you pass the dev:true option, teal will watch your source files and start a PHP server.

Modify your build.js file to read some command line arguments:

var teal = require('teal-php')

var dev = process.argv[2] == 'dev'
var port = process.argv[3]

var tl = teal({
  docroot: __dirname + '/site',
  dev: dev,
  port: port

Then run node build dev 3000 to start a server. If you omit the port, teal-php will choose a free random and automatically open a browser window.


  • docroot – Specifies where the PHP sources are located. Relative paths are resolved against the current working directory. Defaults to "./site"

  • dest – Where the build process will put all files. If not specified, a directory right next to the docroot will be created (prefixed with a dot). Letting this point to same directory as as docroot is a valid option, too. In this case no copy operations will be performed. Defaults to undefined

  • asseturl – The URL prefix under which assets will be exposed. Defaults to "/assets"

  • assetdest Where the assets will be stored. Relative paths are resolved against dest. Defaults to dest + asseturl

  • tlroot – Specifies where the .tl are located. Relative paths are resolved against the docroot. Defaults to "_tl"

  • tldest – Where within dest the compiled .tl.php files will be stored. Defaults to "_tl"

  • ext – File extension to use for the compiled templates. Defaults to ".tl.php"

  • lib – Filename under which the Teal PHP library will be stored. Relative paths are resolved against tldest. Defaults to init.php

  • php – Options to be passed to the php-proxy-middleware.