Download the PHP package madeiteasytools/multiverse without Composer
On this page you can find all versions of the php package madeiteasytools/multiverse. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download madeiteasytools/multiverse
More information about madeiteasytools/multiverse
Files in madeiteasytools/multiverse
Package multiverse
Short Description Run trusted Python workers from Laravel with JSON input and output
License MIT
Informations about the package multiverse
MadeItEasyTools/Multiverse ๐
Run trusted Python workers from your Laravel application.
Multiverse connects Laravel to Python for data processing, image handling, machine learning, PDF generation, and other Python workloads. Send JSON from PHP, execute your Python worker, and receive a JSON result.
Python-only direction: Multiverse was originally planned to support multiple programming languages. We have decided to keep the package focused exclusively on Python. Support for other programming languages is no longer planned.
โจ Features
- ๐ Performance Optimized: Sub-500ms execution times via pre-installed environments
- ๐ก๏ธ Robust Error Handling: Custom exceptions with safe failure metadata
- โฑ๏ธ Configurable Timeouts: Prevent hanging workers with flexible timeout options
- ๐ Automatic Logging: Failed workers logged with metadata only
- ๐งน Process Management: Manual cleanup command for zombie processes
- ๐ Python Only: A Laravel integration dedicated to Python workers
- ๐ฆ Shared Dependencies: One
requirements.txtfor all workers - ๐ ๏ธ Artisan Integration:
multiverse:worker,multiverse:install,multiverse:update,multiverse:clear - ๐ Safer Execution: Finite timeouts, bounded I/O, restricted environment inheritance, and advisory code checks
๐ฅ๏ธ Server Requirements
Before installing, ensure your server meets these requirements:
PHP
- PHP 8.2+ and the PHP version required by your Laravel release
proc_openmust not be indisable_functionsinphp.ini
Shared hosting / HestiaCP / cPanel: These panels often disable
proc_openin PHP-FPM pools. You must remove it fromdisable_functionsin your pool config or globalphp.inifor the package to work. See Troubleshooting.
Python
A Python runtime and virtual environment support are required:
| Package | Purpose | Install (Ubuntu/Debian) |
|---|---|---|
python3 (3.8+) |
Python runtime | pre-installed on most servers |
python3-venv |
Virtual environment support | apt install python3.X-venv |
python3-dev |
Python headers (for C extensions) | apt install python3.X-dev |
build-essential |
C/C++ compiler (gcc, g++) |
apt install build-essential |
Replace
Xwith your Python version (e.g.python3.12-venvfor Python 3.12).python3-devandbuild-essentialare only needed if yourrequirements.txtincludes packages that compile from source (e.g.pyswisseph,numpy,Pillow).
Quick check:
๐ฆ Installation
1. Check Server Requirements
Before setting up, verify your server has everything needed:
Example output:
Each failing check prints the exact apt install command to fix it. Returns exit code 1 if any requirement is missing โ useful in CI/CD pipelines.
2. Setup Python Environment
This creates a multiverse/ directory, sets up a virtual environment, and automatically updates your .gitignore.
3. Publish Configuration (Optional)
๐ Quick Start
Create a Worker
Write Your Python Logic
Edit multiverse/python/image_processor/main.py:
Run from Laravel
Upgrading from v2.x to v3.0
Version 3.0 focuses exclusively on Python and includes breaking execution and failure-handling changes.
Move execution controls out of payload data:
Before upgrading:
- Merge the new keys from
config/multiverse.phpinto your application's published config. Use a finite positivetimeoutno greater thanmax_timeout; unlimited timeouts are rejected. - Add required inherited variables to
process.env_allowlistor pass specific trusted variables throughoptions.env. Application secrets are excluded from subprocess environments by default. - Check the input and combined output budgets. Both default to 10 MiB and must be positive integers.
- Create the shared Python virtual environment before running workers. System Python is used only when
python.allow_system_pythonis explicitly enabled. - Catch
WorkerExceptionfor process failures and invalid or scalar JSON output. Do not rely onraw_outputor raw stderr in exceptions; automatic logs contain metadata only. - Keep scripts and symlink targets inside the configured workers directory.
Ordinary two-argument calls with data-only payloads remain valid. See the changelog for the release details.
โ๏ธ Advanced Features
Timeout Configuration
The default timeout is 60 seconds, with a configurable 300-second maximum. Timeouts must be finite and positive; null, zero, negative values, and values above the maximum are rejected.
Pass trusted execution options as the third argument:
Do not pass request data as execution options. The legacy driver and _timeout payload keys are rejected with a migration message. Use driver and timeout in the third argument instead.
Error Handling
Automatic Error Logging
Failed workers are logged to the configured channel using metadata only. Payloads, HTML, stdout, stderr, and raw process exception messages are excluded. WorkerException::getErrorOutput() returns null for failures produced by the manager. Invalid JSON or scalar JSON output throws WorkerException; raw output is never returned on these failures.
Log Entry Example:
Process Cleanup
Kill hanging or zombie worker processes:
Example:
๐ Managing Dependencies
Add Python Packages
-
Edit
multiverse/python/requirements.txt: - Update environment:
Shared Virtual Environment
All Python workers share one virtual environment, saving disk space and installation time.
๐ Security
Multiverse executes trusted application code with the operating-system permissions of the PHP process. It is not a sandbox. A Python virtual environment isolates dependencies, not filesystem access, networking, or OS permissions.
Execution Limits and Environment
Input is rejected before launch when oversized. A process that exceeds its output budget or timeout is stopped. Byte limits must be positive integers. These limits do not impose an OS memory limit or a global concurrency limit, and they do not sandbox child processes started by a worker.
Parent environment variables are removed unless allowlisted. Explicitly provide only the variables a trusted worker needs:
The shared virtual environment must exist. If deliberately using system Python, set python.allow_system_python to true; there is no automatic fallback. Dependency installation and updates use the finite pip_timeout setting. Pin and audit your Python requirements separately.
Worker names and driver names allow only 1 to 128 letters, numbers, underscores, or dashes. Resolved script paths must stay under workers_path, including symlink targets. Keep worker code, dependencies, and parent directories owned by the deployment user and unwritable by web users. Path checks cannot protect code that an attacker can modify concurrently.
Advisory Pattern Checks
security.scan_for_dangerous_code retains the existing substring checks on the entry point. These checks can catch accidental use of listed patterns; they do not inspect imports, prevent obfuscated code, or make untrusted code safe. Do not treat them as a security boundary.
For untrusted workloads, use a separate service or OS/container sandbox with its own user, restricted mounts, network restrictions, resource limits, and process cleanup.
Best Practices
โ
Validate Input: Always validate data before passing to workers
โ
Use Timeouts: Set reasonable timeouts for all workers
โ
Monitor Logs: Check storage/logs for worker failures
โ
Limit Permissions: Run workers with minimal system permissions
โ
Sanitize Output: Validate worker output before using in your app
๐ ๏ธ Artisan Commands
| Command | Description |
|---|---|
multiverse:check --lang=python |
Check server requirements |
multiverse:install --lang=python |
Setup Python environment |
multiverse:update --lang=python |
Update dependencies |
multiverse:worker name --lang=python |
Create a Python worker |
multiverse:run worker |
Run a Python worker manually |
multiverse:clear [worker] |
Kill zombie processes |
๐ Configuration Reference
๐ฏ Use Cases
AI & Machine Learning
Image Processing
Data Science
Web Scraping
๐ Troubleshooting
proc_open Disabled
proc_open is disabled in your PHP configuration. This is common on shared hosting and control panels (HestiaCP, cPanel, Plesk).
Fix โ check what's disabled:
Fix โ global php.ini (affects all sites):
Fix โ per-site PHP-FPM pool (safer, affects only your site):
Edit your pool config (e.g. /etc/php/8.4/fpm/pool.d/yoursite.conf) and add:
Omit proc_open from the list. Note: pool config can only add to the global list, not remove from it โ so proc_open must also be absent from the global php.ini.
python3-venv Not Installed
C Extension Build Fails (Python.h / g++ not found)
Worker Not Found
Solution: Check that multiverse/python/my_worker/main.py exists.
Timeout Issues
Solution: Increase timeout or optimize worker code.
Import Errors
Solution: Add package to requirements.txt and run multiverse:update.
Zombie Processes
Solution: Run php artisan multiverse:clear worker_name.
๐ License
MIT License - see LICENSE.md for details.
๐ค Contributing
Contributions are welcome! Please see CONTRIBUTING.md for details.
๐ Support
- Issues: GitHub Issues
- Email: [email protected]
Made with โค๏ธ by MadeItEasyTools
All versions of multiverse with dependencies
illuminate/support Version ^11.0|^12.0|^13.0
symfony/process Version ^7.0|^8.0