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

1. 📂 Create a folder for scripts, e.g., phpPyScripts in your project root directory.
2. 📝 Create a Python script file (.py extension) and write Python code. See this script examples.
3. 🔧 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 to shell_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. 📜