Skip to content

ddmitov/elephant-harness

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

74 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

elephant-harness

Travis CI Build Status Snyk Status Maintainability

Node.js - Electron - NW.js package for asynchronous handling of PHP scripts

Quick Start

npm install elephant-harness

const elephantHarness = require("elephant-harness");

let phpTest = {};
phpTest.script = "/test/test.php";

phpTest.stdoutFunction = function (stdout) {
  console.log(stdout);
};

elephantHarness.startScript(phpTest);

Core Dependency

child_process

External Dependency

The only external dependency of elephant-harness is a PHP interpreter on PATH or
a PHP interpreter identified by its full pathname.

elephant-harness npm package test will fail if no php binary is available on PATH.

php binary should be used in Node.js applications and test scripts.

php-cgi binary should be used in Electron and NW.js applications.

API

All settings of a PHP script executed by elephant-harness are stored in a JavaScript object with an arbitrary name and the following object properties:

  • script
    String for PHP script full path
    This object property is mandatory.

    phpTest.script = "/full/path/to/test.php";
  • stdoutFunction
    will be executed every time data is available on STDOUT
    The only parameter passed to the stdoutFunction is the STDOUT String.

    phpTest.stdoutFunction = function (stdout) {
      document.getElementById("DOM-element-id").textContent = stdout;
    };
  • stderrFunction
    will be executed every time data is available on STDERR
    The only parameter passed to the stderrFunction is the STDERR String.

    phpTest.stderrFunction = function (stderr) {
      console.log("PHP script STDERR:\n");
      console.log(stderr);
    };
  • errorFunction
    will be executed on PHP script error
    The only parameter passed to the errorFunction is the error Object.

    The errorFunction can generate a message when PHP interpreter is not found:

    phpTest.errorFunction = function (error) {
      if (error.code === "ENOENT") {
        console.log("PHP interpreter was not found.");
      }
    };
  • exitFunction
    will be executed when PHP script has ended
    The only parameter passed to the exitFunction is the exit code String.

    The exitFunction can generate a message when PHP script is not found:

    phpTest.exitFunction = function (exitCode) {
      if (exitCode === 2) {
        console.log("PHP script was not found.");
      }
    };
  • phpInterpreter
    String for a PHP interpreter: either filename on PATH or full pathname
    If no phpInterpreter is defined, php binary on PATH is used, if available.

    phpTest.interpreter = "/full/path/to/php";
  • interpreterSwitches
    Array for PHP interpreter switches

    phpTest.interpreterSwitches = [];
    phpTest.interpreterSwitches.push("-q");

    The php-cgi binary should be used with the -q switch in Electron and NW.js
    to enable quiet mode and suppress unnecessary HTTP header output.

  • scriptArguments
    Array for PHP script arguments

    phpTest.scriptArguments = [];
    phpTest.scriptArguments.push("argument-one");
    phpTest.scriptArguments.push("argument-two");
  • options
    Object for PHP script options passed to the child_process core module.
    Click here for a full list of all available child_process options.

  • options.cwd
    String for a new PHP script current working directory

    phpTest.options = {};
    phpTest.options.cwd = "/full/path/to/current-working-directory";;
  • options.env
    Object for a new PHP script environment

    Script environment with an inherited PATH and a new variable:

    phpTest.options = {};
    phpTest.options.env = {};
    phpTest.options.env.PATH = process.env.PATH;
    phpTest.options.env.TEST = "test";
  • options.detached
    Boolean option for starting detached PHP processes like servers

    options.detached must be set to true and
    options.stdio must be set to "ignore" to
    start a detached process without receiving anything from it.
    A process detached with the above options can run even after its parent has ended.

    Example settings for a PHP server application:

    let phpServer = {};
    phpServer.script = "/path/to/php-server-application";
    
    phpServer.options = {};
    phpServer.options.detached = true;
    phpServer.options.stdio = "ignore";
    
    const elephantHarness = require("elephant-harness");
    elephantHarness.startScript(phpServer);
    
    phpServer.scriptHandler.unref();
  • requestMethod
    String holding either GET or POST as a value.
    requestMethod has to be set for PHP scripts reading input data in CGI mode.

    phpTest.requestMethod = "GET";

    or

    phpTest.requestMethod = "POST";
  • inputData
    String or Function supplying user data as its return value.

    Single HTML input box example with no dependencies:

    phpTest.inputData = function () {
      let data = document.getElementById("input-box-id").value;
      return data;
    }

    Whole HTML form example based on jQuery:

    phpTest.inputData = function () {
      let formData = $("#form-id").serialize();
      return formData;
    }

Interactive Scripts

elephant-harness can also start and communicate with interactive scripts having their own event loops and capable of repeatedly receiving STDIN input. Use the following code to send data to an interactive script waiting for input on STDIN:

let data = document.getElementById("interactive-script-input").value;
phpTest.scriptHandler.stdin.write(data);

MIT 2016 - 2018
Dimitar D. Mitov