README
¶
phpscript - A custom PHP-flavoured runtime written in Go
This is a PHP interpreter written in Go. It supports the basic php expression syntax and some parts of the standard library. It's currently rudimentary and only enables limited functionality.
- About phpscript
- Design decisions
- Language reference and PHP compatibility
- Installation and usage
- Configuration
- Testing and extending tests
- Test fixture results
- Code coverage
- Naming conventions
- Go Reference
- Creating phpscript applications
- Building an application
- Use cases
Current state
Behaviour is settled by .phpt fixtures: each one is written by running the
source through real php first, and phpscript test tests/fixtures/...
checks the runtime against that output. The generated
test fixture results hold the per-fixture matrix;
the bird's-eye view per area:
| Area | Fixtures | Passed | Failed |
|---|---|---|---|
| tests/fixtures/arithmetic | 21 | 21 | 0 |
| tests/fixtures/arrays | 18 | 18 | 0 |
| tests/fixtures/autoloading | 8 | 8 | 0 |
| tests/fixtures/bindings | 23 | 23 | 0 |
| tests/fixtures/errors | 2 | 2 | 0 |
| tests/fixtures/exceptions | 9 | 9 | 0 |
| tests/fixtures/flatstack | 7 | 7 | 0 |
| tests/fixtures/functions | 9 | 9 | 0 |
| tests/fixtures/gd | 7 | 7 | 0 |
| tests/fixtures/includes | 3 | 3 | 0 |
| tests/fixtures/namespaces | 2 | 2 | 0 |
| tests/fixtures/oop | 24 | 24 | 0 |
| tests/fixtures/output | 4 | 4 | 0 |
| tests/fixtures/paths | 2 | 2 | 0 |
| tests/fixtures/regex | 7 | 7 | 0 |
| tests/fixtures/runtime | 11 | 11 | 0 |
| tests/fixtures/stdlib | 17 | 17 | 0 |
| tests/fixtures/strings | 15 | 15 | 0 |
| tests/fixtures/syntax | 8 | 8 | 0 |
| Total | 197 | 197 | 0 |
The Go test run collects a coverage profile (about 84% of statements at the
time of writing), and atkins cover renders it into the generated
code coverage report, per package and per function.
Building a docker image
You can build a docker image from source as follows:
CGO_ENABLED=0 go build -o bin/ .
docker build -t titpetric/phpscript:latest -f docker/Dockerfile .
See ./compose.yml for usage.
Contributing
Contributions welcome. Open an issue to discuss before opening PRs.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package annotations discovers annotated PHP files in a source tree and gives them a lifecycle: routed endpoints are served over HTTP, startup jobs run once before the server listens, and scheduled jobs run on an interval.
|
Package annotations discovers annotated PHP files in a source tree and gives them a lifecycle: routed endpoints are served over HTTP, startup jobs run once before the server listens, and scheduled jobs run on an interval. |
|
cmd
|
|
|
Package config defines the config/config.yml configuration model.
|
Package config defines the config/config.yml configuration model. |
|
Package flatstack provides the runner embedding API with an opt-in flat bytecode backend.
|
Package flatstack provides the runner embedding API with an opt-in flat bytecode backend. |
|
engine
Package engine compiles model AST programs into flat bytecode and executes them against a host-provided PHP semantics bridge.
|
Package engine compiles model AST programs into flat bytecode and executes them against a host-provided PHP semantics bridge. |
|
Package formatter pretty-prints phpscript ASTs in a gofmt-like style: hard tabs, canonical `function` keywords, parentheses on control structures, semicolons, collapsed blank lines, and a trailing newline.
|
Package formatter pretty-prints phpscript ASTs in a gofmt-like style: hard tabs, canonical `function` keywords, parentheses on control structures, semicolons, collapsed blank lines, and a trailing newline. |
|
internal
|
|
|
apidoc
Package apidoc generates docs/reference/extensions/implemented-apis.md.
|
Package apidoc generates docs/reference/extensions/implemented-apis.md. |
|
phpval
Package phpval holds PHP's value semantics: how a value converts to a string, an integer or a truth value, how a collection reads back as a list of values or strings, and how two values order under PHP 8's <=> operator.
|
Package phpval holds PHP's value semantics: how a value converts to a string, an integer or a truth value, how a collection reads back as a list of values or strings, and how two values order under PHP 8's <=> operator. |
|
table
Package table renders a result table as an ansi box-drawing table on a terminal and as markdown everywhere else.
|
Package table renders a result table as an ansi box-drawing table on a terminal and as markdown everywhere else. |
|
Package list builds a markdown inventory of PHP routes, files and classes.
|
Package list builds a markdown inventory of PHP routes, files and classes. |
|
Package model holds the shared data structures (AST, runtime values, class metadata) used by both the parser and the runner packages.
|
Package model holds the shared data structures (AST, runtime values, class metadata) used by both the parser and the runner packages. |
|
Package parser turns PHP source (the limited subset described in the project README) into the shared model AST consumed by the runner.
|
Package parser turns PHP source (the limited subset described in the project README) into the shared model AST consumed by the runner. |
|
coverage
Package coverage is the statement-coverage extension of the runner: a collector the interpreter reports statement executions to, and the profile blocks a host renders from it.
|
Package coverage is the statement-coverage extension of the runner: a collector the interpreter reports statement executions to, and the profile blocks a host renders from it. |
|
scripts
|
|
|
list-apis
command
Command list-apis generates docs/reference/extensions/implemented-apis.md.
|
Command list-apis generates docs/reference/extensions/implemented-apis.md. |
|
Package stdlib provides the forwarded "bring your own standard library" shims (the README's register_function mechanism).
|
Package stdlib provides the forwarded "bring your own standard library" shims (the README's register_function mechanism). |
|
compat
Package compat implements PHP language surface that a script expects to be there rather than a library it calls: functions whose behaviour is defined by what the interpreter does, not by what they compute.
|
Package compat implements PHP language surface that a script expects to be there rather than a library it calls: functions whose behaviour is defined by what the interpreter does, not by what they compute. |
|
core
Package core holds the part of PHP's standard library that computes: strings, arrays, json, the language constructs exposed as functions, the tokenizer, the environment and the platform surface a program expects to find before it does anything interesting.
|
Package core holds the part of PHP's standard library that computes: strings, arrays, json, the language constructs exposed as functions, the tokenizer, the environment and the platform surface a program expects to find before it does anything interesting. |
|
crypto
Package crypto holds the password hashing and the random source a script cannot write for itself.
|
Package crypto holds the password hashing and the random source a script cannot write for itself. |
|
database
Package database holds the named sql connections a phpscript runtime resolves through.
|
Package database holds the named sql connections a phpscript runtime resolves through. |
|
files
Package files provides the filesystem shims phpscript exposes to PHP: path helpers, reads, writes, streams, and the uploaded-file functions that go with $_FILES.
|
Package files provides the filesystem shims phpscript exposes to PHP: path helpers, reads, writes, streams, and the uploaded-file functions that go with $_FILES. |
|
gd
Package gd provides PHP's image functions over the standard library's image packages and golang.org/x/image.
|
Package gd provides PHP's image functions over the standard library's image packages and golang.org/x/image. |
|
http
Package http provides the HTTP\Client and HTTP\Request bindings, the outbound HTTP surface a script reaches instead of PHP's curl_* family.
|
Package http provides the HTTP\Client and HTTP\Request bindings, the outbound HTTP surface a script reaches instead of PHP's curl_* family. |
|
internals
Package internals provides PHP internal memory and runtime introspection bindings.
|
Package internals provides PHP internal memory and runtime introspection bindings. |
|
logger
Package logger writes a log line and fails the span the work runs in when that line reports an error.
|
Package logger writes a log line and fails the span the work runs in when that line reports an error. |
|
pexec
Package pexec exposes process execution to PHP: exec runs a command through the shell the way PHP's does, escapeshellarg quotes an argument for it, and posix_getpid names the running process.
|
Package pexec exposes process execution to PHP: exec runs a command through the shell the way PHP's does, escapeshellarg quotes an argument for it, and posix_getpid names the running process. |
|
session
Package session implements Session\Manager and the Session\Storage\* family: an HTTP-only cookie carrying an opaque, randomly generated session ID, and the storage the data behind that ID lives in.
|
Package session implements Session\Manager and the Session\Storage\* family: an HTTP-only cookie carrying an opaque, randomly generated session ID, and the storage the data behind that ID lives in. |
|
shared
Package shared holds PHP behaviour that runner and stdlib both need.
|
Package shared holds PHP behaviour that runner and stdlib both need. |
|
span
Package span exposes telemetry spans to PHP as the start_span() binding, so a script can measure a region of its own work next to the spans the interpreter records for it.
|
Package span exposes telemetry spans to PHP as the start_span() binding, so a script can measure a region of its own work next to the spans the interpreter records for it. |
|
time
Package time exposes Go's time values to PHP without wrapping their method sets.
|
Package time exposes Go's time values to PHP without wrapping their method sets. |
|
Package telemetry binds github.com/titpetric/oida into the phpscript namespace: traces and spans recorded in process, with a server side rendered front end mounted at /debug/oida.
|
Package telemetry binds github.com/titpetric/oida into the phpscript namespace: traces and spans recorded in process, with a server side rendered front end mounted at /debug/oida. |
Click to show internal directories.
Click to hide internal directories.