Quickstart

Installing XPSPL

XPSPL is installed using (composer).

require: "prggmr/xpspl": "v5.0.0"

Once installed XPSPL’s API will be available after including composer’s vender/autoload.php.

Processing and Emitting signals

Processing and emitting signals is performed using the xp_signal, xp_emit and xp_complex_sig functions.

xp_signal

xp_signal($signal, $process)

Registers a process to execute when the given signal is emitted.

Note

All processes by default have an exhaust of null.

Note

Processes installed to the same signal execute in FIFO order when no priority is defined.

Parameters:
  • object – Signal to install process on.
  • object – PHP Callable
Return type:

object | boolean - XPSPLProcess otherwise boolean on error

Note

Beginning in XPSPL v4.0.0 all signals were converted to strictly objects.

To use a string or integer as a signal it must be wrapped in a XP_SIG.

Warning

Any signal created using `XP_SIG` CANNOT be unique.

Example #1 Basic Usage

<?php

// Install a process on the foo signal
xp_signal(XP_SIG('foo'), function(){
    echo 'foo';
});

// Emit the foo signal
xp_emit(XP_SIG('foo'));

The above example will output.

foo

Example #2 Class Signals

<?php

// Declare a simple signal
class SIG_Basic extends \XPSPL\SIG {}

// Install a process on the SIG_Basic class
xp_signal(new SIG_Basic(), function(){
    echo 'foo';
})

xp_emit(new SIG_Basic());

The above example will output.

foo

Example #3 Exhausting Processes

<?php

// Install a process on the foo signal, with an exhaust of 1
xp_signal(XP_SIG('foo', xp_exhaust(1, function(){
    echo 'foo';
})));

// Emit the foo signal
xp_emit(XP_SIG('foo'));
xp_emit(XP_SIG('foo'));

The above code will output.

foo

Example #4 Unique Signals

<?php

// Declare a simple unique
class SIG_Foo extends \XPSPL\SIG {
    // Set the signal as unique
    protected $_unqiue = true;
}

// Create two unique SIG_Foo objects
$sig_foo_1 = new SIG_Foo();
$sig_foo_2 = new SIG_Foo();

// Install a process to each unique signal
xp_signal($sig_foo_1, function(){
    echo 'foo';
});

xp_signal($sig_foo_2, function(){
    echo 'bar';
})

// Emit each unique signal
xp_emit($sig_foo_1);
xp_emit($sig_foo_2);

The above code will output.

foobar

xp_emit

xp_emit($signal[, $context = false])

Emits a signal.

This will execute all processes, before and after functions installed to the signal.

Returns the executed \XPSPL\SIG object.

Note

When emitting unique signals, e.g.. complex, routines or defined uniques the unique \XPSPL\SIG object installed must be provided.

Once a signal is emitted the following execution chain takes place.

  1. Before process functions
  2. Process function
  3. After process function
Parameters:
  • signal – XPSPLSIG object to emit.
  • object – XPSPLSIG object context to execute within.
Return type:

object XPSPLSIG

Example #1 Basic Usage

<?php

// Install a process on the foo signal
xp_signal(XP_SIG('foo'), function(){
    echo 'foo';
});

// Emit the foo signal
xp_emit(XP_SIG('foo'));

The above example will output.

foo

Example #2 Unique Signals

<?php

// Create a unique Foo signal.
class SIG_Foo extends \XPSPL\SIG {
    // declare it as unique
    protected $_unique = true;
}

// Create a SIG_Foo unique object
$foo = new SIG_Foo();

signal($foo, function(){
    echo "foo";
});

// Emit the SIG_Foo and another unique SIG_Foo
xp_emit($foo);
xp_emit(new Foo());

The above code will output.

foo

Example #3 Complex Signals

<?php

// Create our 3 required signals.
class SIG_Bells extends \XPSPL\SIG {}
class SIG_Bride extends \XPSPL\SIG {}
class SIG_Groom extends \XPSPL\SIG {}

// Create a complex signal that will emit when a wedding takes place
// based on 3 seperate signals, SIG_Bells, SIG_Bride and SIG_Groom.
class SIG_Wedding extends \XPSPL\SIG_Complex {

    // Keep track if each requirement has already emitted
    protected $_bells = false;
    protected $_bride = false;
    protected $_groom = false;

    // Create an evaulation method to evaluate the runtime
    public function evaluate($signal = null)
    {
      switch ($signal) {
        case $signal instanceof SIG_Bells:
            $this->_bells = true;
            break;
        case $signal instanceof SIG_Bride:
            $this->_bride = true;
            break;
        case $signal instanceof SIG_Groom:
            $this->_groom = true;
            break;
      }
      if ($this->_bells === true &&
            $this->_bride === true &&
            $this->_groom === true) {
        $this->_bells = false;
        $this->_groom = false;
        $this->_bride = false;
        return true;
      }
      return false;
    }
}

// Install a process for complex signal.
xp_signal(new SIG_Wedding(), function(){
    echo 'The wedding is happening!'.PHP_EOL;
});

// Emit SIG_Bells, SIG_Bride and SIG_Groom
xp_emit(new SIG_Bells());
xp_emit(new SIG_Bride());
xp_emit(new SIG_Groom());

The above code will output.

The wedding is happening!

xp_complex_sig

xp_complex_sig($function[, $rebind_context = true])

Allows for performing complex signal processing using callable PHP variables.

A \Closure will be bound into an object context which allows maintaining variables across emits within $this.

Note

A \Closure can remain bound to its original context by passing $rebind_context as false.

Parameters:
  • callable – Callable variable to use for evaluation.
  • boolean – Rebind the given closures context to this object.
Return type:

\XPSPL\SIG_Complex Complex signal registered to the processor.

Example #1 Detecting a wedding.

<?php
// Once a bride, groom and bell signals are emitted we emit the wedding.
$wedding = xp_complex_sig(function($signal){
    if (!isset($this->reset) || $this->reset) {
        $this->reset = false;
        $this->bride = false;
        $this->groom = false;
        $this->bells = false;
    }
    switch (true) {
        // Signals can be compared using the compare method
        // this will return if the signals are identical
        case $signal->compare(XP_SIG('groom')):
            $this->groom = true;
            break;
        case $signal->compare(XP_SIG('bride')):
            $this->bride = true;
            break;
        case $signal->compare(XP_SIG('bells')):
            $this->bells = true;
            break;
    }
    if ($this->groom && $this->bride && $this->bells) {
        $this->reset = true;
        return true;
    }
    return false;
});

xp_signal($wedding, function(){
    echo 'A wedding just happened.';
});

xp_emit(XP_SIG('bride'));
xp_emit(XP_SIG('groom'));
xp_emit(XP_SIG('bells'));

The above code will output.

A wedding just happened.

Example #2 Detecting a wedding using network recieved signals.

<?php

xp_import('network');

$server = network\connect('0.0.0.0', ['port' => 8000]);
// Setup a server that emits a signal of recieved data
$server->on_read(function($signal){
    $read = trim($signal->socket->read());
    if ($read == null) {
      return false;
    }
    xp_emit(XP_SIG($read));
});

// Once a bride, groom and bell signals are emitted we emit the wedding.
$wedding = xp_complex_sig(function($signal){
    if (!isset($this->reset) || $this->reset) {
      $this->reset = false;
      $this->bride = false;
      $this->groom = false;
      $this->bells = false;
    }
    switch (true) {
      case $signal->compare(XP_SIG('groom')):
          $this->groom = true;
          break;
      case $signal->compare(XP_SIG('bride')):
          $this->bride = true;
          break;
      case $signal->compare(XP_SIG('bells')):
          $this->bells = true;
          break;
    }
    if ($this->groom && $this->bride && $this->bells) {
      $this->reset = true;
      return true;
    }
    return false;
});

xp_signal($wedding, function(){
    echo 'A wedding just happened.';
});

// Start the wait loop
xp_wait_loop();

The above code will output.

A wedding just happened.

Once the bride, groom and bells signals are emitted from the network connection the complex signal will emit the wedding.

Environment

XPSPL ships with the xpspl command for directly loading into an environment.

XPSPL understands the following.

usage: xpspl [-c|--config=<file>] [-d] [-h|--help] [-p|--passthru] [--test]
              [--test-cover] [-v|--version] [-j|--judy]
              <file>
Options:
  -c/--config   Load the giving file for configuration
  -d            XPSPL Debug Mode
  -h/--help     Show this help message.
  -j/--judy     Enable judy support
  -p/--passthru Ignore any subsequent arguments and pass to <file>.
  --test        Run the XPSPL unit tests.
  --test-cover  Run unit tests and generate code coverage.
  -v/--version  Displays current XPSPL version.
Read the Docs v: v5.0.1
Versions
latest
v5.0.1
v5.0.0
v4.0.1
v4.0.0
v3.1.1
v3.1.0
v3.0.0
Downloads
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.