A Common Expression Language Implementation in PHP

This repository contains a PHP implementation of the Common Expression Language (CEL).

Table of Contents

• Documentation
• Example
• Specification Compliance
• License
• Security Policy
• Code of Conduct
• Contributing
• Development
  • Justfile Recipes
  • Local Setup

Documentation

• Getting Started
• Standard Extensions Reference

Example

use Cel;
use Psl\IO;

const EXPRESSION = <<<CEL
    account.balance >= transaction.withdrawal
        || (account.overdraftProtection
        && account.overdraftLimit >= transaction.withdrawal - account.balance)
CEL;


$configuration = new Cel\Runtime\Configuration(
    // You can customize the runtime configuration here
);

$runtime = new Cel\Runtime\Runtime(configuration: $configuration);
$cel = new Cel\CommonExpressionLanguage(runtime: $runtime);

try {
    // Parse the expression
    $expression = $cel->parseString(EXPRESSION);
    
    // Perform optimizations on the expression, e.g. short-circuiting
    $expression = $cel->optimize($expression); 
    
    // Evaluate the expression with a given environment
    $result = $cel->run($expression, Cel\Runtime\Environment\Environment::fromArray([
        'account' => [
            'balance' => 500,
            'overdraftProtection' => true,
            'overdraftLimit' => 1000,
        ],
        'transaction' => [
            'withdrawal' => 700,
        ],
    ]));

    IO\write_line('Result: %s(%s)', $result->getType(), var_export($result->getNativeValue(), true));
} catch (Cel\Parser\Exception\ExceptionInterface $exception) {
    // Parsing failed...
} catch (Cel\Runtime\Exception\IncompatibleValueTypeException $e) {
    // An environment variable has an incompatible type...
} catch (Cel\Runtime\Exception\EvaluationException $e) {
    // Some other runtime error...
}

Specification Compliance

This project is still under heavy development. Below is a non-exhaustive list of features and their implementation status according to the CEL specification.

• Language Features
  • Macros
    • has(e.f)
    • e.all(x, p)
    • e.exists(x, p)
    • e.exists_one(x, p)
    • e.map(x, t) (for lists and maps)
    • e.map(x, p, t)
    • e.filter(x, p) (for lists and maps)
  • Types
    • String
    • Bytes
    • Integer
    • Unsigned Integer
    • Double
    • Boolean
    • Null
    • List
    • Map
    • Message
    • Duration
    • Timestamp
• Interpreter & Runtime
  • Tree-Walking Interpreter
  • Stack-Based Interpreter
• Performance
  • Caching Strategy
• API & Quality
  • API Improvements
  • Testing & Coverage

License

This project is licensed under the terms of the LICENSE file.

Security Policy

For information on security vulnerabilities and how to report them, please refer to our SECURITY.md.

Code of Conduct

Please review our CODE_OF_CONDUCT.md for expected behavior and guidelines for participation.

Contributing

We welcome contributions! Please see our CONTRIBUTING.md for details on how to get started.

Development

This project uses just for task automation.

Justfile Recipes

You can see all available commands by running just --list. Some common recipes include:

• just install: Installs project dependencies.
• just test: Runs the test suite.
• just lint: Runs linting checks.
• just verify: Runs all checks (tests, linting, etc.) to ensure code quality. Always run just verify before pushing any changes.

Local Setup

To get started with local development, you'll need to install just and typos.

Installing Just:

If you have Rust and Cargo installed, you can install just via Cargo:

car go install just

Alternatively, you can find other installation methods in the Just documentation.

Installing Typos:

If you have Rust and Cargo installed, you can install typos via Cargo:

car go install typos-cli

After installing just and typos, you can install the project dependencies and run verification checks:

just install
just verify