static-php-py 0.1.7__tar.gz → 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {static_php_py-0.1.7 → static_php_py-0.2.1}/PKG-INFO +21 -98
- static_php_py-0.2.1/README.md +48 -0
- static_php_py-0.2.1/docs/concept.md +116 -0
- static_php_py-0.2.1/docs/design-api.md +95 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/docs/design-discovery.md +10 -22
- static_php_py-0.2.1/docs/design-execution.md +84 -0
- static_php_py-0.2.1/docs/design-extraction.md +148 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/docs/design-modules.md +6 -7
- static_php_py-0.2.1/docs/design-packaged.md +73 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/docs/design-providers.md +25 -28
- static_php_py-0.2.1/docs/impl.md +52 -0
- static_php_py-0.2.1/docs/index.md +16 -0
- static_php_py-0.2.1/docs/model.md +54 -0
- static_php_py-0.2.1/docs/spec-archives.md +108 -0
- static_php_py-0.2.1/docs/spec-remote.md +50 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/pyproject.toml +2 -7
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_execution.py +20 -6
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_php.py +2 -1
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_discovery.py +12 -1
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_extraction.py +105 -26
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_packaged.py +5 -4
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_remote.py +54 -6
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/conftest.py +10 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_discovery.py +96 -1
- static_php_py-0.2.1/tests/_sources/test_discovery_cache.py +117 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_packaged.py +42 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_packaged_selection.py +4 -3
- static_php_py-0.2.1/tests/_sources/test_remote_archive.py +542 -0
- static_php_py-0.2.1/tests/_sources/test_remote_containment.py +510 -0
- static_php_py-0.2.1/tests/conftest.py +31 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_inspect.py +13 -0
- static_php_py-0.1.7/README.md +0 -122
- static_php_py-0.1.7/docs/concept.md +0 -193
- static_php_py-0.1.7/docs/design-api.md +0 -210
- static_php_py-0.1.7/docs/design-extraction.md +0 -139
- static_php_py-0.1.7/docs/design-packaged.md +0 -106
- static_php_py-0.1.7/docs/impl.md +0 -73
- static_php_py-0.1.7/docs/index.md +0 -12
- static_php_py-0.1.7/tests/_sources/test_remote_archive.py +0 -268
- static_php_py-0.1.7/tests/_sources/test_remote_containment.py +0 -151
- static_php_py-0.1.7/tests/conftest.py +0 -17
- {static_php_py-0.1.7 → static_php_py-0.2.1}/.gitignore +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/LICENSE +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/__init__.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_exceptions.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_manifest.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/__init__.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_cache.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_integrity.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_path.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_publishing.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_types.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_version.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/py.typed +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_cache.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_integrity.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_path.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_remote_checksum.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_remote_download.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_remote_search.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_exceptions.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_init.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_integration_exec.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_integration_factory.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_manifest.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_exec.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_factory.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_require.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_types.py +0 -0
- {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_version_fallback.py +0 -0
|
@@ -1,10 +1,7 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: static-php-py
|
|
3
|
-
Version: 0.1
|
|
3
|
+
Version: 0.2.1
|
|
4
4
|
Summary: Python wrapper library for static PHP binaries; code-only execution library
|
|
5
|
-
Project-URL: Homepage, https://github.com/samhsu-dev/static-php-py
|
|
6
|
-
Project-URL: Repository, https://github.com/samhsu-dev/static-php-py
|
|
7
|
-
Project-URL: Issues, https://github.com/samhsu-dev/static-php-py/issues
|
|
8
5
|
Author: static-php-py contributors
|
|
9
6
|
License: GNU GENERAL PUBLIC LICENSE
|
|
10
7
|
Version 2, June 1991
|
|
@@ -359,128 +356,54 @@ Requires-Python: >=3.10
|
|
|
359
356
|
Requires-Dist: packaging>=21.0
|
|
360
357
|
Requires-Dist: platformdirs>=4.0.0
|
|
361
358
|
Provides-Extra: bundled
|
|
362
|
-
Requires-Dist: static-php-py-binary==0.
|
|
359
|
+
Requires-Dist: static-php-py-binary==0.2.0; extra == 'bundled'
|
|
363
360
|
Description-Content-Type: text/markdown
|
|
364
361
|
|
|
365
362
|
# static-php-py
|
|
366
363
|
|
|
367
364
|
> "static PHP for Python" — a single PHP binary wrapped behind one Python class.
|
|
368
365
|
|
|
369
|
-
Run PHP scripts
|
|
366
|
+
Run PHP scripts through a binary supplied by a companion, a path, the system PATH, or a URL.
|
|
370
367
|
|
|
371
368
|
## Install
|
|
372
369
|
|
|
370
|
+
Requires Python 3.10 or later.
|
|
371
|
+
|
|
373
372
|
```bash
|
|
374
|
-
pip install static-php-py
|
|
375
|
-
pip install "static-php-py[bundled]" # also pulls the companion PHP binary
|
|
373
|
+
pip install "static-php-py[bundled]"
|
|
376
374
|
```
|
|
377
375
|
|
|
378
|
-
|
|
376
|
+
Companion installation and its exact dependency relationship:
|
|
377
|
+
[distribution contract](docs/design-api.md#design-overview).
|
|
379
378
|
|
|
380
379
|
## Usage
|
|
381
380
|
|
|
382
381
|
```python
|
|
383
382
|
from static_php_py import PHP
|
|
384
383
|
|
|
385
|
-
php = PHP.bundled()
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
php = PHP.remote("https://example.com/php-8.4.tar.gz", # download + cache
|
|
389
|
-
checksum="sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")
|
|
390
|
-
|
|
391
|
-
result = php.run("script.php", args=["--verbose"])
|
|
392
|
-
if result.success:
|
|
393
|
-
print(result.stdout)
|
|
394
|
-
else:
|
|
395
|
-
print(f"Error (code {result.return_code}): {result.stderr}")
|
|
396
|
-
|
|
397
|
-
print(php.eval("echo phpversion();").stdout)
|
|
398
|
-
print(php.version())
|
|
399
|
-
|
|
400
|
-
report = php.check_extensions(["tokenizer", "mbstring"])
|
|
401
|
-
if not report.satisfied:
|
|
402
|
-
print(f"Missing: {report.missing}")
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
## Required version and extensions
|
|
406
|
-
|
|
407
|
-
Declare the PHP version and extension set your package needs once, as a typed `Requirements` constant, and check any bound binary against it with `require`:
|
|
408
|
-
|
|
409
|
-
```python
|
|
410
|
-
from static_php_py import PHP, Requirements
|
|
411
|
-
|
|
412
|
-
REQUIREMENTS = Requirements(
|
|
413
|
-
version=">=8.4", # PEP 440 specifier, or None for any
|
|
414
|
-
extensions=frozenset({"tokenizer", "mbstring"}),
|
|
415
|
-
)
|
|
416
|
-
|
|
417
|
-
php = PHP.bundled().require(REQUIREMENTS)
|
|
418
|
-
```
|
|
419
|
-
|
|
420
|
-
`require` probes only what the declaration states — no version subprocess without a version constraint, no `php -m` without extensions — and returns the same `PHP` for chaining. A violated version constraint raises `VersionUnsatisfiedError`; a missing extension raises `ExtensionUnsatisfiedError`, naming the `static-php-build` tool that produces a satisfying binary. The same constant drives `static-php-build --manifest your_lib:REQUIREMENTS`, so both tools stay in sync from one declaration.
|
|
421
|
-
|
|
422
|
-
## Self-managed binary
|
|
423
|
-
|
|
424
|
-
A library that needs a fixed extension set ships its own binaries as package data and loads the host's one with `PHP.local`, so its end users install nothing and never compile. Build one archive per OS with `static-php-build`, declare the archives (`.tar.gz`/`.tgz`/`.zip`, default directory `your_lib/_resources/`) as package data, and resolve at runtime with `PackagedBinary` — never the system PATH or a user-supplied path. Selection is by name heuristics — the archive whose name carries the host's OS and architecture tokens (and the series, when given) is chosen — so official static-php-cli release names work unrenamed:
|
|
425
|
-
|
|
426
|
-
```python
|
|
427
|
-
from static_php_py import PHP, PackagedBinary
|
|
428
|
-
|
|
429
|
-
_BINARY = PackagedBinary(package="your_lib", series="8.4")
|
|
430
|
-
|
|
431
|
-
def php() -> PHP:
|
|
432
|
-
return PHP.local(_BINARY.resolve())
|
|
384
|
+
php = PHP.bundled()
|
|
385
|
+
result = php.eval("echo PHP_VERSION;")
|
|
386
|
+
print(result.stdout if result.success else result.stderr)
|
|
433
387
|
```
|
|
434
388
|
|
|
435
|
-
Full CI-to-wheel flow: [`../../docs/llms/bundling-pipeline.md`](../../docs/llms/bundling-pipeline.md).
|
|
436
|
-
|
|
437
389
|
## API
|
|
438
390
|
|
|
439
|
-
|
|
391
|
+
- [PHP acquisition](docs/design-api.md#php-class): factories and cache location.
|
|
392
|
+
- [Execution and inspection](docs/design-execution.md): methods, result types and execution errors.
|
|
393
|
+
- [Requirements and PHP.require](docs/design-providers.md#requirements-class-public-static_php_py).
|
|
394
|
+
- [PackagedBinary](docs/design-packaged.md): consumer-carried archive resolver.
|
|
395
|
+
- [Required Extension Set](../../docs/glossary-extensions.md#required-extension-set): extension-name semantics.
|
|
396
|
+
- [Exception classes](docs/design-providers.md#exception-classes).
|
|
440
397
|
|
|
441
|
-
|
|
442
|
-
- `PHP.bundled() -> PHP` — companion binary; raises `BinaryNotFoundError` naming the `[bundled]` extra when the companion is absent.
|
|
443
|
-
- `PHP.local(path: Path | str) -> PHP` — explicit path.
|
|
444
|
-
- `PHP.system() -> PHP` — first `php` executable on the system PATH.
|
|
445
|
-
- `PHP.remote(url: str, *, force: bool = False, timeout: float = 300.0, checksum: str | None = None) -> PHP` — download, extract (`.tar.gz`/`.tgz`/`.zip`), and cache; `checksum` (`"sha256:<hexdigest>"`, also sha384/sha512) verifies the download before use.
|
|
446
|
-
- `PHP.cache_dir() -> Path` — platform-specific download cache directory.
|
|
447
|
-
- `require(requirements: Requirements) -> PHP` — check the binary against a declaration; probes only declared parts; returns self.
|
|
448
|
-
- `run(script, args=None, *, input=None, ini=None, timeout=None) -> ExecutionResult` — `input` feeds stdin; `ini` maps to `-d key=value` options.
|
|
449
|
-
- `eval(code, *, input=None, ini=None, timeout=None) -> ExecutionResult` — same `input`/`ini` semantics as `run`.
|
|
450
|
-
- `version() -> str`
|
|
451
|
-
- `extensions() -> frozenset[str]` — loaded extensions via `php -m`, lowercased.
|
|
452
|
-
- `check_extensions(required) -> ExtensionReport` — pure inspection; no download or build.
|
|
453
|
-
- `path` (property) `-> Path`
|
|
454
|
-
- `Requirements(version: str | None = None, extensions: frozenset[str] = frozenset())` — frozen declaration of the needed PHP version (PEP 440 specifier) and extension set.
|
|
455
|
-
- `PackagedBinary(package: str, series: str | None = None, *, directory: str = "_resources")` — resolver for a consumer-carried platform archive set; `series` narrows selection (None selects across all series), `directory` names the package-relative archive directory.
|
|
456
|
-
- `resolve() -> Path` — select the host's archive by name heuristics (`macos`≈`darwin`, `windows`≈`win`, `x86_64`≈`amd64`, `aarch64`≈`arm64`; a name with no architecture token matches any), extract its PHP binary beside it (once), and return the path; pass the result to `PHP.local`.
|
|
457
|
-
- `ExecutionResult` — frozen data holder: `return_code`, `stdout`, `stderr`, `success`.
|
|
458
|
-
- `ExtensionReport` — frozen data holder: `required`, `loaded`, `missing`, `satisfied`.
|
|
398
|
+
## Documentation
|
|
459
399
|
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
- `PHPError` — base.
|
|
463
|
-
- `BinaryNotFoundError`, `ExecutionError`, `DownloadError`, `InvalidArchiveError`, `ExtensionUnsatisfiedError`, `VersionUnsatisfiedError`.
|
|
464
|
-
|
|
465
|
-
Full design: [`docs/design-api.md`](docs/design-api.md). Concepts: [`docs/concept.md`](docs/concept.md). Doc index: [`docs/index.md`](docs/index.md).
|
|
400
|
+
[Concepts](docs/concept.md), [design index](docs/index.md), and
|
|
401
|
+
[CI-to-wheel workflow](../../docs/bundling.md).
|
|
466
402
|
|
|
467
403
|
## For Agents
|
|
468
404
|
|
|
469
405
|
Agent-consumable documentation index at [`../../docs/llms.txt`](../../docs/llms.txt) (llmstxt.org format).
|
|
470
406
|
|
|
471
|
-
## Citation
|
|
472
|
-
|
|
473
|
-
If you use this project in academic work, cite our paper. BibTeX (placeholder until the paper is released):
|
|
474
|
-
|
|
475
|
-
```bibtex
|
|
476
|
-
@misc{static_php_py_placeholder,
|
|
477
|
-
title = {{TODO: paper title — not yet released}},
|
|
478
|
-
author = {{TODO: authors}},
|
|
479
|
-
year = {{TODO}},
|
|
480
|
-
note = {Paper not yet released. Citation entry will be updated on publication.}
|
|
481
|
-
}
|
|
482
|
-
```
|
|
483
|
-
|
|
484
407
|
## License
|
|
485
408
|
|
|
486
409
|
GPL-2.0 — see [LICENSE](LICENSE). Pre-built binaries originate from [static-php-cli](https://github.com/crazywhalecc/static-php-cli).
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# static-php-py
|
|
2
|
+
|
|
3
|
+
> "static PHP for Python" — a single PHP binary wrapped behind one Python class.
|
|
4
|
+
|
|
5
|
+
Run PHP scripts through a binary supplied by a companion, a path, the system PATH, or a URL.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Requires Python 3.10 or later.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
pip install "static-php-py[bundled]"
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Companion installation and its exact dependency relationship:
|
|
16
|
+
[distribution contract](docs/design-api.md#design-overview).
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
from static_php_py import PHP
|
|
22
|
+
|
|
23
|
+
php = PHP.bundled()
|
|
24
|
+
result = php.eval("echo PHP_VERSION;")
|
|
25
|
+
print(result.stdout if result.success else result.stderr)
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## API
|
|
29
|
+
|
|
30
|
+
- [PHP acquisition](docs/design-api.md#php-class): factories and cache location.
|
|
31
|
+
- [Execution and inspection](docs/design-execution.md): methods, result types and execution errors.
|
|
32
|
+
- [Requirements and PHP.require](docs/design-providers.md#requirements-class-public-static_php_py).
|
|
33
|
+
- [PackagedBinary](docs/design-packaged.md): consumer-carried archive resolver.
|
|
34
|
+
- [Required Extension Set](../../docs/glossary-extensions.md#required-extension-set): extension-name semantics.
|
|
35
|
+
- [Exception classes](docs/design-providers.md#exception-classes).
|
|
36
|
+
|
|
37
|
+
## Documentation
|
|
38
|
+
|
|
39
|
+
[Concepts](docs/concept.md), [design index](docs/index.md), and
|
|
40
|
+
[CI-to-wheel workflow](../../docs/bundling.md).
|
|
41
|
+
|
|
42
|
+
## For Agents
|
|
43
|
+
|
|
44
|
+
Agent-consumable documentation index at [`../../docs/llms.txt`](../../docs/llms.txt) (llmstxt.org format).
|
|
45
|
+
|
|
46
|
+
## License
|
|
47
|
+
|
|
48
|
+
GPL-2.0 — see [LICENSE](LICENSE). Pre-built binaries originate from [static-php-cli](https://github.com/crazywhalecc/static-php-cli).
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# static-php-py: Python Wrapper for Static PHP
|
|
2
|
+
|
|
3
|
+
## Context
|
|
4
|
+
|
|
5
|
+
**Problem Statement**
|
|
6
|
+
|
|
7
|
+
Python developers need to execute PHP scripts programmatically without depending on a system PHP installation. A library is required that wraps a single PHP binary — bundled, local, system, or remote — behind one class with a uniform interface for running scripts and reading their results. When the bound binary lacks a consumer's declared extensions, the library reports the unmet requirement and the tool that produces a satisfying binary; it never compiles during execution.
|
|
8
|
+
|
|
9
|
+
**System Role**
|
|
10
|
+
|
|
11
|
+
The execution library wraps one PHP binary for consumer scripts. Its relation to
|
|
12
|
+
binary production is owned by the [build concept](../../static-php-build/docs/concept.md#data-contracts).
|
|
13
|
+
|
|
14
|
+
**Data Flow**
|
|
15
|
+
|
|
16
|
+
- **Inputs:** Optional local binary path, optional remote URL, a consumer-carried platform archive set, the consumer's [Requirement Manifest](../../../docs/glossary-requirements.md#requirement-manifest), PHP script paths or code strings, and an optional per-invocation input payload with configuration overrides.
|
|
17
|
+
- **Outputs:** A PHP wrapper bound to one binary; execution results carrying status, exit code, and output streams; a satisfaction verdict for a Requirement Manifest.
|
|
18
|
+
- **Connections:** [Consumer Code] → [binary source] → [binary provider] → [PHP wrapper] → [execution result]; [Consumer Code] → [Requirement Manifest] → [requirement check] → satisfaction verdict; [companion package] —entry point→ [bundled source].
|
|
19
|
+
|
|
20
|
+
**Scope Boundaries**
|
|
21
|
+
|
|
22
|
+
- **Owned:** The public wrapper and its four acquisition sources, resolution of a consumer-carried Packaged Binary, the internal provider abstraction, subprocess execution, result modeling, the exception hierarchy, the requirement declaration type, and the explicit satisfaction check.
|
|
23
|
+
- **Not Owned:** Binary production (owned by the separate build library), the bundled binary's bytes and platform-selection logic (owned by the companion package), the PHP compiler toolchain, PHP language internals, and any compilation during script execution.
|
|
24
|
+
- **Transparent to Consumers:** The host platform dimension is resolved automatically; consumer code never branches on operating system or architecture and never maps a platform to a binary.
|
|
25
|
+
- **Distribution:** [Execution-library and companion packaging](design-api.md#design-overview); [build product](../../static-php-build/docs/design.md#packaging).
|
|
26
|
+
|
|
27
|
+
## Concepts
|
|
28
|
+
|
|
29
|
+
**Conceptual Diagram**
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
Consumer ── source selection ── binary path ── wrapper ── invocation result
|
|
33
|
+
Carried platform archives ──── binary path
|
|
34
|
+
Companion package ──────────── binary path
|
|
35
|
+
Consumer declaration ── requirement check ── wrapper use or shortfall
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
**Core Concepts**
|
|
40
|
+
|
|
41
|
+
- **[Packaged Binary](../../../docs/glossary-binaries.md#packaged-binary)**
|
|
42
|
+
- **Role:** Lets a consumer distribute the PHP binaries its scripts require.
|
|
43
|
+
- **Scope:** Consumer package resources; selection follows [archive resolution](spec-archives.md).
|
|
44
|
+
- **Relationships:** Supplies a local executable to the wrapper. The optional companion supplies its own binary through [discovery](design-discovery.md).
|
|
45
|
+
- **[Required Extension Set](../../../docs/glossary-extensions.md#required-extension-set)**
|
|
46
|
+
- **Role:** Identifies the PHP capabilities a consumer needs.
|
|
47
|
+
- **Scope:** Independent of binary acquisition; belongs to the consumer's Requirement Manifest.
|
|
48
|
+
- **Relationships:** Connects binary production to runtime inspection.
|
|
49
|
+
- **[Requirement Manifest](../../../docs/glossary-requirements.md#requirement-manifest)**
|
|
50
|
+
- **Role:** Gives build-time extension selection and runtime checking one declaration.
|
|
51
|
+
- **Scope:** Each consumer owns and applies its declaration independently.
|
|
52
|
+
- **Relationships:** A consumer checks its chosen binary before relying on its requirements; the build tool reads the declared extension names.
|
|
53
|
+
|
|
54
|
+
Binary acquisition, providers, the wrapper, invocation results and errors are
|
|
55
|
+
software interfaces in [API design](design-api.md), [provider design](design-providers.md)
|
|
56
|
+
and [execution design](design-execution.md).
|
|
57
|
+
A consumer chooses whether to permit a system or supplied-path fallback and
|
|
58
|
+
checks that binary against its own requirements before use.
|
|
59
|
+
|
|
60
|
+
## Contracts & Flow
|
|
61
|
+
|
|
62
|
+
### Data Contracts
|
|
63
|
+
|
|
64
|
+
- **With Consumer Code:** The library exposes one wrapper type reached through four named sources, plus a result type, a satisfaction verdict, and an exception family. Consumers select a source, receive a wrapper, run scripts or code — optionally with an input payload and configuration overrides per invocation — and read typed results; inability to acquire, launch or complete an invocation surfaces as a typed exception. The wrapper is the consumer's only process channel to PHP; consumers never spawn PHP subprocesses themselves.
|
|
65
|
+
- **With the consumer declaration:** Each consumer applies its own Requirement Manifest to the binary it uses. An unchecked wrapper provides no requirement guarantee. Inspection queries the bound interpreter; an unmet requirement raises an error identifying the shortfall and the separate build tool, without downloading or compiling.
|
|
66
|
+
- **With the companion package:** The [companion discovery interface](design-discovery.md) connects its binary to the wrapper.
|
|
67
|
+
- **With the Build Library:** [Shared architecture relationship](../../static-php-build/docs/concept.md#data-contracts).
|
|
68
|
+
|
|
69
|
+
**Internal Processing Flow**
|
|
70
|
+
|
|
71
|
+
[Archive resolution](spec-archives.md) and [remote acquisition](spec-remote.md)
|
|
72
|
+
own acquisition algorithms. [Companion discovery](design-discovery.md),
|
|
73
|
+
[requirement checking](design-providers.md#requirement-check-applied-by-phprequire)
|
|
74
|
+
and [execution](design-execution.md) specify the other interfaces.
|
|
75
|
+
|
|
76
|
+
## Scenarios
|
|
77
|
+
|
|
78
|
+
**Typical (bundled binary)**
|
|
79
|
+
|
|
80
|
+
A developer installs the execution library with the `[bundled]` extra, which pulls in the companion package, and obtains the wrapper through the bundled source without supplying a path. The companion's binary is located through its entry point, the wrapper runs a script, and the result reports success and output.
|
|
81
|
+
|
|
82
|
+
**Local and system sources (boundary)**
|
|
83
|
+
|
|
84
|
+
A developer obtains the wrapper through the local source with an explicit path, which is validated and bound directly. Another developer relies on the system source, which finds PHP on the system PATH or reports a missing binary.
|
|
85
|
+
|
|
86
|
+
**Remote Binary (boundary)**
|
|
87
|
+
|
|
88
|
+
A developer obtains the wrapper through the remote source with a URL to an archive. The remote provider downloads and extracts it, caches the result, and binds the wrapper; later calls reuse the cache unless a forced re-download is requested.
|
|
89
|
+
|
|
90
|
+
**Declared Requirements Satisfied (typical)**
|
|
91
|
+
|
|
92
|
+
A consumer package authors a version constraint and Required Extension Set as one typed value in its code, obtains a wrapper through any source, and passes that value to the requirement check. The check finds the binary sufficient and the consumer proceeds to execution.
|
|
93
|
+
|
|
94
|
+
**Co-installed Consumers (interaction)**
|
|
95
|
+
|
|
96
|
+
Two consuming libraries with different manifests are installed in one environment, each binding its own binary. Each checks its own wrapper against its own manifest; neither library's requirements constrain the other's binary.
|
|
97
|
+
|
|
98
|
+
**Consuming Library Carries Its Own Binary (interaction)**
|
|
99
|
+
|
|
100
|
+
A consuming library depends on the code-only execution library and, during its own packaging, uses the build library to produce one raw binary per target host, then assembles the platform archives in its release process. It places those archives in its own package resources and, at runtime, resolves the host's binary as a Packaged Binary, binds it through the local source, and checks it against its manifest; each invocation pipes its payload through the wrapper instead of a self-managed subprocess. Its end users install only the code-only execution library plus that one carried binary — no redundant bundled binary.
|
|
101
|
+
|
|
102
|
+
**Bundled source without companion (boundary)**
|
|
103
|
+
|
|
104
|
+
A consumer installs the execution library without the `[bundled]` extra and calls the bundled source. The [discovery contract](design-discovery.md) reports the missing companion and identifies how to install it.
|
|
105
|
+
|
|
106
|
+
**Unsatisfied at Runtime (boundary)**
|
|
107
|
+
|
|
108
|
+
A consumer checks a wrapper against a manifest the bound binary cannot meet. The requirement check reports the missing extensions and the library fails fast, naming the build library; no implicit compilation occurs.
|
|
109
|
+
|
|
110
|
+
**Unchecked Wrapper (boundary)**
|
|
111
|
+
|
|
112
|
+
A consumer obtains a wrapper and never invokes the requirement check. The wrapper binds and executes unchecked; requirement guarantees exist only where the consumer applies its manifest.
|
|
113
|
+
|
|
114
|
+
**Execution Failure (interaction)**
|
|
115
|
+
|
|
116
|
+
A script exits with code 7 after printing partial output. The consumer receives an [ExecutionResult](design-execution.md#executionresult-class) and can inspect that output and exit code. A launch failure or timeout instead follows the [execution error contract](design-execution.md#function-specifications).
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# static-php-py Design Specification — Public API
|
|
2
|
+
|
|
3
|
+
Internal providers and errors: [design-providers.md](design-providers.md). Companion discovery: [design-discovery.md](design-discovery.md). Module placement: [design-modules.md](design-modules.md). Build/execution relationship: [build concept](../../static-php-build/docs/concept.md#data-contracts).
|
|
4
|
+
|
|
5
|
+
## Design Overview
|
|
6
|
+
|
|
7
|
+
**Public symbols** (`static_php_py/__init__.py` `__all__`): `PHP`, `PackagedBinary`, `Requirements`, `ExecutionResult`, `ExtensionReport`, `PHPError`, `BinaryNotFoundError`, `ExecutionError`, `DownloadError`, `InvalidArchiveError`, `ExtensionUnsatisfiedError`, `VersionUnsatisfiedError`.
|
|
8
|
+
|
|
9
|
+
**Classes**: `PHP`; result types in [design-execution.md](design-execution.md); `Requirements` (specified in `design-providers.md`); `PackagedBinary` (specified in `design-packaged.md`)
|
|
10
|
+
|
|
11
|
+
**Internal Classes**: `_PHPProvider` (Protocol), `_PathProvider`, `_RemoteProvider`, `_BundledDiscovery`. The companion-owned `_ResourceProvider` lives in `static-php-py-binary`; see `design-discovery.md`.
|
|
12
|
+
|
|
13
|
+
**Relationships**: Factories construct `PHP` through the [provider interfaces](design-providers.md) or [companion discovery](design-discovery.md). Execution/inspection methods and result types are in [design-execution.md](design-execution.md); requirement checking is in [design-providers.md](design-providers.md#requirement-check-applied-by-phprequire). A consumer passes the path from [PackagedBinary](design-packaged.md) to `PHP.local`.
|
|
14
|
+
|
|
15
|
+
**Abstract**: `_PHPProvider` (implemented by `_PathProvider`, `_RemoteProvider`)
|
|
16
|
+
|
|
17
|
+
**Dependency roles**: Data holders: `ExecutionResult`, `ExtensionReport`, `Requirements`. Orchestrator: `PHP`. Providers: `_PathProvider`, `_RemoteProvider`. Companion discovery: `_BundledDiscovery`. The requirement check applied by `PHP.require()`: see `design-providers.md`.
|
|
18
|
+
|
|
19
|
+
**Distribution**: `static-php-py` is code-only. Its optional `[bundled]` extra depends on the internal `static-php-py-binary` companion with an exact version pin; the companion has no public Python API and is installed through that extra. Adopting a companion version updates the extra pin in the same commit; the workspace member version must equal the pin for `uv lock`. Discovery is specified in [design-discovery.md](design-discovery.md), release artifacts in [releasing.md](../../../docs/releasing.md), and the build/execution relationship in the [build concept](../../static-php-build/docs/concept.md#data-contracts).
|
|
20
|
+
|
|
21
|
+
**Exceptions**: [Execution-library error classes](design-providers.md#exception-classes); [build-tool error classes](../../static-php-build/docs/design.md#exception-classes).
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## Class Specifications
|
|
26
|
+
|
|
27
|
+
### PHP Class
|
|
28
|
+
|
|
29
|
+
- **Responsibility**: Represent a PHP binary and execute PHP scripts. Consumer interaction: [concept.md](concept.md#data-contracts).
|
|
30
|
+
- **Properties**:
|
|
31
|
+
- `_binary_path: Path` - Path to PHP executable
|
|
32
|
+
- **[\_\_init\_\_(binary_path: Path) -> None]**
|
|
33
|
+
- **Behavior**: Initialize PHP instance with binary path.
|
|
34
|
+
- **Input**: `binary_path` - Path to PHP executable.
|
|
35
|
+
- **Output**: None
|
|
36
|
+
- **Raises**: None
|
|
37
|
+
- **[bundled() -> PHP]** (Static Method)
|
|
38
|
+
- **Responsibility**: Load the PHP binary supplied by the companion distribution `static-php-py-binary`.
|
|
39
|
+
- **Behavior**: Wrap the path returned by [companion discovery](design-discovery.md#companion-binary-discovery-contract-between-static_php_py-and-static-php-py-binary). The method is present in every installation.
|
|
40
|
+
- **Input**: None
|
|
41
|
+
- **Output**: `PHP` instance wrapping the companion binary.
|
|
42
|
+
- **Raises**: [Discovery errors](design-discovery.md#companion-binary-discovery-contract-between-static_php_py-and-static-php-py-binary).
|
|
43
|
+
- **[local(path: Path | str) -> PHP]** (Static Method)
|
|
44
|
+
- **Responsibility**: Load PHP binary from local file system path.
|
|
45
|
+
- **Behavior**: Delegate to [_PathProvider](design-providers.md#_pathprovider-class-internal-static_php_py) and wrap its path; this does not inspect PHP requirements.
|
|
46
|
+
- **Input**: `path` - Path to PHP binary.
|
|
47
|
+
- **Output**: `PHP` instance wrapping the local binary.
|
|
48
|
+
- **Raises**: [Path provider input and resolution errors](design-providers.md#_pathprovider-class-internal-static_php_py).
|
|
49
|
+
- **[system() -> PHP]** (Static Method)
|
|
50
|
+
- **Responsibility**: Load the PHP binary supplied by the environment through the system PATH.
|
|
51
|
+
- **Behavior**: Wrap the path returned by [_PathProvider](design-providers.md#_pathprovider-class-internal-static_php_py) in PATH-search mode.
|
|
52
|
+
- **Input**: None
|
|
53
|
+
- **Output**: `PHP` instance wrapping the PATH-found binary.
|
|
54
|
+
- **Raises**: [Path resolution errors](design-providers.md#_pathprovider-class-internal-static_php_py).
|
|
55
|
+
|
|
56
|
+
- **[remote(url: str, \*, force: bool = False, timeout: float = 300.0, checksum: str | None = None) -> PHP]** (Static Method)
|
|
57
|
+
- **Responsibility**: Download PHP binary from remote URL.
|
|
58
|
+
- **Behavior**: Wrap the path returned by [_RemoteProvider](design-providers.md#_remoteprovider-class-internal-static_php_py), whose resolution follows [remote acquisition](spec-remote.md).
|
|
59
|
+
- **Input**: `url` and keyword-only acquisition options, passed to the provider; checksum syntax and accepted algorithms: [digest validation](design-providers.md#_integrity-module-internal-static_php_py).
|
|
60
|
+
- **Output**: `PHP` wrapping the resolved executable.
|
|
61
|
+
- **Raises**: [Remote provider errors](design-providers.md#_remoteprovider-class-internal-static_php_py).
|
|
62
|
+
- Execution and inspection methods: [PHP execution](design-execution.md#php-execution-and-inspection).
|
|
63
|
+
- **[cache_dir() -> Path]** (Static Method)
|
|
64
|
+
- **Responsibility**: Get cache directory path where binaries are stored.
|
|
65
|
+
- **Behavior**: Returns platform-specific user cache directory path.
|
|
66
|
+
- **Input**: None
|
|
67
|
+
- **Output**: Path to cache directory (e.g., `~/.cache/static-php-py/` on Linux).
|
|
68
|
+
- **Raises**: None
|
|
69
|
+
- **[require(requirements: Requirements) -> PHP]**
|
|
70
|
+
- **Responsibility**: Apply the consumer declaration to this wrapper.
|
|
71
|
+
- **Behavior / Input / Output / errors**: [Requirement check](design-providers.md#requirement-check-applied-by-phprequire).
|
|
72
|
+
|
|
73
|
+
## Exception / Error Types
|
|
74
|
+
|
|
75
|
+
[Provider and execution errors](design-providers.md#exception-classes) apply to the corresponding factories.
|
|
76
|
+
|
|
77
|
+
## Caller Examples
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from static_php_py import PHP
|
|
81
|
+
|
|
82
|
+
# Create PHP instance
|
|
83
|
+
php = PHP.bundled() # or PHP.local(path), PHP.system(), PHP.remote(url)
|
|
84
|
+
print(php.version())
|
|
85
|
+
print(php.path)
|
|
86
|
+
|
|
87
|
+
# Execute PHP code
|
|
88
|
+
result = php.eval("echo phpversion();", ini={"memory_limit": "256M"})
|
|
89
|
+
result = php.eval("echo stream_get_contents(STDIN);", input="payload")
|
|
90
|
+
|
|
91
|
+
# Inspect extensions without raising (require() runs the same comparison as a gate)
|
|
92
|
+
report = php.check_extensions(["tokenizer", "mbstring"])
|
|
93
|
+
if not report.satisfied:
|
|
94
|
+
print(f"Missing: {report.missing}")
|
|
95
|
+
```
|
|
@@ -1,13 +1,9 @@
|
|
|
1
1
|
# static-php-py Design Specification — Companion Discovery
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
This document owns the contract by which `PHP.bundled` discovers the companion
|
|
8
|
-
distribution's binary. The companion-owned parts (`_ResourceProvider`, platform
|
|
9
|
-
selection) ship in `static-php-py-binary`, not in `static-php-py`; they are
|
|
10
|
-
specified here because the discovery contract spans both distributions.
|
|
3
|
+
`PHP.bundled` obtains its executable from the companion distribution.
|
|
4
|
+
The companion owns its resource provider and platform selection; the execution
|
|
5
|
+
library owns discovery and error translation. [API](design-api.md),
|
|
6
|
+
[provider errors](design-providers.md#exception-classes) and [module placement](design-modules.md).
|
|
11
7
|
|
|
12
8
|
## Design Overview
|
|
13
9
|
|
|
@@ -53,26 +49,21 @@ companion distribution through an entry point and delegates resolution to it.
|
|
|
53
49
|
|
|
54
50
|
### _ResourceProvider Class (Companion-owned, `static_php_py_binary/_php.py`)
|
|
55
51
|
|
|
56
|
-
|
|
57
|
-
`
|
|
58
|
-
|
|
59
|
-
`InvalidArchiveError` it raises are companion-local classes in the companion's
|
|
60
|
-
`_exceptions.py`, mirroring the execution library's names without a code
|
|
61
|
-
dependency; they derive from `Exception`, not from `PHPError`.
|
|
62
|
-
`_BundledDiscovery` translates them into the execution library's same-named
|
|
63
|
-
`PHPError` subclasses, so `PHP.bundled` failures are catchable as `PHPError`.
|
|
52
|
+
The provider's local `BinaryNotFoundError` and `InvalidArchiveError` derive
|
|
53
|
+
from `Exception`. Translation into the execution library's errors belongs to
|
|
54
|
+
[the discovery boundary](#companion-binary-discovery-contract-between-static_php_py-and-static-php-py-binary).
|
|
64
55
|
|
|
65
56
|
- **Responsibility**: Load the PHP binary the companion carries. In a wheel install the binary is pre-extracted; in a source or editable install it is extracted lazily from the bundled platform tar.gz on first use.
|
|
66
57
|
- **[resolve() -> Path]**
|
|
67
58
|
- **Behavior**: Return the pre-extracted binary when present; otherwise extract it from the bundled tar.gz matching the current platform, then set execute permission. The companion carries one platform wheel per supported host, so the matching archive is the host's.
|
|
68
59
|
- **Input**: None
|
|
69
60
|
- **Output**: Path to PHP executable in the companion's resources.
|
|
70
|
-
- **Raises**: `BinaryNotFoundError` if neither the binary nor a matching archive exists, or the platform is unsupported.
|
|
61
|
+
- **Raises**: `BinaryNotFoundError` if neither the binary nor a matching archive exists, or the platform is unsupported; `InvalidArchiveError` if the selected archive is malformed or contains no PHP executable.
|
|
71
62
|
- **[\_extract_platform_binary(target: Path) -> None]**
|
|
72
63
|
- **Behavior**: Extract the current platform's PHP binary from the bundled tar.gz to the target path and set execute permission.
|
|
73
64
|
- **Input**: `target` - Destination path for the extracted binary.
|
|
74
65
|
- **Output**: None
|
|
75
|
-
- **Raises**: `BinaryNotFoundError` if the platform is unsupported or no matching archive exists. `InvalidArchiveError` if the archive contains no PHP executable.
|
|
66
|
+
- **Raises**: `BinaryNotFoundError` if the platform is unsupported or no matching archive exists. `InvalidArchiveError` if the archive is malformed or contains no PHP executable.
|
|
76
67
|
- **[\_archive_path(archive_name: str, target: Path) -> Path]**
|
|
77
68
|
- **Behavior**: Materialize the named platform tar.gz as a real filesystem path.
|
|
78
69
|
- **Input**: `archive_name` - Bundled archive filename. `target` - Destination path named in the error message.
|
|
@@ -88,7 +79,4 @@ dependency; they derive from `Exception`, not from `PHPError`.
|
|
|
88
79
|
- **Input**: `archive` - The opened platform tar.gz.
|
|
89
80
|
- **Output**: A stream over the PHP member, or None when no PHP member exists.
|
|
90
81
|
|
|
91
|
-
|
|
92
|
-
binary, and `platform.machine()` + `sys.platform` to select the host archive. It
|
|
93
|
-
imports nothing from `static_php_py`; the only coupling is the entry-point name
|
|
94
|
-
and the `resolve() -> Path` shape.
|
|
82
|
+
External resource and platform APIs: [impl.md](impl.md#apis).
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# static-php-py execution design
|
|
2
|
+
|
|
3
|
+
## Design Overview
|
|
4
|
+
|
|
5
|
+
- **Classes:** `PHP` execution and inspection methods; `ExecutionResult`, `ExtensionReport` (public, `static_php_py`).
|
|
6
|
+
- **Relationships:** `PHP` delegates process execution and queries to `_execution`; result data lives in `_types`. Acquisition: [design-api.md](design-api.md).
|
|
7
|
+
- **Dependency roles:** Orchestrator: `PHP`. Data holders: `ExecutionResult`, `ExtensionReport`. Internal process functions: `_execution`.
|
|
8
|
+
- **Exceptions:** [execution-library errors](design-providers.md#exception-classes).
|
|
9
|
+
|
|
10
|
+
## Class / Type Specifications
|
|
11
|
+
|
|
12
|
+
### PHP execution and inspection
|
|
13
|
+
|
|
14
|
+
- **[run(script: Path | str, args: list[str] | None = None, *, input: str | None = None, ini: Mapping[str, str] | None = None, timeout: float | None = None) -> ExecutionResult]**
|
|
15
|
+
- **Behavior**: Execute a PHP script through `_execute`, with configuration arguments produced by `_ini_options`; internal contracts are in [Function Specifications](#function-specifications).
|
|
16
|
+
- **Input**: `script` - Path to PHP script, `args` - Script arguments, `input` - Standard-input text (None inherits the parent's stdin), `ini` - Per-invocation ini overrides, `timeout` - Execution timeout.
|
|
17
|
+
- **Output**: ExecutionResult with execution outcome.
|
|
18
|
+
- **Raises**: `FileNotFoundError` if script not found. `ExecutionError` on execution timeout or when the binary cannot be launched.
|
|
19
|
+
- **[eval(code: str, *, input: str | None = None, ini: Mapping[str, str] | None = None, timeout: float | None = None) -> ExecutionResult]**
|
|
20
|
+
- **Behavior**: Execute a PHP code string through `_execute`, with configuration arguments produced by `_ini_options`; internal contracts are in [Function Specifications](#function-specifications).
|
|
21
|
+
- **Input**: `code` - PHP code to execute, `input` - Standard-input text (None inherits the parent's stdin), `ini` - Per-invocation ini overrides, `timeout` - Execution timeout.
|
|
22
|
+
- **Output**: ExecutionResult with execution outcome.
|
|
23
|
+
- **Raises**: `ExecutionError` on execution timeout or when the binary cannot be launched.
|
|
24
|
+
- **[version() -> str]**
|
|
25
|
+
- **Behavior**: Return the version parsed by `_query_version` under [Function Specifications](#function-specifications); external version formats are recorded in [impl.md](impl.md#apis).
|
|
26
|
+
- **Input**: None
|
|
27
|
+
- **Output**: Version string (e.g., "8.3.0").
|
|
28
|
+
- **Raises**: `ExecutionError` when the version query fails or reports an unparseable format.
|
|
29
|
+
- **[path -> Path]** (Property)
|
|
30
|
+
- **Behavior**: Path to the PHP executable.
|
|
31
|
+
- **Output**: Path to PHP executable.
|
|
32
|
+
- **Raises**: None
|
|
33
|
+
- **[extensions() -> frozenset[str]]**
|
|
34
|
+
- **Behavior**: Return the set of extensions loaded by the bound binary, read via `php -m`.
|
|
35
|
+
- **Input**: None
|
|
36
|
+
- **Output**: Loaded extension names under [Required Extension Set semantics](../../../docs/glossary-extensions.md#required-extension-set).
|
|
37
|
+
- **Raises**: `ExecutionError` when the binary cannot report its modules.
|
|
38
|
+
- **[check_extensions(required: Sequence[str]) -> ExtensionReport]**
|
|
39
|
+
- **Behavior**: Compare the bound binary's loaded extensions against the required set; pure inspection with no download or build.
|
|
40
|
+
- **Input**: `required` - Required extension names.
|
|
41
|
+
- **Output**: `ExtensionReport` carrying the satisfaction verdict and the missing names.
|
|
42
|
+
- **Raises**: `ExecutionError` when the binary cannot report its modules.
|
|
43
|
+
|
|
44
|
+
### ExecutionResult Class
|
|
45
|
+
|
|
46
|
+
- **Responsibility**: Represent PHP script execution outcome. Frozen data holder (`@dataclass(frozen=True)`).
|
|
47
|
+
- **Fields**:
|
|
48
|
+
- `return_code: int` - Process exit code
|
|
49
|
+
- `stdout: str` - Standard output
|
|
50
|
+
- `stderr: str` - Standard error
|
|
51
|
+
- **[success -> bool]** (Property)
|
|
52
|
+
- **Behavior**: True when `return_code` is 0.
|
|
53
|
+
- **Output**: Success flag derived from the exit code.
|
|
54
|
+
- **Raises**: None
|
|
55
|
+
- **Example Usage**:
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
result = php.run("script.php")
|
|
59
|
+
if result.success:
|
|
60
|
+
print(result.stdout)
|
|
61
|
+
else:
|
|
62
|
+
print(f"Error: {result.stderr}")
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
### ExtensionReport Class
|
|
68
|
+
|
|
69
|
+
- **Responsibility**: Represent the outcome of an extension-set check. Frozen data holder (`@dataclass(frozen=True)`).
|
|
70
|
+
- **Fields**:
|
|
71
|
+
- `required: frozenset[str]` - Extension names the consumer required
|
|
72
|
+
- `loaded: frozenset[str]` - Extension names the binary loads
|
|
73
|
+
- `missing: frozenset[str]` - Required names absent from `loaded`
|
|
74
|
+
- **[satisfied -> bool]** (Property)
|
|
75
|
+
- **Behavior**: True when `missing` is empty.
|
|
76
|
+
- **Output**: Satisfaction flag derived from the missing set.
|
|
77
|
+
- **Raises**: None
|
|
78
|
+
|
|
79
|
+
## Function Specifications
|
|
80
|
+
|
|
81
|
+
- `_execute(cmd: list[str], timeout: float | None, input: str | None = None) -> ExecutionResult` — run the command using the [subprocess API](impl.md#apis); every completed invocation returns a result, including a nonzero exit. Raise `ExecutionError` on launch failure or timeout.
|
|
82
|
+
- `_ini_options(ini: Mapping[str, str] | None) -> list[str]` — render the [PHP configuration arguments](impl.md#apis), returning an empty argument list for None.
|
|
83
|
+
- `_query_version(binary_path: Path) -> str` — query and parse either [version format](impl.md#apis), returning its numeric version; raise `ExecutionError` on query failure or unparseable output.
|
|
84
|
+
- `_query_modules(binary_path: Path) -> frozenset[str]` — query loaded modules under [Required Extension Set semantics](../../../docs/glossary-extensions.md#required-extension-set); raise `ExecutionError` when the query fails.
|