Download the PHP package syncfly/python-in-php without Composer

Python packages in PHP

🔥 Fully use artificial intelligence frameworks for AI models inference or training directly in PHP!
You can run AI models with libraries like transformers, torch, vllm, numpy, etc. in your PHP project with PHP syntax.
See syncfly/transformers-torch-php for a quick start with transformers and torch.

System requirements

The library automatically downloads and installs the uv tool and a Python environment on first use. No manual Python installation is required.

Note for Windows users: symlink creation may require Administrator privileges or Developer Mode enabled.

Installation

Answer yes when Composer asks to activate the plugin. This will:

1. Download uv (~10 MB) into vendor/bin/
2. Create a Python virtual environment in vendor/bin/python-in-php/
3. Generate PHPDoc stubs for installed packages in py/

⭐️ Please star the repository to show that there is demand for it, so that you can be sure it will continue to be maintained

Quick start

After installation, Python's standard library is available immediately:

Install additional packages, then use them:

For a complete Python → PHP syntax reference (kwargs, iteration, dicts, context managers, exceptions, and more) see docs/usage.md.

Package manager

The built-in package manager wraps uv pip with Composer integration.

Installed packages and their sources are saved to composer.json under extra.python-in-php.packages with an approximate constraint (e.g. ^2.32.3), while the exact resolved versions are pinned in python-in-php.lock next to composer.lock. On the next composer install packages are re-installed exactly from the lock file; without it they are resolved from the composer.json constraints and the lock file is created. Commit python-in-php.lock to version control to get reproducible installs across machines.

composer pip install --upgrade re-resolves versions within the composer.json constraints and updates only the lock file, mirroring how composer update treats PHP packages.

Running Python

The composer python command runs the project's Python interpreter (the one with your installed packages), runs .py scripts, and manages the Python version:

The script's exit code is propagated. Note that --version/-V is intercepted by Composer itself — use composer python use to see the managed version, or composer python -c "import sys; print(sys.version)".

Manual configuration

In addition to the composer pip commands you can configure Python-in-PHP manually in composer.json:

PyTorch GPU backends

composer pip install torch picks the right PyTorch build for your hardware automatically:

• CUDA for NVIDIA
• ROCm for AMD
• Metal for Apple Silicon
• CPU backend when no GPU is present

To force a specific backend, set the PYTHON_IN_PHP_TORCH_BACKEND environment variable (e.g. cpu, cu128, rocm7.2, or none to disable the default) or pass --torch-backend=... explicitly:

Using Python objects

Python objects are returned as PythonObject instances that support method calls and attribute access:

Python core from PHP

The Py facade exposes Python's exec/eval and its builtins directly — useful for the things PHP has no equivalent for, or handles differently. It starts the Python worker automatically on first use.

See docs/usage.md for the full list of helpers.

Context managers

Use Py::with() to run code inside a Python context manager — the equivalent of Python's with statement. The context is exited afterwards even if the callback throws.

Py::with() returns whatever the callback returns.

PHP callbacks in Python

You can pass a PHP callable as an argument to any Python call. Python receives a callable it can invoke synchronously — the PHP callback runs and its return value is sent back — so functions like map, filter, sorted(key=...) and any API that takes a callback work directly:

The callback may itself call back into Python (re-entrancy), and it can be stored by Python and invoked later:

Most PHP callables are auto-detected as callbacks: a Closure, a first-class callable (strlen(...)), a [$object, 'method'] pair, an invokable object, etc.

ℹ️ Callable strings are not auto-detected. A plain string such as 'strlen' is ambiguous with ordinary string data, so it is passed to Python as a string. To use a named function (or force callback semantics for any value), wrap it in Py::callback():

If an exception is thrown inside the PHP callback, it propagates back to the original caller.

Exceptions

Python exceptions are thrown as Python_In_PHP\PythonException:

AI model example

Or simpler with transformers pipeline:

Troubleshooting

uv download fails / no internet access

The library downloads uv automatically during composer install. If your environment has no internet access, install uv manually before running Composer:

• macOS/Linux: curl -Ls https://astral.sh/uv/install.sh | sh
• Windows: winget install astral-sh.uv

Then set the UV_BIN env variable or ensure uv is in your PATH.

"Class py\xxx not found"

PHPDoc stubs are generated in vendor/syncfly/python-in-php/py/. Run composer install to regenerate them after adding new packages.

"Could not import: …" during stub generation

Some modules can't be imported while their stubs are generated. Expected cases — optional modules that aren't installed, or platform-only modules on the wrong OS — are hidden; the remaining ones are summarized on a single line. Re-run with -v (e.g. composer install -v) to see the full error for each module.

"Python script was not found"

The Python binary symlink is missing. Remove vendor/bin/python-in-php/ and re-run composer install.

Python server does not start within 30 seconds

Check that the Python binary works: vendor/bin/python-in-php/python --version. If it fails, remove the environment and reinstall: rm -rf vendor/bin/python-in-php && composer install.

Permission denied on Windows

Symlink creation requires Administrator privileges or Windows Developer Mode. Run your terminal as Administrator, or enable Developer Mode in Windows Settings → System → Developer options.

License

This project is licensed under the Apache License 2.0.

You are free to use, modify and distribute it, including in commercial projects, provided you retain the copyright notice, state significant changes and include a copy of the license. The license also grants an explicit patent license.

Contributions submitted to this repository are licensed under the same terms.

"SyncFly" and "Python-in-PHP" are trademarks of the project maintainers and are not covered by the Apache License; see TRADEMARKS for what use is permitted without asking.