Download the PHP package pug-php/pug without Composer

Pug-php

Pug-php adds inline PHP scripting support to the Pug template compiler. Since version 3, it uses Phug, a very customizable Pug template engine made by the tale-pug and pug-php developers as the new PHP Pug engine reference.

Official Phug documentation

See Pug-php demo

Get supported pug-php/pug with the Tidelift Subscription

Install

First you need composer if you haven't yet: https://getcomposer.org/download/

Then run:

Pug in your favorite framework

Phalcon: https://github.com/pug-php/pug-phalcon

Symfony: https://github.com/pug-php/pug-symfony

Laravel: https://github.com/BKWLD/laravel-pug

CodeIgniter: https://github.com/pug-php/ci-pug-engine

Yii 2: https://github.com/rmrevin/yii2-pug

Slim 3: https://github.com/MarcelloDuarte/pug-slim

Zend Expressive: https://github.com/kpicaza/infw-pug

Use

Since pug-php 3.1.2, you no longer need to import the class with use Pug\Pug; as we provide an alias.

Main methods are render, renderFile, compile, compileFile, display, displayFile and setOption, see the complete documentation here: phug-lang.com.

You can also use the facade to call methods statically:

Pug options

Pug options should be passed to the constructor

Supports for local variables

New in pug-php 3

pug-php 3 is now aligned on pugjs 2, it aims to be a perfect implementation of the JS project. That's why there are breaking changes in this new version.

See the changelog to know what's new

See the migration guide if you want to upgrade from pug-php 2 to 3

Support for custom filters

Filters must be callable: It can be a class that implements the __invoke() method or an anonymous function.

Built-in filters

• :css
• :php
• :javascript
• :escaped
• :cdata

Install other filters with composer

http://pug-filters.selfbuild.fr/

Publish your own filter

https://github.com/pug-php/pug-filter-base#readme

Support for custom keywords

You can add custom keywords, here are some examples:

Anonymous function:

This will render:

Note that the existing operator will have the precedence on this custom keyword.

Invokable class:

This will render:

A keyword must return an array (containing begin and/or end entries) or a string (used as a begin entry).

The begin and end are rendered as raw HTML, but you can also use beginPhp and endPhp like in the first example to render PHP code that will wrap the rendered block if there is one.

PHP Helper functions

If you want to make a php function available in a template or in all of them for convenience, use closures and pass them like any other variable:

This will render:

You can make that closure available to all templates without passing it in render params by using the share method:

This will render the same HTML than the previous example. Also note that share allow you to pass any type of value.

Cache

Important: to improve performance in production, enable the Pug cache by setting the cache option to a writable directory, you can first cache all your template at once (during deployment):

Be sure any unexpected error occurred and that all your templates in your template directory have been cached.

Then use the same cache directory and template directory in production with the option upToDateCheck to to bypass the cache check and automatically use the cache version:

Templates from pug-js

First remember pug-php is a PHP template engine. Pug-js and Pug-php provide both, a HAML-like syntax for markup and some abstraction of the language behind it (loops, conditions, etc.). But for expressions and raw code, pug-js uses JS, and pug-php uses PHP. By default, we do some magic tricks to transform simple JS syntax into PHP. This should help you to migrate smoother from pug-js if you already have some templates, but benefit from the PHP advantages.

If you start a new project, we highly recommend you to use the following option:

It will disable all translations, so you always have to use explicit PHP syntax:

If you want expressions very close to JS, you can use:

It will allow both PHP and JS in a JS-style syntax. But you have to stick to it, you will not be able to mix PHP and JS in this mode.

Finally, you can use the native pug-js engine with:

This mode requires node and npm to be installed as it will install pug-cli and directly call it. This mode will flatten your local variables (it means complex object like DateTime, or classes with magic methods will be stringified in JSON to simple objects) and you will not benefit from some features like mixed indent, pre/post render hooks. But in this mode you will get exact same output as in pug-js.

Write locals object to JSON file with pug-js

If your locals object is large it may cause a RuntimeException. This is because locals object passed directly to pug-cli as argument. To fix this problem you can use the localsJsonFile option:

Then your locals will be written to a JSON file and the path of the file will be passed to the compiler.

Pug CLI

Pug also provide a CLI tool:

See the complete CLI documentation here

Check requirements

To check if your environment is ready to use Pug, use the requirements method:

Contributing

All contributions are welcome, for any bug, issue or merge request (except for security issues) please refer to CONTRIBUTING.md

Security

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Contributors

This project exists thanks to all the people who contribute.

And all the people contributing to our dependencies, in particular: The Phug engine The JS syntax converter Js-Phpize

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor

And a big thank-you to Jet Brains who provides such a great IDE: