Documentation
¶
Overview ¶
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.
Two annotations are recognised, both written as comments:
- `// @route GET /users/{id}` registers an HTTP endpoint.
- `// @startup` marks a file the server executes before it listens.
- `// @schedule daily -- prune` runs a file on a clock or interval.
Routes ¶
The `@route` tag takes an HTTP method and a path, optionally separated from the tag by a colon, one route per line:
- `// @route GET /users/{id}`
- `// @route POST /users/{id}`
- `// @route: /users/{id}`
The tag can be repeated to register multiple handlers. In the case of a duplicate handler being registered, the last one wins and a warning is printed in the logs.
If method is omitted, only GET and POST are routed to the handler. This ignores requests like HEAD and OPTIONS, ideally leaving these to be resolved in the router, rather than invoking PHP.
Specific HTTP methods like PUT are only reachable when explicitly stated.
This functionality fills a phpscript-specific auto-global value:
- `$_PATH`, specifically `$_PATH['id']`.
It relies on the Go standard library to extract path parameters present.
Startup jobs ¶
A file carrying `@startup` runs once, in path order, before the server listens. It executes with the CLI SAPI, so it can migrate a schema or warm a cache. An error aborts startup.
Scheduled jobs ¶
A file may repeat `@schedule` with an interval spec and optional `-- args` passed as `$argv`. Specs: `every N seconds|minutes|hours`, `hourly`, `daily`, `weekly`, `monthly`, `every weekday`, `every sunday` (any weekday name), `N times per hour|day`. Calendar specs fire at local midnight. A tick is skipped when the previous run is still going. Output is recorded on the oida span as `output`.
Discovery ¶
The .php files are scanned recursively, so you may keep them in a single folder, or just place them in arbitrary subfolders. Files without annotations are skipped, as are `vendor` directories: a composer dependency does not get to publish routes into the application, or to run at startup.
Index ¶
- func HasStartup(src []byte) bool
- func ParseRoutes(src []byte) []model.RouteAnnotation
- type Option
- func WithExcludedDirectory(name string) Option
- func WithExprCache(cache *runner.ExprCache) Option
- func WithFlatstack(enabled bool) Option
- func WithModuleSuffix(suffix string) Option
- func WithObservers(observers ...runner.Observer) Option
- func WithOutput(out io.Writer) Option
- func WithRootDir(dir string) Option
- func WithRunnerOptions(options runner.Options) Option
- func WithRuntimeFunc(fn RuntimeFunc) Option
- type Registrar
- type Route
- type RuntimeFunc
- type Schedule
- type Scheduler
- type Startup
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HasStartup ¶
HasStartup reports whether src carries an @startup comment, marking a file the server executes once before it listens. `phpscript list` uses it to show startup files alongside routed ones.
func ParseRoutes ¶
func ParseRoutes(src []byte) []model.RouteAnnotation
ParseRoutes returns the @route declarations found in src. A path-only annotation expands to both GET and POST, matching the HTTP router.
Types ¶
type Option ¶
type Option func(*config)
Option configures how annotated PHP files are discovered and executed. The same options apply to Route and Startup: both scan one source tree and run PHP files out of it.
func WithExcludedDirectory ¶
WithExcludedDirectory skips a top-level directory while scanning.
func WithExprCache ¶
WithExprCache sets a shared expression cache used by routed endpoints.
func WithFlatstack ¶
WithFlatstack enables the flat bytecode runtime with interpreter fallback.
func WithModuleSuffix ¶ added in v0.3.1
WithModuleSuffix distinguishes the platform modules of one source tree from another's. A server running several virtual hosts registers a module set per site, and platform.Options.Modules addresses modules by name, so the names have to differ.
func WithObservers ¶
WithObservers attaches runtime observers to every annotated PHP file.
func WithOutput ¶
WithOutput sets where a startup job writes its output. Routed endpoints write to the HTTP response instead, and ignore this.
func WithRootDir ¶
WithRootDir grants annotated PHP files access to the project directory, backing filesystem functions like fopen().
func WithRunnerOptions ¶
WithRunnerOptions configures the runtimes created for annotated PHP files.
func WithRuntimeFunc ¶
func WithRuntimeFunc(fn RuntimeFunc) Option
WithRuntimeFunc registers fn to customize each runtime after the standard library and the request context have been installed on it.
type Registrar ¶
Registrar binds a handler to an HTTP method and path. It is the seam between discovered routes and whichever router the application runs.
type Route ¶
type Route struct {
platform.UnimplementedModule
// contains filtered or unexported fields
}
Route serves the @route endpoints of a PHP source tree. It is a platform.Module, and registers on a standard library mux just as well.
type RuntimeFunc ¶
RuntimeFunc customizes a PHP runtime before an annotated PHP file executes.
type Schedule ¶
type Schedule struct {
Raw string
Args []string
Every time.Duration
Weekdays []time.Weekday
MonthDay int
Align align
}
Schedule is one `@schedule` annotation: when to run, and argv after `--`.
func ParseSchedules ¶
ParseSchedules returns the @schedule declarations found in src. A line may carry `-- args` after the interval spec; those become $argv[1:].
type Scheduler ¶
type Scheduler struct {
platform.UnimplementedModule
// contains filtered or unexported fields
}
Scheduler runs @schedule jobs for the life of the server. Start returns immediately; each job waits until its next due time in its own goroutine.
func NewScheduler ¶
NewScheduler creates a schedule module reading jobs from root.
type Startup ¶
type Startup struct {
platform.UnimplementedModule
// contains filtered or unexported fields
}
Startup runs the @startup jobs of a PHP source tree once, in path order, before the platform starts its server.
func NewStartup ¶
NewStartup creates a startup lifecycle module reading jobs from root.
func (*Startup) Start ¶
Start executes every PHP file carrying an @startup annotation and reports what failed.
One job failing does not stop the others: the tree's jobs are independent, and the errors are joined into the returned one so a caller learns about all of them rather than the first. Whether a failure is fatal is the caller's decision, not this module's; a server hosting several sites records it and carries on, where a single site server may well not.
Source Files