# sof3/pharynx architecture

> Architecture diagram of the GitHub repository sof3/pharynx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sof3/pharynx
- Repository: https://github.com/sof3/pharynx

## Overview

#### Purpose and entry points
Pharynx is a PHP CLI packager that recompiles PHP sources into a PSR-0-compatible directory tree and optionally a PHAR. Its primary executable flow starts at `pharynx`, dispatches through `src/Main.php`, and is assembled into distributable form by `build.php`.

A companion GitHub Action invokes the tool from `gh-action/action.yml` and `gh-action/src/index.ts`.

#### CLI orchestration
`src/Main.php` owns command execution: parse options, derive input/output settings, invoke source processing, copy requested assets, and choose directory versus PHAR output. `src/Args.php` represents command-line options including source roots, file mappings, output paths, packing, Composer inference, verbosity, and virion antigens.

Key paths: `pharynx`, `src/Main.php`, `src/Args.php`.

#### Source discovery and output assembly
Source roots passed with `-s` (or inferred through `-i` / Composer) are traversed and emitted beneath a configured output source-root path, defaulting to `src`. Explicit `-f NAME:PATH` mappings copy files or directories into named output locations.

`src/Files.php` provides filesystem-level operations used to construct the staged directory output. The staged tree is the boundary between source transformation and final packaging.

Key paths: `src/Files.php`, `src/Main.php`.

#### PHP recompilation pipeline
`src/Processor.php` is the central transformation stage. It processes PHP source files and rewrites them for PSR-0 output semantics rather than simply archiving original files. `src/PhpFile.php` models/processes individual PHP files, while `src/PhpToken.php` supplies token-level parsing/rewrite support.

This pipeline consumes source-root PHP files and produces rewritten files in the staged output tree.

Key paths: `src/Processor.php`, `src/PhpFile.php`, `src/PhpToken.php`.

#### Namespace/class path model
`src/PsrItem.php` represents PSR-oriented source items used by the recompilation logic to map PHP declarations and references into PSR-0-compatible layout. This is the semantic boundary of the packager: PHP code is analyzed and reorganized before PHAR creation.

Key paths: `src/PsrItem.php`, `src/Processor.php`.

#### Virion shading
Optional `-a` antigens trigger dependency shading for PocketMine “virion” libraries. `src/Virion/VirionProcessor.php` is the specialized transformation layer for this operation, integrated into the broader processing pipeline so bundled dependencies avoid naming collisions.

Key paths: `src/Virion/VirionProcessor.php`, `src/Processor.php`, `src/Main.php`.

#### Packaging, runtime, and integrations
The runtime is PHP, with Composer dependency metadata in `composer.json`. Final output can remain a directory (`-o`) or be packed as a PHAR (`-p`), requiring PHP’s PHAR support at execution/build time. Composer mode (`-c`) reads an already-installed project’s Composer context to infer source paths and virion dependencies.

Terminal interaction and verbose reporting are handled by `src/Terminal.php`. The PocketMine plugin-development integration consists of bootstrap and launch wrappers in `plugin-dev/bootstrap-plugin-dev.php`, `plugin-dev/start.sh`, and `plugin-dev/start.cmd`.

Key paths: `src/Terminal.php`, `plugin-dev/bootstrap-plugin-dev.php`, `gh-action/action.yml`.

Main entry points: [`src/Main.php`](https://github.com/sof3/pharynx/blob/master/src/Main.php) (Main), [`src/Processor.php`](https://github.com/sof3/pharynx/blob/master/src/Processor.php) (Processor), [`pharynx`](https://github.com/sof3/pharynx/blob/master/pharynx) (pharynx), [`src/PhpFile.php`](https://github.com/sof3/pharynx/blob/master/src/PhpFile.php) (PhpFile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_entry["pharynx<br/>CLI entrypoint"]
  node_main["Main<br/>command orchestrator<br/>[Main.php]"]
  node_args["Args<br/>option model<br/>[Args.php]"]
  node_terminal["Terminal<br/>console reporting<br/>[Terminal.php]"]
end

subgraph group_transform["Recompilation"]
  node_source_roots["Source roots<br/>PHP input"]
  node_processor["Processor<br/>recompilation pipeline<br/>[Processor.php]"]
  node_php_file["PhpFile<br/>file transformer<br/>[PhpFile.php]"]
  node_php_token["PhpToken<br/>token rewrite support<br/>[PhpToken.php]"]
  node_psr_item["PsrItem<br/>PSR-0 path model<br/>[PsrItem.php]"]
  node_virion["VirionProcessor<br/>dependency shader"]
end

subgraph group_output["Output"]
  node_files["Files<br/>[Files.php]"]
  node_staging[("Staged output tree<br/>directory boundary")]
  node_phar["Directory or PHAR<br/>package artifact"]
  node_build["build.php<br/>distribution build<br/>[build.php]"]
end

subgraph group_integrations["Integrations"]
  node_composer["Composer context<br/>dependency metadata<br/>[composer.json]"]
  node_github_action["GitHub Action<br/>automation wrapper<br/>[action.yml]"]
  node_action_runner["Action runner<br/>TypeScript entrypoint<br/>[index.ts]"]
  node_plugin_dev["Plugin-dev bootstrap<br/>PocketMine wrapper"]
end

node_entry -->|"dispatches"| node_main
node_main -->|"parses"| node_args
node_main -->|"reports through"| node_terminal
node_args -->|"selects"| node_source_roots
node_composer -.->|"infers inputs for -c"| node_args
node_main -->|"invokes"| node_processor
node_source_roots -->|"PHP files"| node_processor
node_processor -->|"processes"| node_php_file
node_php_file -->|"uses"| node_php_token
node_php_file -->|"maps via"| node_psr_item
node_main -.->|"enables with -a"| node_virion
node_virion -->|"integrates shading"| node_processor
node_processor -->|"emits rewritten files"| node_files
node_main -->|"copies -f assets"| node_files
node_files -->|"constructs"| node_staging
node_main -->|"chooses directory or -p"| node_phar
node_staging -->|"packages"| node_phar
node_build -->|"builds distributable"| node_entry
node_github_action -->|"runs"| node_action_runner
node_action_runner -->|"invokes"| node_entry
node_plugin_dev -->|"bootstraps for development"| node_entry

click node_entry "https://github.com/sof3/pharynx/blob/master/pharynx"
click node_main "https://github.com/sof3/pharynx/blob/master/src/Main.php"
click node_args "https://github.com/sof3/pharynx/blob/master/src/Args.php"
click node_terminal "https://github.com/sof3/pharynx/blob/master/src/Terminal.php"
click node_processor "https://github.com/sof3/pharynx/blob/master/src/Processor.php"
click node_php_file "https://github.com/sof3/pharynx/blob/master/src/PhpFile.php"
click node_php_token "https://github.com/sof3/pharynx/blob/master/src/PhpToken.php"
click node_psr_item "https://github.com/sof3/pharynx/blob/master/src/PsrItem.php"
click node_virion "https://github.com/sof3/pharynx/blob/master/src/Virion/VirionProcessor.php"
click node_files "https://github.com/sof3/pharynx/blob/master/src/Files.php"
click node_build "https://github.com/sof3/pharynx/blob/master/build.php"
click node_composer "https://github.com/sof3/pharynx/blob/master/composer.json"
click node_github_action "https://github.com/sof3/pharynx/blob/master/gh-action/action.yml"
click node_action_runner "https://github.com/sof3/pharynx/blob/master/gh-action/src/index.ts"
click node_plugin_dev "https://github.com/sof3/pharynx/blob/master/plugin-dev/bootstrap-plugin-dev.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_main,node_args,node_terminal toneBlue
class node_source_roots,node_processor,node_php_file,node_php_token,node_psr_item,node_virion toneAmber
class node_files,node_staging,node_phar,node_build toneMint
class node_composer,node_github_action,node_action_runner,node_plugin_dev toneRose
```

## Components

### CLI

- [pharynx](https://github.com/sof3/pharynx/blob/master/pharynx): CLI entrypoint · `pharynx`
- [Main](https://github.com/sof3/pharynx/blob/master/src/Main.php): command orchestrator · Coordinates options, processing, assets, and output mode. · `src/Main.php`
- [Args](https://github.com/sof3/pharynx/blob/master/src/Args.php): option model · `src/Args.php`
- [Terminal](https://github.com/sof3/pharynx/blob/master/src/Terminal.php): console reporting · `src/Terminal.php`

### Recompilation

- **Source roots**: PHP input · Explicit, inferred, or Composer-derived source paths.
- [Processor](https://github.com/sof3/pharynx/blob/master/src/Processor.php): recompilation pipeline · Rewrites PHP sources for PSR-0 output semantics. · `src/Processor.php`
- [PhpFile](https://github.com/sof3/pharynx/blob/master/src/PhpFile.php): file transformer · `src/PhpFile.php`
- [PhpToken](https://github.com/sof3/pharynx/blob/master/src/PhpToken.php): token rewrite support · `src/PhpToken.php`
- [PsrItem](https://github.com/sof3/pharynx/blob/master/src/PsrItem.php): PSR-0 path model · Maps declarations and references into PSR-0 layout. · `src/PsrItem.php`
- [VirionProcessor](https://github.com/sof3/pharynx/blob/master/src/Virion/VirionProcessor.php): dependency shader · Optionally shades virion dependencies to prevent collisions. · `src/Virion/VirionProcessor.php`

### Output

- [Files](https://github.com/sof3/pharynx/blob/master/src/Files.php): filesystem assembly · `src/Files.php`
- **Staged output tree**: directory boundary · Rewritten sources and mapped assets are assembled here.
- **Directory or PHAR**: package artifact
- [build.php](https://github.com/sof3/pharynx/blob/master/build.php): distribution build · Assembles the distributable CLI. · `build.php`

### Integrations

- [Composer context](https://github.com/sof3/pharynx/blob/master/composer.json): dependency metadata · Provides inferred source paths and virion dependencies in Composer mode. · `composer.json`
- [GitHub Action](https://github.com/sof3/pharynx/blob/master/gh-action/action.yml): automation wrapper · `gh-action/action.yml`
- [Action runner](https://github.com/sof3/pharynx/blob/master/gh-action/src/index.ts): TypeScript entrypoint · `gh-action/src/index.ts`
- [Plugin-dev bootstrap](https://github.com/sof3/pharynx/blob/master/plugin-dev/bootstrap-plugin-dev.php): PocketMine wrapper · `plugin-dev/bootstrap-plugin-dev.php`

## Connections

- pharynx → Main: dispatches
- Main → Args: parses
- Main → Terminal: reports through
- Args → Source roots: selects
- Composer context → Args: infers inputs for -c
- Main → Processor: invokes
- Source roots → Processor: PHP files
- Processor → PhpFile: processes
- PhpFile → PhpToken: uses
- PhpFile → PsrItem: maps via
- Main → VirionProcessor: enables with -a
- VirionProcessor → Processor: integrates shading
- Processor → Files: emits rewritten files
- Main → Files: copies -f assets
- Files → Staged output tree: constructs
- Main → Directory or PHAR: chooses directory or -p
- Staged output tree → Directory or PHAR: packages
- build.php → pharynx: builds distributable
- GitHub Action → Action runner: runs
- Action runner → pharynx: invokes
- Plugin-dev bootstrap → pharynx: bootstraps for development