README

Write PHP templates with #include directives similar to those processed by the C preprocessor.

Also optionally evaluates <?php ?> blocks.

Install

If you want to use composer:

composer require-dev jchook/phpp

or download the phar and include it in your project

Example

Make a file that can contain cpp-like #include directives and/or PHP templating.

Dockerfile.in

FROM alpine:3.14

#include "php.dockerfile"
#include "runit.dockerfile"

Then run the script to build it, similar to cpp.

phpp -o Dockerfile Dockerfile.in

Command-Line Usage

USAGE

  phpp [options] PATH...

OPTIONS

  -h, --help  Show this help info
  -o PATH     Output processed file to PATH. (multi)
  -I PATH     Look here for included files (multi)
  --ext       Look for files with this extension (multi)
  --eval      Evaluate PHP in included files
  -v          Verbose mode

Options labeled (multi) can be invoked multiple times.

PHP Interface

See the source code for more info. Here's a simple example:

<?php

use Jchook\Phpp\Preprocessor;

$pre = new Preprocessor();
$pre->makeFile('Dockerfile.in');

Motivation

Dockerfiles do not allow you to INCLUDE other Dockerfiles. This is a known and embraced limitation.

Folks have suggested using cpp to translate #include directives, but this has critical issues:

• Cannot use normal # comments, as ccp will throw an error
• The cpp manual warns against using it for non-C code

This tool leverages PHP (a powerful, turing-complete templating language) to provide a complete templating solution with a familiar #include shortcut.

Why not use plain ol' PHP?

Consider these two examples in a Dockerfile side-by-side:

# PHP include:
#<?php include __DIR__ . '/thing.dockerfile' ?>

# CPP-like include
#include "thing.dockerfile"

Using "just PHP" presents some awkward quirks:

• Ideally you can comment out the include line to avoid raising syntax errors or strange highlighting issues in your code editors / IDE.

• Commenting out the include line means the first line of the included file is commented out.

• No automatic paper trail showing which code came from which include in the output file(s).

• More cumbersome syntax, requiring more explicit include paths.

Caveat

If your Dockerfile or similar code contains the string <?php you PHP will interpret that. If you do not want this behavior, be sure to escape at least one of the characters or disable eval mode.