{"id":38893147,"url":"https://github.com/eddmann/phpx","last_synced_at":"2026-01-20T15:01:05.840Z","repository":{"id":332965301,"uuid":"1135749960","full_name":"eddmann/phpx","owner":"eddmann","description":"Run PHP scripts with inline dependencies. Execute Composer tools without global installation. Like npx/uvx for PHP.","archived":false,"fork":false,"pushed_at":"2026-01-16T17:26:44.000Z","size":1596,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-17T23:41:51.386Z","etag":null,"topics":["cli","composer","developer-tools","go","npx","php","static-php"],"latest_commit_sha":null,"homepage":"https://eddmann.com/phpx/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eddmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-16T14:39:27.000Z","updated_at":"2026-01-16T17:26:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eddmann/phpx","commit_stats":null,"previous_names":["eddmann/phpx"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/eddmann/phpx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eddmann","download_url":"https://codeload.github.com/eddmann/phpx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eddmann%2Fphpx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28605915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T14:45:23.139Z","status":"ssl_error","status_checked_at":"2026-01-20T14:44:16.929Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","composer","developer-tools","go","npx","php","static-php"],"created_at":"2026-01-17T14:56:32.318Z","updated_at":"2026-01-20T15:01:05.834Z","avatar_url":"https://github.com/eddmann.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# phpx\n\n![phpx](docs/heading.png)\n\nRun PHP scripts with inline dependencies. Execute Composer tools without global installation.\n\nphpx brings patterns established in other ecosystems to PHP - ephemeral tool execution like [npx](https://docs.npmjs.com/cli/commands/npx) and [uvx](https://docs.astral.sh/uv/guides/tools/), inline script dependencies like [PEP 723](https://peps.python.org/pep-0723/).\n\n## Features\n\n- **Inline dependencies** - declare packages in a `// phpx` comment block, they're installed automatically\n- **Ephemeral tools** - run PHPStan, Psalm, PHP-CS-Fixer without polluting your global environment\n- **Automatic PHP management** - downloads pre-built static PHP binaries matching your version constraints\n- **Smart caching** - PHP binaries, dependencies, and tools are cached for fast subsequent runs\n- **Sandboxing \u0026 isolation** - run scripts in isolated environments with controlled filesystem, network, and resource limits\n\n## Installation\n\n### Homebrew (Recommended)\n\n```bash\nbrew install eddmann/tap/phpx\n```\n\n### Quick Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/eddmann/phpx/main/install.sh | sh\n```\n\n### Download Binary\n\n```bash\n# macOS (Apple Silicon)\ncurl -L https://github.com/eddmann/phpx/releases/latest/download/phpx-macos-arm64 -o phpx\nchmod +x phpx \u0026\u0026 sudo mv phpx /usr/local/bin/\n\n# macOS (Intel)\ncurl -L https://github.com/eddmann/phpx/releases/latest/download/phpx-macos-x64 -o phpx\nchmod +x phpx \u0026\u0026 sudo mv phpx /usr/local/bin/\n\n# Linux (x64)\ncurl -L https://github.com/eddmann/phpx/releases/latest/download/phpx-linux-x64 -o phpx\nchmod +x phpx \u0026\u0026 sudo mv phpx /usr/local/bin/\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/eddmann/phpx\ncd phpx\nmake build-release VERSION=0.1.0\nmake install  # Installs to ~/.local/bin\n```\n\n## Quick Start\n\n**1. Run a simple script**\n\n```bash\nphpx script.php\n```\n\n**2. Add inline dependencies**\n\n```php\n\u003c?php\n// phpx\n// packages = [\"nesbot/carbon:^3.0\"]\n\necho \\Carbon\\Carbon::parse('next friday')-\u003ediffForHumans();\n```\n\n**3. Run it**\n\n```bash\nphpx script.php\n# 6 days from now\n```\n\n**4. Run a tool without installing it**\n\n```bash\nphpx tool phpstan -- analyze src/\n```\n\n**5. Pipe PHP from stdin**\n\n```bash\necho '\u003c?php echo PHP_VERSION;' | phpx run -\n```\n\n## Script Metadata\n\nDeclare dependencies in a `// phpx` comment block at the top of your script:\n\n```php\n\u003c?php\n// phpx\n// php = \"\u003e=8.2\"\n// packages = [\"guzzlehttp/guzzle:^7.0\", \"monolog/monolog:^3.0\"]\n// extensions = [\"intl\"]\n\n// Your code here...\n```\n\n| Field        | Type     | Description                                   |\n| ------------ | -------- | --------------------------------------------- |\n| `php`        | string   | PHP version constraint (semver)               |\n| `packages`   | string[] | Composer packages as `vendor/name:constraint` |\n| `extensions` | string[] | Required PHP extensions                       |\n\n## Shebang Support\n\nMake PHP scripts directly executable:\n\n```php\n#!/usr/bin/env phpx\n\u003c?php\n// phpx\n// packages = [\"nesbot/carbon:^3.0\"]\n\necho \\Carbon\\Carbon::now()-\u003eformat('Y-m-d');\n```\n\n```bash\nchmod +x script.php\n./script.php\n```\n\n## Command Reference\n\n### phpx run\n\nRun a PHP script with inline dependencies.\n\n```bash\nphpx run \u003cscript.php\u003e [-- args...]\nphpx \u003cscript.php\u003e [-- args...]  # Shorthand\n```\n\n| Flag           | Short | Description                               |\n| -------------- | ----- | ----------------------------------------- |\n| `--php`        |       | PHP version constraint (overrides script) |\n| `--packages`   |       | Comma-separated packages to add           |\n| `--extensions` |       | Comma-separated PHP extensions            |\n| `--sandbox`    |       | Enable sandboxing (restricts filesystem)  |\n| `--offline`    |       | Block all network access                  |\n| `--allow-host` |       | Allow network to specific hosts           |\n| `--allow-read` |       | Additional readable paths                 |\n| `--allow-write`|       | Additional writable paths                 |\n| `--allow-env`  |       | Environment variables to pass             |\n| `--memory`     |       | Memory limit in MB (default: 128)         |\n| `--timeout`    |       | Execution timeout in seconds (default: 30)|\n| `--cpu`        |       | CPU time limit in seconds (default: 30)   |\n| `--verbose`    | `-v`  | Show detailed output                      |\n| `--quiet`      | `-q`  | Suppress phpx output                      |\n\n### phpx tool\n\nRun a Composer package's binary without global installation.\n\n```bash\nphpx tool \u003cpackage[@version]\u003e [-- args...]\n```\n\n| Flag           | Short | Description                                |\n| -------------- | ----- | ------------------------------------------ |\n| `--php`        |       | PHP version constraint                     |\n| `--extensions` |       | Comma-separated PHP extensions             |\n| `--from`       |       | Explicit package name when binary differs  |\n| `--sandbox`    |       | Enable sandboxing (restricts filesystem)   |\n| `--offline`    |       | Block all network access                   |\n| `--allow-host` |       | Allow network to specific hosts            |\n| `--allow-read` |       | Additional readable paths                  |\n| `--allow-write`|       | Additional writable paths                  |\n| `--allow-env`  |       | Environment variables to pass              |\n| `--memory`     |       | Memory limit in MB (default: 256)          |\n| `--timeout`    |       | Execution timeout in seconds (default: 300)|\n| `--cpu`        |       | CPU time limit in seconds (default: 300)   |\n| `--verbose`    | `-v`  | Show detailed output                       |\n| `--quiet`      | `-q`  | Suppress phpx output                       |\n\n**Version specifiers:**\n\n- `phpstan` - latest stable\n- `phpstan@1.10.0` - exact version\n- `phpstan:^1.10` - version constraint\n\n**Built-in aliases:**\n\n| Alias          | Package                   |\n| -------------- | ------------------------- |\n| `phpstan`      | phpstan/phpstan           |\n| `psalm`        | vimeo/psalm               |\n| `php-cs-fixer` | friendsofphp/php-cs-fixer |\n| `pint`         | laravel/pint              |\n| `phpunit`      | phpunit/phpunit           |\n| `pest`         | pestphp/pest              |\n| `rector`       | rector/rector             |\n| `phpcs`        | squizlabs/php_codesniffer |\n| `laravel`      | laravel/installer         |\n| `psysh`        | psy/psysh                 |\n\n### phpx cache\n\nManage the phpx cache.\n\n```bash\nphpx cache list              # Show cached items\nphpx cache clean             # Remove tool cache (default)\nphpx cache clean --php       # Remove PHP binaries\nphpx cache clean --deps      # Remove dependencies\nphpx cache clean --index     # Remove version index\nphpx cache clean --all       # Remove everything\nphpx cache dir               # Print cache path\nphpx cache refresh           # Force re-fetch of version index\n```\n\n### phpx version\n\nPrint version information.\n\n## Examples\n\nThe `examples/` directory contains 16 progressive examples demonstrating all phpx features - from basic script execution through inline dependencies, PHP version constraints, extensions, HTTP clients, CLI apps, and sandboxing.\n\n```bash\n# Simple dependency usage\nphpx examples/04-single-package.php\n\n# Full CLI app with Symfony Console\nphpx examples/11-cli-app.php -- --name=World --shout\n\n# Sandboxed execution with resource limits\nphpx examples/12-sandbox-basic.php --sandbox --memory 64 --timeout 10\n\n# Network filtering (allow specific hosts)\nphpx examples/14-sandbox-allow-host.php --allow-host httpbin.org\n```\n\nSee [examples/README.md](examples/README.md) for the complete list and detailed usage instructions.\n\n## How It Works\n\n```\nScript → Parse metadata → Resolve PHP version → Download PHP (if needed)\n                                              → Install dependencies (if needed)\n                                              → Execute script\n```\n\n**PHP binaries** are downloaded from [static-php-cli](https://github.com/crazywhalecc/static-php-cli) - pre-built static PHP binaries with common extensions included. Two tiers are available:\n\n- **Common** - smaller download with standard extensions (curl, gd, redis, mysql, postgres, sqlite, xml, json, mbstring)\n- **Bulk** - larger download with additional extensions (imagick, intl, swoole, opcache, apcu, readline, xsl, event)\n\nThe tier is selected automatically based on required extensions.\n\n**Dependencies** are installed via Composer into content-addressed cache directories at `~/.phpx/deps/{hash}/`.\n\n**Tools** are installed once and cached at `~/.phpx/tools/{package}-{version}/`.\n\n## Security \u0026 Sandboxing\n\nphpx supports running scripts and tools in isolated environments with controlled resource limits.\n\n### Sandbox Modes\n\n**Filesystem sandboxing** (`--sandbox`):\n- macOS: Uses `sandbox-exec` profiles\n- Linux: Uses `bubblewrap` or `nsjail` (if available)\n- Restricts filesystem access to only what the script needs\n\n**Network isolation** (`--offline`, `--allow-host`):\n\n```bash\n# Completely block network access\nphpx run script.php --offline\n\n# Allow only specific hosts\nphpx run script.php --allow-host api.example.com,cdn.example.com\n```\n\n### Resource Limits\n\n```bash\n# Run with 64MB memory, 10 second timeout, 5 second CPU limit\nphpx run script.php --sandbox --memory 64 --timeout 10 --cpu 5\n```\n\n### Filesystem Access\n\n```bash\n# Allow reading from additional paths\nphpx run script.php --sandbox --allow-read /path/to/data\n\n# Allow writing to additional paths\nphpx run script.php --sandbox --allow-write /path/to/output\n```\n\n### Environment Variables\n\nBy default, sandbox mode filters environment variables to avoid leaking secrets. Use `--allow-env` to pass specific variables:\n\n```bash\nphpx run script.php --sandbox --allow-env API_KEY,DEBUG\n```\n\n## Cache Structure\n\n```\n~/.phpx/\n├── php/{version}-{tier}/bin/php        # PHP binaries\n├── deps/{hash}/vendor/                 # Script dependencies\n├── tools/{pkg}-{ver}/vendor/bin/       # Tool installations\n├── composer/{version}/composer.phar    # Composer binaries\n└── index/                              # Version/extension index\n```\n\n## Development\n\n```bash\ngit clone https://github.com/eddmann/phpx\ncd phpx\nmake test                           # Run tests\nmake lint                           # Run linters\nmake build                          # Build binary (dev, with debug symbols)\nmake build-release VERSION=x.x.x    # Build binary (release, optimized)\nmake install                        # Install to ~/.local/bin\n```\n\n## Credits\n\n- [static-php-cli](https://github.com/crazywhalecc/static-php-cli) - Pre-built static PHP binaries\n- [Composer](https://getcomposer.org/) - PHP dependency management\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddmann%2Fphpx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feddmann%2Fphpx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feddmann%2Fphpx/lists"}