static-php-py 0.1.4__tar.gz → 0.1.6__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.4 → static_php_py-0.1.6}/PKG-INFO +29 -22
- static_php_py-0.1.6/README.md +122 -0
- static_php_py-0.1.6/docs/concept.md +193 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/docs/design-api.md +53 -36
- static_php_py-0.1.6/docs/design-discovery.md +94 -0
- static_php_py-0.1.6/docs/design-extraction.md +139 -0
- static_php_py-0.1.6/docs/design-modules.md +71 -0
- static_php_py-0.1.6/docs/design-packaged.md +106 -0
- static_php_py-0.1.6/docs/design-providers.md +158 -0
- static_php_py-0.1.6/docs/impl.md +73 -0
- static_php_py-0.1.6/docs/index.md +12 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/pyproject.toml +1 -1
- static_php_py-0.1.6/src/static_php_py/__init__.py +41 -0
- static_php_py-0.1.6/src/static_php_py/_execution.py +115 -0
- static_php_py-0.1.6/src/static_php_py/_manifest.py +85 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/src/static_php_py/_php.py +91 -126
- static_php_py-0.1.6/src/static_php_py/_sources/__init__.py +17 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_cache.py +32 -0
- {static_php_py-0.1.4/src/static_php_py → static_php_py-0.1.6/src/static_php_py/_sources}/_discovery.py +14 -5
- static_php_py-0.1.6/src/static_php_py/_sources/_entrypoints.py +22 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_extraction.py +208 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_integrity.py +67 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_packaged.py +268 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_path.py +113 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_publishing.py +44 -0
- static_php_py-0.1.6/src/static_php_py/_sources/_remote.py +214 -0
- static_php_py-0.1.6/src/static_php_py/_version.py +27 -0
- static_php_py-0.1.6/src/static_php_py/py.typed +0 -0
- static_php_py-0.1.6/tests/_sources/conftest.py +104 -0
- static_php_py-0.1.6/tests/_sources/test_cache.py +52 -0
- {static_php_py-0.1.4/tests → static_php_py-0.1.6/tests/_sources}/test_discovery.py +30 -18
- static_php_py-0.1.6/tests/_sources/test_entrypoints.py +63 -0
- static_php_py-0.1.6/tests/_sources/test_integrity.py +96 -0
- static_php_py-0.1.6/tests/_sources/test_packaged.py +291 -0
- static_php_py-0.1.6/tests/_sources/test_packaged_selection.py +195 -0
- static_php_py-0.1.4/tests/test_providers_path.py → static_php_py-0.1.6/tests/_sources/test_path.py +9 -60
- static_php_py-0.1.6/tests/_sources/test_remote_archive.py +268 -0
- static_php_py-0.1.6/tests/_sources/test_remote_checksum.py +157 -0
- static_php_py-0.1.6/tests/_sources/test_remote_containment.py +151 -0
- static_php_py-0.1.6/tests/_sources/test_remote_download.py +227 -0
- static_php_py-0.1.6/tests/_sources/test_remote_search.py +84 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/tests/test_exceptions.py +22 -5
- static_php_py-0.1.6/tests/test_init.py +48 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/tests/test_integration_exec.py +2 -42
- static_php_py-0.1.6/tests/test_integration_factory.py +50 -0
- static_php_py-0.1.6/tests/test_manifest.py +117 -0
- static_php_py-0.1.6/tests/test_php_exec.py +300 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/tests/test_php_factory.py +79 -35
- {static_php_py-0.1.4 → static_php_py-0.1.6}/tests/test_php_inspect.py +23 -3
- static_php_py-0.1.6/tests/test_php_require.py +163 -0
- static_php_py-0.1.4/tests/test_models.py → static_php_py-0.1.6/tests/test_types.py +20 -15
- static_php_py-0.1.6/tests/test_version_fallback.py +55 -0
- static_php_py-0.1.4/README.md +0 -115
- static_php_py-0.1.4/docs/concept.md +0 -178
- static_php_py-0.1.4/docs/design-providers.md +0 -198
- static_php_py-0.1.4/docs/impl.md +0 -54
- static_php_py-0.1.4/docs/index.md +0 -8
- static_php_py-0.1.4/src/static_php_py/__init__.py +0 -56
- static_php_py-0.1.4/src/static_php_py/_manifest.py +0 -75
- static_php_py-0.1.4/src/static_php_py/_providers.py +0 -274
- static_php_py-0.1.4/tests/test_integration_factory.py +0 -119
- static_php_py-0.1.4/tests/test_manifest.py +0 -93
- static_php_py-0.1.4/tests/test_php_checked.py +0 -130
- static_php_py-0.1.4/tests/test_php_exec.py +0 -156
- static_php_py-0.1.4/tests/test_providers_remote_archive.py +0 -266
- static_php_py-0.1.4/tests/test_providers_remote_download.py +0 -138
- {static_php_py-0.1.4 → static_php_py-0.1.6}/.gitignore +0 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/LICENSE +0 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/src/static_php_py/_exceptions.py +0 -0
- /static_php_py-0.1.4/src/static_php_py/_models.py → /static_php_py-0.1.6/src/static_php_py/_types.py +0 -0
- {static_php_py-0.1.4 → static_php_py-0.1.6}/tests/conftest.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: static-php-py
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.6
|
|
4
4
|
Summary: Python wrapper library for static PHP binaries; code-only execution library
|
|
5
5
|
Project-URL: Homepage, https://github.com/samhsu-dev/static-php-py
|
|
6
6
|
Project-URL: Repository, https://github.com/samhsu-dev/static-php-py
|
|
@@ -384,8 +384,10 @@ The `[bundled]` extra pulls the companion distribution `static-php-py-binary` (i
|
|
|
384
384
|
from static_php_py import PHP
|
|
385
385
|
|
|
386
386
|
php = PHP.bundled() # companion binary (needs [bundled] extra)
|
|
387
|
-
php = PHP.local("/usr/bin/php") # explicit path
|
|
388
|
-
php = PHP.
|
|
387
|
+
php = PHP.local("/usr/bin/php") # explicit path
|
|
388
|
+
php = PHP.system() # first php on the system PATH
|
|
389
|
+
php = PHP.remote("https://example.com/php-8.4.tar.gz", # download + cache
|
|
390
|
+
checksum="sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")
|
|
389
391
|
|
|
390
392
|
result = php.run("script.php", args=["--verbose"])
|
|
391
393
|
if result.success:
|
|
@@ -403,32 +405,32 @@ if not report.satisfied:
|
|
|
403
405
|
|
|
404
406
|
## Required version and extensions
|
|
405
407
|
|
|
406
|
-
Declare the PHP version and extension set your package needs once, as a `
|
|
407
|
-
|
|
408
|
-
```toml
|
|
409
|
-
[project.entry-points."static_php_py.requirements"]
|
|
410
|
-
manifest = "your_lib._php_requirements"
|
|
411
|
-
```
|
|
408
|
+
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`:
|
|
412
409
|
|
|
413
410
|
```python
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
411
|
+
from static_php_py import PHP, Requirements
|
|
412
|
+
|
|
413
|
+
REQUIREMENTS = Requirements(
|
|
414
|
+
version=">=8.4", # PEP 440 specifier, or None for any
|
|
415
|
+
extensions=frozenset({"tokenizer", "mbstring"}),
|
|
416
|
+
)
|
|
417
|
+
|
|
418
|
+
php = PHP.bundled().require(REQUIREMENTS)
|
|
417
419
|
```
|
|
418
420
|
|
|
419
|
-
|
|
421
|
+
`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.
|
|
420
422
|
|
|
421
423
|
## Self-managed binary
|
|
422
424
|
|
|
423
|
-
A library that needs a fixed extension set ships its own
|
|
425
|
+
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:
|
|
424
426
|
|
|
425
427
|
```python
|
|
426
|
-
from
|
|
427
|
-
|
|
428
|
+
from static_php_py import PHP, PackagedBinary
|
|
429
|
+
|
|
430
|
+
_BINARY = PackagedBinary(package="your_lib", series="8.4")
|
|
428
431
|
|
|
429
432
|
def php() -> PHP:
|
|
430
|
-
|
|
431
|
-
return PHP.local(binary)
|
|
433
|
+
return PHP.local(_BINARY.resolve())
|
|
432
434
|
```
|
|
433
435
|
|
|
434
436
|
Full CI-to-wheel flow: [`../../docs/llms/bundling-pipeline.md`](../../docs/llms/bundling-pipeline.md).
|
|
@@ -439,15 +441,20 @@ Full CI-to-wheel flow: [`../../docs/llms/bundling-pipeline.md`](../../docs/llms/
|
|
|
439
441
|
|
|
440
442
|
- `PHP` — wrapper bound to one binary.
|
|
441
443
|
- `PHP.bundled() -> PHP` — companion binary; raises `BinaryNotFoundError` naming the `[bundled]` extra when the companion is absent.
|
|
442
|
-
- `PHP.local(path: Path | str) -> PHP` — explicit path
|
|
443
|
-
- `PHP.
|
|
444
|
+
- `PHP.local(path: Path | str) -> PHP` — explicit path.
|
|
445
|
+
- `PHP.system() -> PHP` — first `php` executable on the system PATH.
|
|
446
|
+
- `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.
|
|
444
447
|
- `PHP.cache_dir() -> Path` — platform-specific download cache directory.
|
|
445
|
-
- `
|
|
446
|
-
- `
|
|
448
|
+
- `require(requirements: Requirements) -> PHP` — check the binary against a declaration; probes only declared parts; returns self.
|
|
449
|
+
- `run(script, args=None, *, input=None, ini=None, timeout=None) -> ExecutionResult` — `input` feeds stdin; `ini` maps to `-d key=value` options.
|
|
450
|
+
- `eval(code, *, input=None, ini=None, timeout=None) -> ExecutionResult` — same `input`/`ini` semantics as `run`.
|
|
447
451
|
- `version() -> str`
|
|
448
452
|
- `extensions() -> frozenset[str]` — loaded extensions via `php -m`, lowercased.
|
|
449
453
|
- `check_extensions(required) -> ExtensionReport` — pure inspection; no download or build.
|
|
450
454
|
- `path` (property) `-> Path`
|
|
455
|
+
- `Requirements(version: str | None = None, extensions: frozenset[str] = frozenset())` — frozen declaration of the needed PHP version (PEP 440 specifier) and extension set.
|
|
456
|
+
- `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.
|
|
457
|
+
- `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`.
|
|
451
458
|
- `ExecutionResult` — frozen data holder: `return_code`, `stdout`, `stderr`, `success`.
|
|
452
459
|
- `ExtensionReport` — frozen data holder: `required`, `loaded`, `missing`, `satisfied`.
|
|
453
460
|
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# static-php-py
|
|
2
|
+
|
|
3
|
+
> "static PHP for Python" — a single PHP binary wrapped behind one Python class.
|
|
4
|
+
|
|
5
|
+
Run PHP scripts from Python without a system PHP install, binding one binary from a companion, a path, or a URL.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pip install static-php-py # code-only, bring your own binary
|
|
11
|
+
pip install "static-php-py[bundled]" # also pulls the companion PHP binary
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
The `[bundled]` extra pulls the companion distribution `static-php-py-binary` (internal, exact-pinned — never install it directly), supplying a pre-built PHP 8.4 binary for the host platform.
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
from static_php_py import PHP
|
|
20
|
+
|
|
21
|
+
php = PHP.bundled() # companion binary (needs [bundled] extra)
|
|
22
|
+
php = PHP.local("/usr/bin/php") # explicit path
|
|
23
|
+
php = PHP.system() # first php on the system PATH
|
|
24
|
+
php = PHP.remote("https://example.com/php-8.4.tar.gz", # download + cache
|
|
25
|
+
checksum="sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08")
|
|
26
|
+
|
|
27
|
+
result = php.run("script.php", args=["--verbose"])
|
|
28
|
+
if result.success:
|
|
29
|
+
print(result.stdout)
|
|
30
|
+
else:
|
|
31
|
+
print(f"Error (code {result.return_code}): {result.stderr}")
|
|
32
|
+
|
|
33
|
+
print(php.eval("echo phpversion();").stdout)
|
|
34
|
+
print(php.version())
|
|
35
|
+
|
|
36
|
+
report = php.check_extensions(["tokenizer", "mbstring"])
|
|
37
|
+
if not report.satisfied:
|
|
38
|
+
print(f"Missing: {report.missing}")
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Required version and extensions
|
|
42
|
+
|
|
43
|
+
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`:
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from static_php_py import PHP, Requirements
|
|
47
|
+
|
|
48
|
+
REQUIREMENTS = Requirements(
|
|
49
|
+
version=">=8.4", # PEP 440 specifier, or None for any
|
|
50
|
+
extensions=frozenset({"tokenizer", "mbstring"}),
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
php = PHP.bundled().require(REQUIREMENTS)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
`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.
|
|
57
|
+
|
|
58
|
+
## Self-managed binary
|
|
59
|
+
|
|
60
|
+
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:
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from static_php_py import PHP, PackagedBinary
|
|
64
|
+
|
|
65
|
+
_BINARY = PackagedBinary(package="your_lib", series="8.4")
|
|
66
|
+
|
|
67
|
+
def php() -> PHP:
|
|
68
|
+
return PHP.local(_BINARY.resolve())
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Full CI-to-wheel flow: [`../../docs/llms/bundling-pipeline.md`](../../docs/llms/bundling-pipeline.md).
|
|
72
|
+
|
|
73
|
+
## API
|
|
74
|
+
|
|
75
|
+
### Classes
|
|
76
|
+
|
|
77
|
+
- `PHP` — wrapper bound to one binary.
|
|
78
|
+
- `PHP.bundled() -> PHP` — companion binary; raises `BinaryNotFoundError` naming the `[bundled]` extra when the companion is absent.
|
|
79
|
+
- `PHP.local(path: Path | str) -> PHP` — explicit path.
|
|
80
|
+
- `PHP.system() -> PHP` — first `php` executable on the system PATH.
|
|
81
|
+
- `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.
|
|
82
|
+
- `PHP.cache_dir() -> Path` — platform-specific download cache directory.
|
|
83
|
+
- `require(requirements: Requirements) -> PHP` — check the binary against a declaration; probes only declared parts; returns self.
|
|
84
|
+
- `run(script, args=None, *, input=None, ini=None, timeout=None) -> ExecutionResult` — `input` feeds stdin; `ini` maps to `-d key=value` options.
|
|
85
|
+
- `eval(code, *, input=None, ini=None, timeout=None) -> ExecutionResult` — same `input`/`ini` semantics as `run`.
|
|
86
|
+
- `version() -> str`
|
|
87
|
+
- `extensions() -> frozenset[str]` — loaded extensions via `php -m`, lowercased.
|
|
88
|
+
- `check_extensions(required) -> ExtensionReport` — pure inspection; no download or build.
|
|
89
|
+
- `path` (property) `-> Path`
|
|
90
|
+
- `Requirements(version: str | None = None, extensions: frozenset[str] = frozenset())` — frozen declaration of the needed PHP version (PEP 440 specifier) and extension set.
|
|
91
|
+
- `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.
|
|
92
|
+
- `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`.
|
|
93
|
+
- `ExecutionResult` — frozen data holder: `return_code`, `stdout`, `stderr`, `success`.
|
|
94
|
+
- `ExtensionReport` — frozen data holder: `required`, `loaded`, `missing`, `satisfied`.
|
|
95
|
+
|
|
96
|
+
### Exceptions
|
|
97
|
+
|
|
98
|
+
- `PHPError` — base.
|
|
99
|
+
- `BinaryNotFoundError`, `ExecutionError`, `DownloadError`, `InvalidArchiveError`, `ExtensionUnsatisfiedError`, `VersionUnsatisfiedError`.
|
|
100
|
+
|
|
101
|
+
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).
|
|
102
|
+
|
|
103
|
+
## For Agents
|
|
104
|
+
|
|
105
|
+
Agent-consumable documentation index at [`../../docs/llms.txt`](../../docs/llms.txt) (llmstxt.org format).
|
|
106
|
+
|
|
107
|
+
## Citation
|
|
108
|
+
|
|
109
|
+
If you use this project in academic work, cite our paper. BibTeX (placeholder until the paper is released):
|
|
110
|
+
|
|
111
|
+
```bibtex
|
|
112
|
+
@misc{static_php_py_placeholder,
|
|
113
|
+
title = {{TODO: paper title — not yet released}},
|
|
114
|
+
author = {{TODO: authors}},
|
|
115
|
+
year = {{TODO}},
|
|
116
|
+
note = {Paper not yet released. Citation entry will be updated on publication.}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## License
|
|
121
|
+
|
|
122
|
+
GPL-2.0 — see [LICENSE](LICENSE). Pre-built binaries originate from [static-php-cli](https://github.com/crazywhalecc/static-php-cli).
|
|
@@ -0,0 +1,193 @@
|
|
|
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 is an importable package wrapping one PHP binary behind one class, obtained through one of four named sources; binary production belongs to the separate build library, which shares no code with it and meets it only through a produced binary file on disk, loaded with the local source — directly or resolved first from a consumer-carried Packaged Binary.
|
|
12
|
+
|
|
13
|
+
**Data Flow**
|
|
14
|
+
|
|
15
|
+
- **Inputs:** Optional local binary path, optional remote URL, a consumer-carried platform archive set, the consumer's Requirement Manifest (PHP version and extension set, authored as a typed value in the consumer's code), PHP script paths or code strings, and an optional per-invocation input payload with configuration overrides.
|
|
16
|
+
- **Outputs:** A PHP wrapper bound to one binary; execution results carrying status, exit code, and output streams; a satisfaction verdict for a Requirement Manifest.
|
|
17
|
+
- **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].
|
|
18
|
+
|
|
19
|
+
**Scope Boundaries**
|
|
20
|
+
|
|
21
|
+
- **Owned:** The public wrapper and its four acquisition sources, resolution of consumer-carried Packaged Binaries, the internal provider abstraction, subprocess execution, result modeling, the exception hierarchy, the requirement declaration type, and the explicit satisfaction check.
|
|
22
|
+
- **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.
|
|
23
|
+
- **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.
|
|
24
|
+
- **Distribution:** Three independent distributions, maintained in one repository and versioned independently — the execution library (code-only), the companion package (platform binary), and the build library. Packaging mechanics and the supported-platform set are specified in `design-api.md` and the build library's `design.md` (`../../static-php-build/docs/design.md`).
|
|
25
|
+
|
|
26
|
+
## Concepts
|
|
27
|
+
|
|
28
|
+
**Conceptual Diagram**
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
┌────────────────────────────────────────────────────────────┐
|
|
32
|
+
│ Consumer │
|
|
33
|
+
└────────────────────────────────────────────────────────────┘
|
|
34
|
+
│ bundled() │ local(path) │ system() │ remote(url)
|
|
35
|
+
▼ ▼ ▼ ▼
|
|
36
|
+
┌──────────┐ ┌──────────────────────────┐ ┌──────────┐
|
|
37
|
+
│ Resource │ │ Path Provider │ │ Remote │ Binary Source
|
|
38
|
+
│ Provider │ │ explicit path │ PATH scan│ │ Provider │ (where binary
|
|
39
|
+
└────┬─────┘ └────────────┬─────────────┘ └────┬─────┘ comes from)
|
|
40
|
+
entry point │ ▲ └─────────┬───────────┘
|
|
41
|
+
┌───────────┴──────┐ │ resolved path ▼
|
|
42
|
+
│ Companion Package│ │ ┌─────────────┐
|
|
43
|
+
│ (binary + tgz + │ Packaged │ PHP wrapper │
|
|
44
|
+
│ Resource logic) │ Binary └──────┬──────┘
|
|
45
|
+
└──────────────────┘ Provider (consumer- │
|
|
46
|
+
consumer-authored carried tgz set) │ reported version + loaded extensions
|
|
47
|
+
version + extensions ▼
|
|
48
|
+
│ ┌─────────────┐
|
|
49
|
+
└──► Manifest ──►│ Requirement │ orthogonal gate, invoked
|
|
50
|
+
│ Check │ explicitly by the consumer
|
|
51
|
+
└──────┬──────┘ (read-only; no build, no download)
|
|
52
|
+
satisfied │ unsatisfied
|
|
53
|
+
┌────────────┴────────────┐
|
|
54
|
+
▼ ▼
|
|
55
|
+
┌─────────────────────────┐ fail fast: report unmet
|
|
56
|
+
│ run / eval │ need + the build library
|
|
57
|
+
│ (payload, overrides) │
|
|
58
|
+
│ → Result │
|
|
59
|
+
└─────────────────────────┘
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Core Concepts**
|
|
63
|
+
|
|
64
|
+
**PHP Wrapper**
|
|
65
|
+
- **Definition:** A handle to one resolved PHP binary that executes scripts and code.
|
|
66
|
+
- **Scope:** The single public entry point for all execution.
|
|
67
|
+
- **Relationships:** Constructed by a Binary Source; produces an Execution Result for each run.
|
|
68
|
+
|
|
69
|
+
**Binary Source**
|
|
70
|
+
- **Definition:** A named way to obtain a PHP Wrapper — bundled, local, system, or remote.
|
|
71
|
+
- **Scope:** Selection of where the binary comes from; one source binds one wrapper.
|
|
72
|
+
- **Relationships:** Each source delegates to one Binary Provider. The Requirement Check accepts the wrapper any source produces.
|
|
73
|
+
|
|
74
|
+
**Bundled Source**
|
|
75
|
+
- **Definition:** Obtains the PHP binary supplied by the Companion Package, discovered at runtime through an entry point.
|
|
76
|
+
- **Scope:** Self-contained deployments where the companion package is installed via the `[bundled]` extra.
|
|
77
|
+
- **Relationships:** Backed by the Resource Provider, which lives in the Companion Package. Absent the companion, the source reports a missing-binary error.
|
|
78
|
+
|
|
79
|
+
**Local Source**
|
|
80
|
+
- **Definition:** Obtains a PHP binary from an explicit filesystem path.
|
|
81
|
+
- **Scope:** Environments with a custom PHP installation, and consumers loading a binary they produced with the build library or resolved from a Packaged Binary.
|
|
82
|
+
- **Relationships:** Backed by the Path Provider. This is the source a consuming library uses to load its own carried binary.
|
|
83
|
+
|
|
84
|
+
**System Source**
|
|
85
|
+
- **Definition:** Obtains the PHP binary found on the system PATH.
|
|
86
|
+
- **Scope:** Environments relying on an existing PHP installation without naming its location; the fallback tier of a consuming library's resolution chain.
|
|
87
|
+
- **Relationships:** Backed by the Path Provider in its search mode.
|
|
88
|
+
|
|
89
|
+
**Remote Source**
|
|
90
|
+
- **Definition:** Obtains a PHP binary by downloading it from a URL, extracting an archive when needed.
|
|
91
|
+
- **Scope:** Acquiring a specific build from a network location, with local caching.
|
|
92
|
+
- **Relationships:** Backed by the Remote Provider.
|
|
93
|
+
|
|
94
|
+
**Binary Provider**
|
|
95
|
+
- **Definition:** An internal strategy that resolves and returns a usable PHP binary.
|
|
96
|
+
- **Scope:** Hidden acquisition logic shared behind a common resolve contract.
|
|
97
|
+
- **Relationships:** Realized by the Resource, Path, and Remote providers.
|
|
98
|
+
|
|
99
|
+
**Companion Package**
|
|
100
|
+
- **Definition:** A separate, data-only distribution carrying the platform PHP binary and the logic that locates it; it holds no public Python API.
|
|
101
|
+
- **Scope:** Pulled in by the `[bundled]` extra of the execution library; one platform wheel per supported host.
|
|
102
|
+
- **Relationships:** Registers the single entry point the Bundled Source discovers; supplies the binary the Bundled Source returns. The discovery group is reserved for the companion — more than one registration is reported as an environment misconfiguration, never resolved by picking one.
|
|
103
|
+
|
|
104
|
+
**Packaged Binary**
|
|
105
|
+
- **Definition:** A consumer-carried platform archive set from which the library extracts the host's PHP binary on first use.
|
|
106
|
+
- **Scope:** Consuming libraries shipping their own binary as package data; archive naming follows the build library's platform-archive contract.
|
|
107
|
+
- **Relationships:** Resolved by the library's public provider into a path bound through the Local Source; mirrors the Companion Package's carrying pattern without sharing code with it.
|
|
108
|
+
|
|
109
|
+
**Execution Result**
|
|
110
|
+
- **Definition:** The outcome of one PHP invocation — success flag, exit code, and captured output.
|
|
111
|
+
- **Scope:** Every script run and code evaluation.
|
|
112
|
+
- **Relationships:** Produced by the PHP Wrapper; consumed by caller code.
|
|
113
|
+
|
|
114
|
+
**Required Extension Set**
|
|
115
|
+
- **Definition:** The set of PHP extension names a consumer declares as needed for its scripts.
|
|
116
|
+
- **Scope:** A consumer's stated dependency on PHP capabilities; independent of how the binary is obtained. Part of the Requirement Manifest.
|
|
117
|
+
- **Relationships:** Checked against a wrapper's loaded extensions; an unsatisfied set is reported with guidance to use the build library.
|
|
118
|
+
|
|
119
|
+
**Requirement Manifest**
|
|
120
|
+
- **Definition:** A consumer's declared PHP requirements — a version constraint and a Required Extension Set — authored once as a typed value in the consumer's own code.
|
|
121
|
+
- **Scope:** A per-consumer constraint owned by that consumer alone. Each consumer applies its own manifest to the wrappers it obtains; manifests of co-installed consumers never merge or interact.
|
|
122
|
+
- **Relationships:** Constructed and held by the consumer; passed to the Requirement Check; the same declaration drives the build library's extension selection.
|
|
123
|
+
|
|
124
|
+
**Requirement Check**
|
|
125
|
+
- **Definition:** A comparison of a wrapper's reported version and loaded extensions against a Requirement Manifest, yielding a satisfaction verdict and the missing extension names.
|
|
126
|
+
- **Scope:** Read-only inspection; no side effects, no build, no download. Invoked explicitly by the consumer with its own manifest on a wrapper from any source; a wrapper the consumer does not check carries no requirement guarantee. An unsatisfied verdict always fails fast — it never triggers compilation.
|
|
127
|
+
- **Relationships:** Reads a consumer-supplied Requirement Manifest and a PHP Wrapper; on an unsatisfied verdict, reports the unmet need and names the build library.
|
|
128
|
+
|
|
129
|
+
**Exception Family**
|
|
130
|
+
- **Definition:** A typed hierarchy describing how a binary or execution failed, rooted at a common base.
|
|
131
|
+
- **Scope:** All error reporting across sources and execution within the execution library.
|
|
132
|
+
- **Relationships:** Raised by providers and the wrapper. Build-time failures are a separate concern owned by the build library.
|
|
133
|
+
|
|
134
|
+
## Contracts & Flow
|
|
135
|
+
|
|
136
|
+
**Data Contracts**
|
|
137
|
+
|
|
138
|
+
- **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; failures surface as typed exceptions. The wrapper is the consumer's only process channel to PHP; consumers never spawn PHP subprocesses themselves.
|
|
139
|
+
- **With the Consumer Manifest:** The consumer authors one Requirement Manifest as a typed value in its code and passes it explicitly to the Requirement Check for each wrapper it obtains. The manifest binds at the consumer's own call site: co-installed consumers each check against their own manifest, never a merged one. The same declaration is the input the build library reads for extension selection.
|
|
140
|
+
- **With the Companion Package:** When installed via the `[bundled]` extra, the companion registers an entry point exposing a binary-resolution capability; the Bundled Source discovers and uses it. The group holds exactly the companion's registration — more than one registration is reported as an environment misconfiguration. Without the companion, the Bundled Source reports a missing-binary error; the Local and Remote sources are unaffected.
|
|
141
|
+
- **With the Build Library:** The build library produces a binary file on disk. The consumer loads that file through the Local Source — directly, or packaged as the platform archive set a Packaged Binary resolution extracts from. The two libraries share no code and exchange only the produced file and the platform-archive naming contract.
|
|
142
|
+
|
|
143
|
+
**Internal Processing Flow**
|
|
144
|
+
|
|
145
|
+
1. **Source Selection** — Consumer chooses the bundled, local, system, or remote source; a consuming library carrying its own binary first resolves it as a Packaged Binary, then uses the local source.
|
|
146
|
+
2. **Provider Resolution** — The chosen source delegates to its provider to produce a binary path; the host platform is resolved automatically. The bundled source resolves through the companion package's entry point.
|
|
147
|
+
3. **Wrapper Construction** — The resolved path is bound into a PHP Wrapper.
|
|
148
|
+
4. **Requirement Check** — The consumer passes its Requirement Manifest to the wrapper's check, which compares the manifest against the wrapper's reported version and loaded extensions, obtaining a verdict and any missing names. A wrapper the consumer does not check is bound unchecked.
|
|
149
|
+
5. **Fail Fast on Shortfall** — On an unsatisfied check, the library raises a typed exception naming the missing extensions and the build library that produces a satisfying binary. No download or compilation occurs during execution.
|
|
150
|
+
6. **Execution** — The consumer runs a script or evaluates code, optionally supplying an input payload and configuration overrides; the wrapper invokes the binary and captures output.
|
|
151
|
+
7. **Result or Error** — Success yields an Execution Result; failure raises a typed exception.
|
|
152
|
+
|
|
153
|
+
## Scenarios
|
|
154
|
+
|
|
155
|
+
**Typical (bundled binary)**
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
**Local and System Sources (boundary)**
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
**Remote Binary (boundary)**
|
|
164
|
+
|
|
165
|
+
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.
|
|
166
|
+
|
|
167
|
+
**Declared Requirements Satisfied (typical)**
|
|
168
|
+
|
|
169
|
+
A consumer package (for example, php-parser-py) 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.
|
|
170
|
+
|
|
171
|
+
**Co-installed Consumers (interaction)**
|
|
172
|
+
|
|
173
|
+
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.
|
|
174
|
+
|
|
175
|
+
**Consuming Library Carries Its Own Binary (interaction)**
|
|
176
|
+
|
|
177
|
+
A consuming library depends on the code-only execution library and, during its own packaging, uses the build library to produce platform archives loading the extensions its manifest declares. 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.
|
|
178
|
+
|
|
179
|
+
**Bundled Source Without Companion (boundary)**
|
|
180
|
+
|
|
181
|
+
A consumer installs the execution library without the `[bundled]` extra and calls the bundled source. The source raises a missing-binary error naming the `[bundled]` extra; the bundled method exists in every installation, but resolves a binary only when the companion is present.
|
|
182
|
+
|
|
183
|
+
**Unsatisfied at Runtime (boundary)**
|
|
184
|
+
|
|
185
|
+
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.
|
|
186
|
+
|
|
187
|
+
**Unchecked Wrapper (boundary)**
|
|
188
|
+
|
|
189
|
+
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.
|
|
190
|
+
|
|
191
|
+
**Execution Failure (interaction)**
|
|
192
|
+
|
|
193
|
+
A script exits non-zero or a download fails. The wrapper returns a result whose success flag is false for a non-zero exit, while acquisition failures raise the matching exception from the Exception Family.
|
|
@@ -1,22 +1,22 @@
|
|
|
1
1
|
# static-php-py Design Specification — Public API
|
|
2
2
|
|
|
3
|
-
Internal providers and the exception hierarchy: see `design-providers.md`. Binary production is a separate distribution; see the build library's `design.md` (`../../static-php-build/docs/design.md`).
|
|
3
|
+
Internal providers and the exception hierarchy: see `design-providers.md`. Companion discovery: see `design-discovery.md`. Module placement: see `design-modules.md`. Binary production is a separate distribution; see the build library's `design.md` (`../../static-php-build/docs/design.md`).
|
|
4
4
|
|
|
5
5
|
## Design Overview
|
|
6
6
|
|
|
7
|
-
**Public symbols** (`static_php_py/__init__.py` `__all__`): `PHP`, `ExecutionResult`, `ExtensionReport`, `PHPError`, `BinaryNotFoundError`, `ExecutionError`, `DownloadError`, `InvalidArchiveError`, `ExtensionUnsatisfiedError`, `VersionUnsatisfiedError`.
|
|
7
|
+
**Public symbols** (`static_php_py/__init__.py` `__all__`): `PHP`, `PackagedBinary`, `Requirements`, `ExecutionResult`, `ExtensionReport`, `PHPError`, `BinaryNotFoundError`, `ExecutionError`, `DownloadError`, `InvalidArchiveError`, `ExtensionUnsatisfiedError`, `VersionUnsatisfiedError`.
|
|
8
8
|
|
|
9
|
-
**Classes**: `PHP`, `ExecutionResult`, `ExtensionReport`
|
|
9
|
+
**Classes**: `PHP`, `ExecutionResult`, `ExtensionReport`; `Requirements` (specified in `design-providers.md`); `PackagedBinary` (specified in `design-packaged.md`)
|
|
10
10
|
|
|
11
|
-
**Internal Classes**: `_PHPProvider` (Protocol), `_PathProvider`, `_RemoteProvider`, `_BundledDiscovery`. The companion-owned `_ResourceProvider` lives in `static-php-py-binary`; see `design-
|
|
11
|
+
**Internal Classes**: `_PHPProvider` (Protocol), `_PathProvider`, `_RemoteProvider`, `_BundledDiscovery`. The companion-owned `_ResourceProvider` lives in `static-php-py-binary`; see `design-discovery.md`.
|
|
12
12
|
|
|
13
|
-
**Relationships**: `PHP.bundled` uses `_BundledDiscovery` (which delegates to the companion's `_ResourceProvider` through an entry point), `PHP.local` uses `_PathProvider
|
|
13
|
+
**Relationships**: `PHP.bundled` uses `_BundledDiscovery` (which delegates to the companion's `_ResourceProvider` through an entry point), `PHP.local` uses `_PathProvider` (explicit path), `PHP.system` uses `_PathProvider` (PATH search), `PHP.remote` uses `_RemoteProvider`, `_PathProvider` and `_RemoteProvider` implement `_PHPProvider`, all factory methods return `PHP`, `PHP.require` applies the Requirement Check against a consumer-supplied `Requirements` and returns the same `PHP`, `PHP.run`/`PHP.eval` return `ExecutionResult`, `PHP.check_extensions` returns `ExtensionReport`, `PackagedBinary.resolve` yields the path a consumer passes to `PHP.local`
|
|
14
14
|
|
|
15
15
|
**Abstract**: `_PHPProvider` (implemented by `_PathProvider`, `_RemoteProvider`)
|
|
16
16
|
|
|
17
|
-
**Dependency roles**: Data holders: `ExecutionResult`, `ExtensionReport`. Orchestrator: `PHP`. Providers: `_PathProvider`, `_RemoteProvider`. Companion discovery: `_BundledDiscovery`.
|
|
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
18
|
|
|
19
|
-
**Distribution**: `static-php-py` is a code-only distribution carrying no binary by default. `PHP.bundled` discovers a PHP binary supplied by the companion distribution `static-php-py-binary` (no public Python API), pulled in by the `[bundled]` extra and registered through an entry point; the method is always present in the public API and raises `BinaryNotFoundError` naming the `[bundled]` extra when the companion is absent. Host compilation lives in the independent `static-php-build` distribution, specified in the build library's `design.md`; `static-php-py` shares no code with it and never imports it.
|
|
19
|
+
**Distribution**: `static-php-py` is a code-only distribution carrying no binary by default. `PHP.bundled` discovers a PHP binary supplied by the companion distribution `static-php-py-binary` (no public Python API), pulled in by the `[bundled]` extra and registered through an entry point; the method is always present in the public API and raises `BinaryNotFoundError` naming the `[bundled]` extra when the companion is absent. Host compilation lives in the independent `static-php-build` distribution, specified in the build library's `design.md`; `static-php-py` shares no code with it and never imports it. `PHP.require` applies the Requirement Check to a wrapper against a consumer-supplied `Requirements` and raises `ExtensionUnsatisfiedError` (missing extensions) or `VersionUnsatisfiedError` (violated version constraint) on an unsatisfied check; the never-compile policy is stated in `concept.md`.
|
|
20
20
|
|
|
21
21
|
**Exceptions**: `PHPError` (base), `BinaryNotFoundError` extends `PHPError`, `ExecutionError` extends `PHPError`, `DownloadError` extends `PHPError`, `InvalidArchiveError` extends `PHPError`, `ExtensionUnsatisfiedError` extends `PHPError`, `VersionUnsatisfiedError` extends `PHPError`. Specifications in `design-providers.md`. `ProvisioningError` belongs to the separate build distribution; see the build library's `design.md`.
|
|
22
22
|
|
|
@@ -26,7 +26,7 @@ Internal providers and the exception hierarchy: see `design-providers.md`. Binar
|
|
|
26
26
|
|
|
27
27
|
### PHP Class
|
|
28
28
|
|
|
29
|
-
- **Responsibility**: Represent a PHP binary and execute PHP scripts.
|
|
29
|
+
- **Responsibility**: Represent a PHP binary and execute PHP scripts. The wrapper is the consumer's only process channel to PHP; consumers never spawn PHP subprocesses themselves.
|
|
30
30
|
- **Properties**:
|
|
31
31
|
- `_binary_path: Path` - Path to PHP executable
|
|
32
32
|
- **[\_\_init\_\_(binary_path: Path) -> None]**
|
|
@@ -59,52 +59,53 @@ php = PHP.bundled()
|
|
|
59
59
|
|
|
60
60
|
```python
|
|
61
61
|
from static_php_py import PHP
|
|
62
|
-
from pathlib import Path
|
|
63
62
|
|
|
64
|
-
#
|
|
65
|
-
php = PHP.local("/usr/bin/php")
|
|
66
|
-
|
|
67
|
-
# Load from Path object
|
|
68
|
-
php = PHP.local(Path("/usr/local/bin/php"))
|
|
63
|
+
php = PHP.local("/usr/bin/php") # str or Path
|
|
69
64
|
```
|
|
70
65
|
|
|
71
|
-
- **[
|
|
66
|
+
- **[system() -> PHP]** (Static Method)
|
|
67
|
+
- **Responsibility**: Load the PHP binary supplied by the environment through the system PATH.
|
|
68
|
+
- **Behavior**: Searches the system PATH for a `php` executable and wraps the first match. Which binary is found depends on the host environment; consumers needing a deterministic binary use `local`, `bundled`, or `remote`.
|
|
69
|
+
- **Input**: None
|
|
70
|
+
- **Output**: `PHP` instance wrapping the PATH-found binary.
|
|
71
|
+
- **Raises**: `BinaryNotFoundError` when no `php` executable exists on the system PATH.
|
|
72
|
+
|
|
73
|
+
- **[remote(url: str, \*, force: bool = False, timeout: float = 300.0, checksum: str | None = None) -> PHP]** (Static Method)
|
|
72
74
|
- **Responsibility**: Download PHP binary from remote URL.
|
|
73
|
-
- **Behavior**: Downloads PHP binary from URL to local cache, extracts if archive (tar.gz, tgz, zip), sets execute permission, and returns `PHP` instance.
|
|
74
|
-
- **Input**: `url` - Remote URL to PHP binary or archive, `force` - Force re-download ignoring cache (default: False), `timeout` - Download timeout in seconds (default: 300.0)
|
|
75
|
+
- **Behavior**: Downloads PHP binary from URL to local cache, extracts if archive (tar.gz, tgz, zip), sets execute permission, and returns `PHP` instance. When `checksum` is given, every use of the downloaded artifact is preceded by digest verification, and the cache entry is keyed by URL and checksum together, so a changed checksum addresses a fresh cache entry instead of reusing a stale one. Options are keyword-only. Exception to the 3-parameter rule: `force`, `timeout`, and `checksum` are orthogonal keyword-only options consumed independently by `_RemoteProvider`, not a data clump.
|
|
76
|
+
- **Input**: `url` - Remote URL to PHP binary or archive, `force` - Force re-download ignoring cache (default: False), `timeout` - Download timeout in seconds (default: 300.0), `checksum` - Expected digest of the downloaded artifact as `"<algorithm>:<hexdigest>"` with the algorithm one of sha256, sha384, sha512 (default: None, no verification)
|
|
75
77
|
- **Output**: `PHP` instance wrapping the downloaded binary.
|
|
76
|
-
- **Raises**: `DownloadError` if network/HTTP error occurs
|
|
78
|
+
- **Raises**: `ValueError` when `checksum` is malformed or names an unsupported algorithm (raised before any I/O), `DownloadError` if network/HTTP error occurs or the downloaded artifact does not match `checksum`, `InvalidArchiveError` if archive format invalid or no php executable found.
|
|
77
79
|
- **Example Usage**:
|
|
78
80
|
|
|
79
81
|
```python
|
|
80
82
|
from static_php_py import PHP
|
|
81
83
|
|
|
82
|
-
# Download binary
|
|
83
|
-
php = PHP.remote("https://example.com/php-8.4-cli")
|
|
84
|
-
|
|
85
|
-
# Download and extract archive (tar.gz, tgz, or zip)
|
|
84
|
+
# Download and extract archive (tar.gz, tgz, or zip); direct binary URLs also work
|
|
86
85
|
php = PHP.remote("https://example.com/php-8.4.tar.gz")
|
|
87
|
-
php = PHP.remote("https://example.com/php-8.4.zip")
|
|
88
86
|
|
|
89
87
|
# Force re-download
|
|
90
88
|
php = PHP.remote("https://example.com/php-8.4-cli", force=True)
|
|
89
|
+
|
|
90
|
+
# Verify the download against a published digest
|
|
91
|
+
php = PHP.remote("https://example.com/php-8.4.tar.gz", checksum="sha256:9f86d08...")
|
|
91
92
|
```
|
|
92
93
|
|
|
93
|
-
- **[run(script: Path | str, args: list[str] | None = None, timeout: float | None = None) -> ExecutionResult]**
|
|
94
|
-
- **Behavior**: Execute PHP script file.
|
|
95
|
-
- **Input**: `script` - Path to PHP script, `args` - Script arguments, `timeout` - Execution timeout.
|
|
94
|
+
- **[run(script: Path | str, args: list[str] | None = None, *, input: str | None = None, ini: Mapping[str, str] | None = None, timeout: float | None = None) -> ExecutionResult]**
|
|
95
|
+
- **Behavior**: Execute PHP script file. `ini` entries render as `-d key=value` options placed before the script path (after the script they would land in `$argv`); `input` is delivered as the process's standard-input text.
|
|
96
|
+
- **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.
|
|
96
97
|
- **Output**: ExecutionResult with execution outcome.
|
|
97
|
-
- **Raises**: `FileNotFoundError` if script not found.
|
|
98
|
-
- **[eval(code: str, timeout: float | None = None) -> ExecutionResult]**
|
|
99
|
-
- **Behavior**: Execute PHP code string via php -r.
|
|
100
|
-
- **Input**: `code` - PHP code to execute, `timeout` - Execution timeout.
|
|
98
|
+
- **Raises**: `FileNotFoundError` if script not found. `ExecutionError` on execution timeout or when the binary cannot be launched.
|
|
99
|
+
- **[eval(code: str, *, input: str | None = None, ini: Mapping[str, str] | None = None, timeout: float | None = None) -> ExecutionResult]**
|
|
100
|
+
- **Behavior**: Execute PHP code string via php -r. `ini` entries render as `-d key=value` options placed before `-r`; `input` is delivered as the process's standard-input text.
|
|
101
|
+
- **Input**: `code` - PHP code to execute, `input` - Standard-input text (None inherits the parent's stdin), `ini` - Per-invocation ini overrides, `timeout` - Execution timeout.
|
|
101
102
|
- **Output**: ExecutionResult with execution outcome.
|
|
102
|
-
- **Raises**:
|
|
103
|
+
- **Raises**: `ExecutionError` on execution timeout or when the binary cannot be launched.
|
|
103
104
|
- **[version() -> str]**
|
|
104
|
-
- **Behavior**: Get PHP version string.
|
|
105
|
+
- **Behavior**: Get PHP version string, parsed from the binary's `--version` output in either reported format (`PHP X.Y.Z` or `static-php-cli X.Y.Z`).
|
|
105
106
|
- **Input**: None
|
|
106
107
|
- **Output**: Version string (e.g., "8.3.0").
|
|
107
|
-
- **Raises**:
|
|
108
|
+
- **Raises**: `ExecutionError` when the version query fails or reports an unparseable format.
|
|
108
109
|
- **[path -> Path]** (Property)
|
|
109
110
|
- **Behavior**: Path to the PHP executable.
|
|
110
111
|
- **Output**: Path to PHP executable.
|
|
@@ -134,6 +135,21 @@ print(f"Cache directory: {cache_path}")
|
|
|
134
135
|
- **Input**: `required` - Required extension names.
|
|
135
136
|
- **Output**: `ExtensionReport` carrying the satisfaction verdict and the missing names.
|
|
136
137
|
- **Raises**: `ExecutionError` when the binary cannot report its modules.
|
|
138
|
+
- **[require(requirements: Requirements) -> PHP]**
|
|
139
|
+
- **Responsibility**: Apply the Requirement Check to this wrapper against the consumer's declared requirements.
|
|
140
|
+
- **Behavior**: Probes the binary only for the declared parts — no version read without a version constraint, no module read without required extensions — and returns this wrapper when satisfied, so the call chains onto any factory. Fails fast on a shortfall; never downloads or compiles.
|
|
141
|
+
- **Input**: `requirements` - The consumer's `Requirements` value.
|
|
142
|
+
- **Output**: This `PHP` instance, when satisfied.
|
|
143
|
+
- **Raises**: `VersionUnsatisfiedError` when the reported version violates the constraint or the constraint is not a valid PEP 440 specifier; `ExtensionUnsatisfiedError` when required extensions are missing (message names `static-php-build`); `ExecutionError` when the binary cannot report its version or modules.
|
|
144
|
+
- **Example Usage**:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
from static_php_py import PHP, Requirements
|
|
148
|
+
|
|
149
|
+
REQUIREMENTS = Requirements(version=">=8.4", extensions=frozenset({"tokenizer"}))
|
|
150
|
+
|
|
151
|
+
php = PHP.bundled().require(REQUIREMENTS)
|
|
152
|
+
```
|
|
137
153
|
|
|
138
154
|
- **Example Usage**:
|
|
139
155
|
|
|
@@ -141,15 +157,16 @@ print(f"Cache directory: {cache_path}")
|
|
|
141
157
|
from static_php_py import PHP
|
|
142
158
|
|
|
143
159
|
# Create PHP instance
|
|
144
|
-
php = PHP.bundled() # or PHP.local(
|
|
160
|
+
php = PHP.bundled() # or PHP.local(path), PHP.system(), PHP.remote(url)
|
|
145
161
|
print(php.version())
|
|
146
162
|
print(php.path)
|
|
147
163
|
|
|
148
164
|
# Execute PHP code
|
|
149
165
|
result = php.run("script.php", args=["--verbose"])
|
|
150
|
-
result = php.eval("echo phpversion();")
|
|
166
|
+
result = php.eval("echo phpversion();", ini={"memory_limit": "256M"})
|
|
167
|
+
result = php.eval("echo stream_get_contents(STDIN);", input="payload")
|
|
151
168
|
|
|
152
|
-
# Inspect extensions
|
|
169
|
+
# Inspect extensions without raising (require() runs the same comparison as a gate)
|
|
153
170
|
report = php.check_extensions(["tokenizer", "mbstring"])
|
|
154
171
|
if not report.satisfied:
|
|
155
172
|
print(f"Missing: {report.missing}")
|