README

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

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

Documentation

Example

use Cel;
use Psl\IO;

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

try {
    $result = Cel\run(EXPRESSION, [
        '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\RuntimeException $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

carthage-software / cel-php

Maintainers

Details