omaralalwi/laravel-py

Laravel wrapper for php-py package, to seamless enabling secure and efficient execution of Python scripts within PHP applications.

This package is auto-updated.

Last update: 2025-03-02 13:39:17 UTC


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

  • 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
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. ๐Ÿ“œ