smuuf / primi
A scripting language written in PHP & executable within PHP.
Installs: 55 940
Dependents: 0
Suggesters: 0
Security: 0
Stars: 126
Watchers: 6
Forks: 15
Open Issues: 2
Requires
- php: >=7.1
- smuuf/php-peg: ^2
Requires (Dev)
- nette/tester: ^2.0
- phpstan/phpstan: ^0.12
- smuuf/koloader: dev-master
- smuuf/phpcb: dev-master
README
Primi
A scripting language written in PHP & interpreted in PHP.
Primi is meant for PHP developers who want to allow their clients to write their own custom logic. Primi allows you (the developer) to execute untrusted code (provided simply as a string) inside a sandbox, safely separated from its surroundings.
Quick access
Rationale
Primi - as things sometimes go in life - began as an answer to a practical problem: I needed some general-purpose (ie. not too much domain-specific) scripting language that my other app's users could use to write their simple custom logic. I needed some universally usable and primitive scripting thing, with familiar syntax (PHP-like
x C-like
x JS-like
) and one that could be safely executed inside pure PHP environment (no external depedencies on v8js, v8 and whatnot - meaning Javascript is out of the game...).
Thus, Primi was (mostly as an experiment) created.
Installation
You can either use Primi as a standalone package (a)
- for its development, making contributions, debugging it, or to just play with it. Or you can use Primi in your own projects (b)
by installing it as a Composer dependency.
You'll want either one of these:
git clone https://github.com/smuuf/primi.git
(standalone use)composer require smuuf/primi
(using Primi as a library in your own project)
a) Standalone installation
- Clone this repo.
git clone https://github.com/smuuf/primi.git
- Install Composer dependencies.
composer install
- Run something with Primi CLI.
chmod +x ./primi && ./primi -s -c "a = 1 + 2 / 3;"
Convenient installation Onelinerâ„¢:
git clone https://github.com/smuuf/primi.git && cd primi && composer install && chmod +x ./primi && ./primi -s -c "msg = 'Primi works.';"
Extra stuff:
-
Register Primi's CLI executable for current user so typing
primi
will behave like a binary (otherwise you'd need to write./primi
and would have to be in the right directory):./bin/registerbin
Note: This will add an alias in .bashrc for current user.
-
Run tests (tests are located inside
./tests/
directory):./bin/test
-
Rebuild parser (when you modify Primi's grammar definitions, you will want to rebuild the parser to reflect the changes):
./bin/buildparser
b) Using Primi as a library
- First, install Primi Composer package:
composer require smuuf/primi
- Then use it like this:
<?php require __DIR__ . "/vendor/autoload.php"; $context = new \Smuuf\Primi\Context; $interpreter = new \Smuuf\Primi\Interpreter($context); try { // Let the interpreter run a source code. $interpreter->run('a = 1; b = a + 2; c = "some string"; d = c + " extra thing";'); // Get defined variables from primary context and print them. foreach ($context->getVariables() as $name => $value) { printf("%s (%s) ... %s\n", $name, $value::TYPE, $value->getCoreValue()); } } catch (\Smuuf\Primi\ErrorException $e) { die($e->getMessage()); }
Running this code would output:
a (number) ... 1
b (number) ... 3
c (string) ... some string
d (string) ... some string extra thing
REPL mode
Primi provides a convenient "sandbox" REPL mode which is launched by executing ./primi
without any argument. You can use this for messing around with the language or to test any new stuff you might be trying to implement (e.g. your own Primi extensions written in PHP).
In this mode, all statements are executed when entered and the result value of the last expression is returned. REPL commands history is preserved between separate sessions (history is stored in ~/.primi_history
file).
Language reference
The basics of the language syntax and data types are found here: https://github.com/smuuf/primi/blob/master/docs/language_reference.md