README

Snake Charmer is a simple PHP class designed to execute Python scripts conveniently from within a PHP environment. It provides methods to run Python scripts, pass parameters to them, and retrieve the results.

Features

• Execute Python scripts from PHP with ease.
• Pass parameters to Python scripts.
• Retrieve results as strings or arrays.
• Clear script files and results conveniently.
• New: Support for saving script execution results to files.
• New: Methods for switching between memory and file output modes.

Installation

You can install Snake Charmer via Composer. Run the following command in your terminal:

composer require thunderbirddeveloper/snakecharmer

Usage

Here's a basic example of how to use Snake Charmer:

<?php

require 'vendor/autoload.php';

use ThunderbirdDeveloper\Bifrost\SnakeCharmer;

// Instantiate SnakeCharmer
$snakeCharmer = new SnakeCharmer();

// Set the script file
$snakeCharmer->setScripts('example/helloworld.py');

// Run the script
$snakeCharmer->run();

// Set the new path for another python script directory
$snakeCharmer->setPath(dirname(__DIR__). "/scripts");

// Execute another script from "/scripts"
$snakeCharmer->execute('test.py');

// Get the result as a string
$result = $snakeCharmer->getResultAsString();
echo $result; // Output the result

Methods available in the SnakeCharmer class

setPath($path)

Method setting the path to the directory containing Python scripts.

setScripts($files, $clearResult = true)

Method setting the list of scripts to execute.

run($params = '', $last = false)

Method executing scripts with optional parameters.

getResultAsString($separator = "\n")

Method returning the execution results of scripts as a single string.

getResultAsArray()

Method returning the execution results of scripts as an array.

switchOutputToFile()

Method switching the mode of saving script execution results to writing to a file.

switchOutputToMemory()

Method switching the mode of saving script execution results to writing to memory.

getLastExitCode()

Method returning the exit code of the last executed script. 0 means success, non-zero indicates an error.

New Features

• File Output Mode: Snake Charmer can now save the output of script executions to files. Use switchOutputToFile() to enable this mode.
• Memory Output Mode: Default mode where script results are stored in memory. Use switchOutputToMemory() to enable this mode.
• FileManager Integration: Manages the saving and retrieval of script execution results in file mode.
• LastExitCode: You can returning the exit code of the last executed script

Example use cases

You can also add a section describing more complex use cases, such as executing multiple scripts with different parameters, error handling, etc.

Testing

1. Running unit tests

SnakeCharmerTest.php contains unit tests for the SnakeCharmer class.

vendor/bin/phpunit test/SnakeCharmerTest.php

1. Running simple test

SimpleTest.php is a script that demonstrates how to use the SnakeCharmer class rather than a traditional unit test file.

php test/SimpleTest.php

When running these commands, make sure your unit tests are correctly defined and have all necessary dependencies loaded, including PHPUnit for unit testing.

Requirements

• PHP version 7.0 or higher
• System shell for executing Python scripts.

Changing Snake Charmer Version

If you need to change the version of Snake Charmer, follow these steps:

1. Edit composer.json file: Open the composer.json file in your project and update the version of Snake Charmer in the require section:

"require": {
    "thunderbirddeveloper/snakecharmer": "^1.0.0"
}

Update the version number (^1.0.0) according to Semantic Versioning rules (e.g., ^1.0.1 for MINOR update, ^1.1.0 for MAJOR update).

1. Update the library: Then run Composer to update the library to the new version:

composer update thunderbirddeveloper/snakecharmer

Reinstallation

If you need to reinstall Snake Charmer via Composer. Run the following command in your terminal:

composer remove thunderbirddeveloper/snakecharmer

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Damian Łukasik 08.02.2024