php-script/php-script

php script is a script language powered by backend php with editing in the browser for supporting ui-driven php applications.

v1.0.3 2025-12-03 17:00 UTC

Requires

• php: ^8.4.0

Requires (Dev)

• laravel/pint: ^1.24.0
• pestphp/pest: ^4.1.0
• pestphp/pest-plugin-type-coverage: ^4.0.2
• phpstan/phpstan: ^2.1.26
• rector/rector: ^2.1.7
• symfony/var-dumper: ^7.3.3

MIT

• Robert Kummer

• php
• language
• script
• php script
• php-script

README

PHP Script is a scripting language that allows end-users to customize and extend your PHP-powered backend with the simplicity of JavaScript. It provides a secure and controlled environment to execute user-generated scripts without the need for a separate Node.js service.

Features

• Easy to Use: The syntax is inspired by JavaScript, making it familiar to a wide range of developers.
• Secure: The engine provides a sandboxed environment, giving you full control over the exposed functions and data.
• Flexible: You can expose any PHP function or variable to the script, allowing for powerful customizations.
• Lightweight: The package is designed to be lightweight and has minimal dependencies.

Installation

You can install the package via composer:

composer require php-script/php-script

Usage

1. Setting up the Engine

First, you need to create an instance of the Engine and expose the necessary data and functions to the script.

use PhpScript\Core\Engine;

class LoginStats
{
    public function count(): int
    {
        return 42;
    }
}

class User
{
    public string $name = "Administrator";
    public LoginStats $logins;

    public function __construct()
    {
        $this->logins = new LoginStats();
    }

    public function hasPermission(string $perm): bool
    {
        return $perm === 'admin';
    }
}

// Setting up the PHP Script engine
$engine = new Engine();
$engine->set('user', new User());
$engine->set('app_version', '1.2.3');
$engine->set('users_list', ['Alice', 'Bob', 'Charlie']);

// Optionally, set an execution time limit to prevent infinite loops
$engine->setExecutionTimeLimit(5); // Script will time out after 5 seconds

2. Writing a PHP Script

Now, you can write a script that interacts with the exposed data and functions.

// This is a line comment
echo 'Hello ' + user.name // String concatenation and object property access

// Calling a method
totalLogins = user.logins.count();
echo 'Logins: ' + totalLogins;

// Working with variables
var1 = 10;
var2 = var1 * 2 + totalLogins;
echo 'Sum: ' + var2;

// Conditional statements
if (var2 > 50) {
    echo 'var2 is greater than 50!';
}

// Looping through an array
echo 'Users list:';
foreach (users_list as u) {
    echo '- ' + u;
}

// Calling a method with an argument
if (user.hasPermission('admin')) {
    echo 'Access granted!';
}

// Accessing a global variable
echo 'App Version: ' + app_version;

3. Executing the Script

Finally, you can execute the script using the execute method of the Engine.

try {
    echo $engine->execute($script);
} catch (Exception $exception) {
    echo $exception->getMessage();
}

This will produce the following output:

Hello Administrator
Logins: 42
Sum: 62
var2 is greater than 50!
Users list:
- Alice
- Bob
- Charlie
Access granted!
App Version: 1.2.3

PHP Script Language Reference

Please take a look into the language reference online.

Features

• Abstract Syntax Tree (AST) is in use
• we render PHP from AST
• we can render PHP Script from AST
• robust error handling with a pointer to the root cause in the PHP Script
• 100% code coverage
• Whitelist implementation for allowing function calls
• Playground
  • use make playground and open http://localhost:8080/playground.php in your browser
  • with a Monaco prepared editor
  • using PhpScriptRenderer as linter
• Monarch language definition for the keywords and dynamic code suggestion for provided context
  • Monaco-based editors can learn the language and provide code completion (Monaco, vscode)

TODO

• render Mermaid.js Flowchart from AST
• Provide a Monaco editor component for vanilla JavaScript
• Provide a Monaco editor component for Vue.js
• Provide a Monaco editor component for React.js

Contribution

1. Create a branch from main
2. do your stuff
3. document your stuff here
4. call composer lint until no errors
5. call composer refactor until no errors
6. call composer lint again until no errors
7. call composer test until no errors
8. commit and push your changes and open a PR

SDD - Spec-Driven-Development

The spec-driven development is supported. All base files are generated.

The flow:

• /constitution - already DONE
• for each new feature:
  • /specify
    • optional: /clarify
  • /plan
  • /tasks
  • /implement
• optional: at any time /analyze to check your specs

Local development

🧹 Keep a modern codebase with Pint:

composer lint

✅ Run refactors using Rector

composer refactor

⚗️ Run static analysis using PHPStan:

composer test:types

✅ Run unit tests using PEST

composer test:unit

🚀 Run the entire test suite:

composer test

PHP Script was created by Robert Kummer under the MIT license.