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.
Files changed (70) hide show
  1. {static_php_py-0.1.7 → static_php_py-0.2.1}/PKG-INFO +21 -98
  2. static_php_py-0.2.1/README.md +48 -0
  3. static_php_py-0.2.1/docs/concept.md +116 -0
  4. static_php_py-0.2.1/docs/design-api.md +95 -0
  5. {static_php_py-0.1.7 → static_php_py-0.2.1}/docs/design-discovery.md +10 -22
  6. static_php_py-0.2.1/docs/design-execution.md +84 -0
  7. static_php_py-0.2.1/docs/design-extraction.md +148 -0
  8. {static_php_py-0.1.7 → static_php_py-0.2.1}/docs/design-modules.md +6 -7
  9. static_php_py-0.2.1/docs/design-packaged.md +73 -0
  10. {static_php_py-0.1.7 → static_php_py-0.2.1}/docs/design-providers.md +25 -28
  11. static_php_py-0.2.1/docs/impl.md +52 -0
  12. static_php_py-0.2.1/docs/index.md +16 -0
  13. static_php_py-0.2.1/docs/model.md +54 -0
  14. static_php_py-0.2.1/docs/spec-archives.md +108 -0
  15. static_php_py-0.2.1/docs/spec-remote.md +50 -0
  16. {static_php_py-0.1.7 → static_php_py-0.2.1}/pyproject.toml +2 -7
  17. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_execution.py +20 -6
  18. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_php.py +2 -1
  19. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_discovery.py +12 -1
  20. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_extraction.py +105 -26
  21. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_packaged.py +5 -4
  22. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_remote.py +54 -6
  23. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/conftest.py +10 -0
  24. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_discovery.py +96 -1
  25. static_php_py-0.2.1/tests/_sources/test_discovery_cache.py +117 -0
  26. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_packaged.py +42 -0
  27. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_packaged_selection.py +4 -3
  28. static_php_py-0.2.1/tests/_sources/test_remote_archive.py +542 -0
  29. static_php_py-0.2.1/tests/_sources/test_remote_containment.py +510 -0
  30. static_php_py-0.2.1/tests/conftest.py +31 -0
  31. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_inspect.py +13 -0
  32. static_php_py-0.1.7/README.md +0 -122
  33. static_php_py-0.1.7/docs/concept.md +0 -193
  34. static_php_py-0.1.7/docs/design-api.md +0 -210
  35. static_php_py-0.1.7/docs/design-extraction.md +0 -139
  36. static_php_py-0.1.7/docs/design-packaged.md +0 -106
  37. static_php_py-0.1.7/docs/impl.md +0 -73
  38. static_php_py-0.1.7/docs/index.md +0 -12
  39. static_php_py-0.1.7/tests/_sources/test_remote_archive.py +0 -268
  40. static_php_py-0.1.7/tests/_sources/test_remote_containment.py +0 -151
  41. static_php_py-0.1.7/tests/conftest.py +0 -17
  42. {static_php_py-0.1.7 → static_php_py-0.2.1}/.gitignore +0 -0
  43. {static_php_py-0.1.7 → static_php_py-0.2.1}/LICENSE +0 -0
  44. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/__init__.py +0 -0
  45. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_exceptions.py +0 -0
  46. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_manifest.py +0 -0
  47. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/__init__.py +0 -0
  48. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_cache.py +0 -0
  49. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_integrity.py +0 -0
  50. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_path.py +0 -0
  51. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_sources/_publishing.py +0 -0
  52. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_types.py +0 -0
  53. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/_version.py +0 -0
  54. {static_php_py-0.1.7 → static_php_py-0.2.1}/src/static_php_py/py.typed +0 -0
  55. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_cache.py +0 -0
  56. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_integrity.py +0 -0
  57. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_path.py +0 -0
  58. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_remote_checksum.py +0 -0
  59. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_remote_download.py +0 -0
  60. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/_sources/test_remote_search.py +0 -0
  61. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_exceptions.py +0 -0
  62. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_init.py +0 -0
  63. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_integration_exec.py +0 -0
  64. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_integration_factory.py +0 -0
  65. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_manifest.py +0 -0
  66. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_exec.py +0 -0
  67. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_factory.py +0 -0
  68. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_php_require.py +0 -0
  69. {static_php_py-0.1.7 → static_php_py-0.2.1}/tests/test_types.py +0 -0
  70. {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.4
1
+ Metadata-Version: 2.5
2
2
  Name: static-php-py
3
- Version: 0.1.7
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.1.5; extra == 'bundled'
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 from Python without a system PHP install, binding one binary from a companion, a path, or a URL.
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 # code-only, bring your own binary
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
- 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.
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() # companion binary (needs [bundled] extra)
386
- php = PHP.local("/usr/bin/php") # explicit path
387
- php = PHP.system() # first php on the system PATH
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
- ### Classes
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
- - `PHP` — wrapper bound to one binary.
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
- ### Exceptions
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
- Public API (`PHP`) and the design overview: see `design-api.md`. Internal
4
- providers and the exception classes named below: see `design-providers.md`.
5
- Module placement: see `design-modules.md`.
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
- This class ships in the companion distribution `static-php-py-binary`, not in
57
- `static-php-py`. It is the object the companion registers in the
58
- `static_php_py.binary` entry-point group. The `BinaryNotFoundError` and
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
- The companion uses `importlib.resources.files()/as_file()` to locate its own
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.