API Reference¶
Everything below is exported from the cl-cc/php package.
The package has two very different kinds of export, and the distinction matters more than usual here:
- Entry points — the stable, user-facing surface. Fully specified below.
- Runtime builtins (the
%php-prefixed symbols) — a compilation target. They exist so that code generated by cl-cc can name PHP semantics primitives. They are catalogued below rather than individually specified, because their contract is "behave like the corresponding PHP construct" and they change alongside the compiler. See Compatibility.
Entry points¶
tokenize-php-source¶
Tokenizes a PHP source string into a list of token plists.
source is a string containing PHP source, including the opening <?php tag.
Returns: a list of plists of the form (:type :T-XXX :value val). The list
always ends with (:type :T-EOF :value nil), so callers detect the end without
tracking length.
Signals: type-error if source is not a string.
Example:
(cl-cc/php:tokenize-php-source "<?php $x = 1;")
;; => ((:type :T-OPEN-TAG :value nil) (:type :T-VARIABLE :value "x")
;; ...
;; (:type :T-EOF :value nil))
See also: Getting Started
parse-php-source¶
Parses a PHP source string into cl-cc AST nodes. This is the primary entry
point, and is analogous to parse-all-forms for Common Lisp.
source is a string containing PHP source, including the opening <?php tag.
Returns: a list of top-level cl-cc AST nodes.
Signals: parser errors on malformed input; type-error if source is not a
string.
Example:
See also: Core Concepts
parse-php-source-to-cst¶
Parses a PHP source string into concrete syntax tree nodes, preserving surface
structure that the AST discards. Use this for formatters, linters, and
source-to-source rewrites; use parse-php-source when you intend to compile.
| Argument | Type | Default | Meaning |
|---|---|---|---|
source |
string |
— | PHP source text |
source-file |
string or nil |
nil |
Path recorded on the token stream, used in diagnostics |
Returns: two values. The first is the list of CST nodes; the second is the list of diagnostics collected during the parse.
Signals: type-error if source is not a string.
Example:
(cl-cc/php:parse-php-source-to-cst "<?php if ($a) { b(); }" "example.php")
;; => (values (#<php-cst-if ...>) nil)
See also: Recipes
php-check-supported-forms¶
Walks an AST and signals an error on any construct the frontend does not support, so that unsupported input fails at the frontend rather than deeper in the compiler pipeline.
forms is a list of AST nodes, as returned by parse-php-source.
Returns: nil. This is called for effect.
Signals: an AST error naming the offending form, for unsupported calls and unsupported class-like declarations.
Example:
See also: Compatibility
Attributes¶
PHP 8 attributes (#[...]) are modelled as a struct with parsing helpers.
| Symbol | Role |
|---|---|
php-attribute |
Struct type |
make-php-attribute |
Constructor |
php-attribute-name |
Accessor: attribute name |
php-attribute-args |
Accessor: argument list |
php-attribute-target-type |
Accessor: declaration the attribute is attached to |
%php-parse-attributes |
Parse a run of attribute groups |
%php-parse-attribute-group |
Parse one #[...] group |
%php-parse-attribute |
Parse a single attribute within a group |
%php-skip-attributes |
Advance past attributes without building them |
Registries¶
| Symbol | Role |
|---|---|
*php-trait-registry* |
Traits collected during parsing |
*php-interface-registry* |
Interfaces collected during parsing |
%php-parse-trait-decl |
Parse a trait declaration |
%php-parse-use-trait-stmt |
Parse a use statement inside a class body |
%php-parse-interface-decl |
Parse an interface declaration |
Runtime builtins¶
Called by generated code
These implement PHP semantics for compiled output. Treat them as a compilation target, not as a convenience library. Their contract is that of the PHP construct they name.
Values and coercion: +php-null+, %php-null-p, %php-truthy,
%php-to-number, %php-stringify, %php-value-type, %php-isset.
+php-null+ is a dedicated sentinel, distinct from nil, because PHP
distinguishes null from false and from the empty array. Passing Lisp nil where
PHP null is meant gives wrong results in loose comparisons.
Comparison: %php-eq-loose implements ==, %php-eq-strict implements ===,
and %php-spaceship implements <=>.
Arithmetic and bitwise: %php-modulo, %php-shift-left, %php-shift-right,
%php-bitwise-and, %php-bitwise-or, %php-bitwise-xor, %php-bitwise-not.
These follow PHP's semantics, not Common Lisp's — notably for negative operands
and for the coercion applied to non-integer arguments.
Strings: %php-concat, %php-strlen, %php-strtolower, %php-strtoupper. The
wider str*, mb_*, preg_*, formatting, encoding, serialization, JSON, and
digest families are reached through the builtin registry rather than through
individual exports.
Arrays: %php-array, %php-array-empty-p, %php-array-ref, %php-array-set,
%php-array-unset, %php-array-key-exists, %php-count, %php-compact,
%php-extract. PHP 8.4 additions: %php-array-first, %php-array-last,
%php-array-find, %php-array-find-key, %php-array-any, %php-array-all.
PHP arrays are ordered maps — neither Lisp lists nor plain hash tables.
Objects: %php-clone, %php-clone-with.
Generators and fibers: %php-yield, %php-yield-from, %php-fiber-make,
%php-fiber-start, %php-fiber-resume, %php-fiber-suspend.
Exceptions: php-exception, %php-throw, %php-make-exception,
%php-exception-object-p, %php-exception-value, %php-exception-matches-p,
%php-get-error-handler.
Enums: %php-enum-make-case, %php-enum-cases, %php-enum-case-list,
%php-enum-from, %php-enum-try-from, %php-enum-case-value.
%php-enum-try-from returns nil where %php-enum-from signals, matching
PHP's tryFrom/from pair.
Callables: %php-callable-ref, %php-pipe.
Test system¶
run-tests¶
Runs the entire test suite, reporting results to *standard-output* via
cl-weave's :spec reporter.
Returns: t when every test passes.
Signals: an error when any test fails, rather than returning nil, so the
call works directly as a script-level exit gate.
Example:
See also: Development