Documentation

XP Compiler

Build status on GitHub Build Status on TravisCI XP Framework Module BSD Licence Requires PHP 7.0+ Supports PHP 8.0+ Latest Stable Version

Compiles future PHP to today's PHP.

Usage

After adding the compiler to your project via composer require xp-framework/compiler classes will be passed through the compiler during autoloading. Code inside files with a .class.php ending is considered already compiled; files need to renamed T.class.php => T.php in order to be picked up.

Example

The following code uses Hack language, PHP 8.1, 8.0, PHP 7.4, PHP 7.3, PHP 7.2, PHP 7.1 and PHP 7.0 features but runs on anything >= PHP 7.0. Builtin features from newer PHP versions are translated to work with the currently executing runtime if necessary.

<?php // In a file "HelloWorld.php"

use lang\Type;
use util\cmd\Console;

#[Author('Timm Friebe')]
#[Permissions(0o777)]
class HelloWorld {
  public const GREETING = 'Hello';

  public static function main(array<string> $args): void {
    $greet= fn($to, $from) => self::GREETING.' '.$to.' from '.$from;
    $author= Type::forName(self::class)->getAnnotation('author');

    Console::writeLine($greet($args[0] ?? 'World', from: $author));
  }
}

Compilation

By default, XP Compiler will hook into the class loading chain and compile files on-demand. This keeps the code-save-reload/rerun development process typical for PHP. However, compilation can also be performed manually by invoking the compiler:

# Compile code and write result to a class file
$ xp compile HelloWorld.php HelloWorld.class.php

# Compile standard input and write to standard output.
$ echo "<?php ..." | xp compile -

# Compile src/main/php and src/test/php to the dist folder.
$ xp compile -o dist src/main/php/ src/test/php/

# Compile src/main/php to the dist.xar archive
$ xp compile -o dist.xar src/main/php/

# Compile src/main/php, do not write output
$ xp compile -n src/main/php/

# Target PHP 7.4 (default target is current PHP version)
$ xp compile -t PHP.7.4 HelloWorld.php HelloWorld.class.php

The -o and -n options accept multiple input sources following them. The -q option suppresses all diagnostic output except for errors.

Features supported

XP Compiler supports features such as annotations, arrow functions, enums property type-hints, the null-safe instance operator as well as all PHP 7 and PHP 8 syntax additions. A complete list including examples can be found in our Wiki.

Additional syntax can be added by installing compiler plugins from here:

$ composer require xp-lang/php-is-operator
# ...

$ xp compile
Usage: xp compile <in> [<out>]

@FileSystemCL<./vendor/xp-framework/compiler/src/main/php>
lang.ast.emit.PHP70
lang.ast.emit.PHP71
lang.ast.emit.PHP72
lang.ast.emit.PHP74
lang.ast.emit.PHP80 [*]
lang.ast.emit.PHP81
lang.ast.syntax.php.Using [*]

@FileSystemCL<./vendor/xp-lang/php-is-operator/src/main/php>
lang.ast.syntax.php.IsOperator

Implementation status

Some features from newer PHP versions as well as Hack language are still missing. The goal, however, is to have all features implemented - with the exception of where Hack's direction conflicts with PHP! An overview can be seen on this Wiki page.

To contribute, open issues and/or pull requests.

See also