omaralalwi / laravel-py
Laravel wrapper for php-py package, to seamless enabling secure and efficient execution of Python scripts within PHP applications.
Requires
- php: ^8.1
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
- omaralalwi/php-py: ^1.0
Requires (Dev)
- orchestra/testbench: ^6.0
- pestphp/pest: ^1.23
- phpunit/phpunit: ^9.0
README
Laravel wrapper for php-py package package, to Seamless enabling secure and efficient execution of Python scripts within Laravel applications without spread multiple applications and or setup API.
๐ Table of Contents
- ๐ง Requirements
- ๐ Installation
- ๐ Quick Start
- โจ Features
- ๐ Changelog
- ๐งช Testing
- ๐ Security
- ๐ค Contributors
- ๐ License
Requirements
- PHP 8.1+ .
- python3 must be installed in server .
Installation ๐ ๏ธ
You can install the package via Composer:
composer require omaralalwi/laravel-py
Publishing Configuration File
php artisan vendor:publish --tag=laravel-py
๐ Quick Start
- ๐ Create a folder for scripts, e.g.,
phpPyScripts
in your project root directory. - ๐ Create a Python script file (
.py
extension) and write Python code. See this script examples. - ๐ง make script file executable,
chmod +x script_file_path
.
โก Easy Usage
<?php use LaravelPy; class LaravelPyController { public function testLaravelPy() { $laravelPy = app(LaravelPy::class); $script = 'total_calculator.py'; $arguments = [10, 20, 30]; try { $result = $laravelPy ->loadScript($script) ->withArguments($arguments) ->run(); print_r($result); // 60.0 } catch (Exception $e) { echo "Error: " . $e->getMessage(); } } }
๐ฅ Advanced Usage
<?php use LaravelPy; use Omaralalwi\PhpPy\Managers\ConfigManager; class LaravelPyController { public function testLaravelPy() { try { $laravelPy = app(LaravelPy::class); $script = 'advance_example.py'; $numbers = [2,4, 5,7,9]; $config = new ConfigManager([ 'scripts_directory' => 'phpPyScripts', 'python_executable' => '/usr/bin/python3', 'max_timeout' => 120, ]); $result = $laravelPy ->setConfig($config) ->loadScript($script) ->withArguments($numbers) ->withEnvironment(['FIRST_ENV_VAR' => 10, 'SECOND_ENV_VAR' => 'second var value']) ->timeout(60) ->asJson() ->run(); print_r(json_encode($result)); } catch (\Exception $e) { print_r("Error: " . $e->getMessage()); } } }
โจ Features
๐ Secure Execution
- Path Validation โ Ensures scripts are within allowed directories.
- Argument & Environment Validation ๐ Restricts unauthorized input.
- Timeout Control โณ Prevents long-running scripts.
- black list for these vars
PATH,PYTHONPATH,LD_LIBRARY_PATH,LD_PRELOAD,PYTHONHOME
, can not passed . - Uses
proc_open
as an alternative toshell_exec
.
๐ง Flexible Configuration
- Centralized settings via
ConfigManager
. - Customizable execution parameters.
๐ค Output Handling
- Supports JSON parsing.
- Captures and reports script errors.
๐จ Error Management
- Detailed exception handling for debugging.
- Standardized error reporting.
๐ Extensibility
- Modular execution through
CommandExecutor
. - Customizable for advanced use cases.
Important Critical Note:
โ Never pass user-controlled input directly script, just pass scripts that you will need as a administrator (Just from Your side) .
๐ Changelog
See detailed release notes in CHANGELOG.md ๐
๐งช Testing
./vendor/bin/pest
๐ Security
Report Vulnerabilities: Contact omaralwi2010@gmail.com ๐ฉ
๐ค Contributors
A huge thank you to these amazing people who have contributed to this project! ๐๐
Omar AlAlwi ๐ Creator |
Want to contribute? Check out the contributing guidelines and submit a pull request! ๐
๐ License
This package is open-source software licensed under the MIT License. ๐