gielfeldt/shutdownhandler

Shutdown Handler.

1.2.0 2015-09-20 19:24 UTC

Requires

• php: >=5.3.0

MIT

• Thomas Gielfeldt

• handler
• shutdown
• destructor

README

Installation

To install the ShutdownHandler library in your project using Composer, first add the following to your composer.json config file.

{
    "require": {
        "gielfeldt/shutdownhandler": "~1.0"
    }
}

Then run Composer's install or update commands to complete installation. Please visit the Composer homepage for more information about how to use Composer.

Shutdown handler

This shutdown handler class allows you to create advanced shutdown handlers, that can be manipulated after being created.

Motivation

1. Destructors are not run on fatal errors. In my particular case, I needed a lock class that was robust wrt to cleaning up after itself. See "Example 2" below or examples/fatal.php for an example of this.

2. PHP shutdown handlers cannot be manipulated after registration (unregister, execute, etc.).

Example 1 - using Shutdown Handler

namespace Gielfeldt\ShutdownHandler\Example;

require 'vendor/autoload.php';

use Gielfeldt\ShutdownHandler\ShutdownHandler;

/**
 * Simple shutdown handler callback.
 *
 * @param string $message
 *   Message to display during shutdown.
 */
function myshutdownhandler($message = '')
{
    echo "Goodbye $message\n";
}

// Register shutdown handler to be run during PHP shutdown phase.
$handler = new ShutdownHandler('\Gielfeldt\ShutdownHandler\Example\myshutdownhandler', array('cruel world'));

echo "Hello world\n";

// Register shutdown handler.
$handler2 = new ShutdownHandler('\Gielfeldt\ShutdownHandler\Example\myshutdownhandler', array('for now'));

// Don't wait for shutdown phase, just run now.
$handler2->run();

Example 2 - Ensuring object destruction

namespace Gielfeldt\ShutdownHandler\Example;

require 'vendor/autoload.php';

use Gielfeldt\ShutdownHandler\ShutdownHandler;

/**
 * Test class with destructor via Gielfeldt\ShutdownHandler\ShutdownHandler.
 */
class MyClass
{
    /**
     * Reference to the shutdown handler object.
     * @var ShutdownHandler
     */
    protected $shutdown;

    /**
     * Constructor.
     *
     * @param string $message
     *   Message to display during destruction.
     */
    public function __construct($message = '')
    {
        // Register our shutdown handler.
        $this->shutdown = new ShutdownHandler(array(get_class($this), 'shutdown'), array($message));
    }

    /**
     * Run our shutdown handler upon object destruction.
     */
    public function __destruct()
    {
        $this->shutdown->run();
    }

    /**
     * Our shutdown handler.
     *
     * @param string $message
     *   The message to display.
     */
    public static function shutdown($message = '')
    {
        echo "Destroy $message\n";
    }
}

// Instantiate object.
$obj = new MyClass("world");

// Destroy object. The object's shutdown handler will be run.
unset($obj);

// Instantiate new object.
$obj = new MyClass("universe");

// Object's shutdown handler will be run on object's destruction or when PHP's
// shutdown handlers are executed. Whichever comes first.

For more examples see the examples/ folder.

Features

• Unregister a shutdown handler
• Run a shutdown handler prematurely
• Improve object destructors by ensuring destruction via PHP shutdown handlers
• Keyed shutdown handlers, allowing to easily deduplicate multiple shutdown handlers

Caveats

1. Lots probably.