Js Phpize Phug Laravel Package

Getting Started

This package is the glue between two libraries: JsPhpize (transpiles JavaScript expressions to PHP at compile time) and Phug (a Pug template engine for PHP). In practice it lets you keep writing Pug templates the way a front-end developer would — with JS expressions, var, ternaries, JS-style operators — while rendering them server-side in PHP.

Minimal setup:

composer require js-phpize/js-phpize-phug

Then register the adapter as a Phug module/extension on the renderer:

use Phug\Renderer;

$renderer = new Renderer([
    'paths'     => [__DIR__ . '/views'],
    'cache_dir' => __DIR__ . '/cache',
    'modules'   => [\JsPhpize\JsPhpizePhug::class], // adapter entry point
]);

echo $renderer->renderFile('profile.pug', ['user' => $user]);

And in views/profile.pug:

- var discount = user.isPremium ? 0.2 : 0
- var price = product.price * (1 - discount)
h1= user.name
p= price

Where to look first:

1. The repo README for the exact class name and registration option (this is a small package — the README is the documentation).
2. The src/ directory if the README is thin; the adapter is usually a small class that registers JsPhpize as a Phug compiler/filter module.
3. The upstream js-phpize README for the expression syntax that is actually supported; the adapter only wires it in.

First real use case: you have a Pug template written for Node/Pug (or you want to write one that way) and you need to render it from PHP without rewriting every - var x = ... line into PHP. This package is the fastest path to that, and it also works well when front-end devs own the templates and PHP devs own the data.

Implementation Patterns

Register the adapter once at bootstrap, not per render. Phug resolves modules when the renderer is constructed, so build a single Renderer (or a container-bound singleton) and reuse it. Creating a renderer per request re-parses options and defeats the compiled-template cache.

// bootstrap / service provider
$container->singleton(Renderer::class, fn () => new Renderer([
    'paths'     => [resource_path('views')],
    'cache_dir' => storage_path('framework/views/phug'),
    'modules'   => [\JsPhpize\JsPhpizePhug::class],
    'debug'     => env('APP_DEBUG'),
]));

Keep statements in - and output in =. The idiomatic split still applies. Use - var x = ... for variables and = expr / #{expr} for output. This makes it obvious which lines are passed through JsPhpize versus treated as plain Pug text.

- var items = cart.items.filter(function (i) { return i.qty > 0; })
ul
  each item in items
    li= item.name + ' × ' + item.qty

Share data, don't embed data. Pass PHP arrays/objects via the second argument to renderFile and treat them as the JS scope. Avoid putting business logic in the template; use it only for presentation-level expressions (formatting, ternaries, arithmetic, small loops).

$renderer->renderFile('cart.pug', [
    'cart'  => $cart->toArray(),
    'user'  => $auth->user(),
]);

Mixing PHP and JS is possible but should be a deliberate boundary. Some projects use JS expressions for the template logic and PHP for helper calls injected into scope (e.g. $formatMoney as a closure). Keep that boundary consistent; don't alternate styles within a single template file.

Framework integration. Wire the renderer into your app's view layer (Laravel, Slim, Symfony, or plain PHP). Because Phug compiles to PHP and caches, the runtime cost after the first render is just executing generated PHP — comparable to Twig/Blade.

Compile-then-inspect workflow. During development, render the template and open the compiled file in cache_dir. The generated PHP is the exact translation JsPhpize produced; it is the single most useful debugging artifact. Enable debug so cache is regenerated on template change.

Gotchas and Tips

• JS ≠ PHP semantics. + on mixed types, == vs ===, undefined vs null, truthiness of "0", and array key handling all behave differently than you might expect. JsPhpize emulates JS where it can, but always test expressions that mix types.
• Not all of ES2015+ is supported. Arrow functions, template literals, destructuring, and some array methods may or may not be available depending on the js-phpize version. Check the core README's supported-syntax list before leaning on modern JS; when in doubt, use function () {} and string concatenation.
• String/array methods are a common failure point. .toUpperCase(), .map(), .reduce(), .toFixed() depend on JsPhpize's method stubs. If a method silently produces wrong output, rewrite it as a plain expression or call a PHP helper injected into scope.
• Errors surface as PHP errors in generated code. A syntax issue may appear as a PHP parse error pointing at the compiled file, not your .pug. Always include the compiled path in stack traces when reporting bugs.
• Enable the cache in production. JsPhpize runs during compilation, so the transpilation cost is paid once per template version. Disable the cache in dev (so changes hot-reload) and enable it in prod; otherwise every request pays the JsPhpize parse cost.
• Module ordering and options. In Phug, module registration order and priority can matter if you also use other modules (filters, extensions). Register JsPhpize after core extensions and keep its options in one place.
• Templates are code — treat them as trusted. Do not let user input flow into template source. Expressions are compiled to PHP; a "template editor" feature would be an RCE vector.
• Version pinning matters in a small ecosystem. With 5 stars and 0 dependents, there's little community pressure to keep interfaces stable. Pin js-phpize, phug, and this adapter together in composer.json, and read the diff on upgrades.
• Extension points. JsPhpize itself exposes hooks for allowed functions and custom keywords; if you need a JS helper that maps to a PHP callable, that's the place to add it rather than hacking the compiled output.
• When it's worth it. If your team already has Pug templates from a Node project, this adapter saves a rewrite. If you're starting fresh in PHP, plain Phug (or Blade/Twig) is simpler and better supported — use this package only when JS-in-templates is a real requirement.