API Documentation

API Documentation

Core Classes:

• Whoops\Run - The main Whoops class - represents the stack and current execution
• Whoops\Handler\Handler and Whoops\Handler\HandlerInterface - Abstract representation of a Handler, and utility methods
• Whoops\Exception\Inspector - Exposes methods to inspect an exception
• Whoops\Exception\Frame - Exposes methods to inspect a single stack trace frame from an exception

Core Handlers:

• Whoops\Handler\CallbackHandler - Wraps regular closures as handlers

Core Classes:

Whoops\Run

The Run class models an instance of an execution, and integrates the methods to control whoops' execution in that context, and control the handlers stack.

Constants

string Run::EXCEPTION_HANDLER // (name for exception handler method)
string Run::ERROR_HANDLER     // (name for error handler method)
string Run::SHUTDOWN_HANDLER  // (name for shutdown handler method)

Methods

// Pushes a new handler to the stack of handlers
Run::pushHandler( Whoops\HandlerInterface $handler )
 #=> Whoops\Run

// Pops and returns the last handler from the stack
Run::popHandler()
 #=> Whoops\HandlerInterface

// Returns all handlers in the stack
Run::getHandlers()
 #=> Whoops\HandlerInterface[]

// Returns a Whoops\Inspector instance for a given Exception
Run::getInspector( Exception $exception )
 #=> Whoops\Exception\Inspector

// Registers this Whoops\Run instance as an error/exception/shutdown
// handler with PHP
Run::register()
 #=> Whoops\Run

// I'll let you guess this one
Run::unregister()
 #=> Whoops\Run

// If true, allows Whoops to terminate script execution (default: true)
Run::allowQuit( $allowQuit = null )
 #=> bool

// ** HANDLERS **
// These are semi-internal methods that receive input from
// PHP directly. If you know what you're doing, you can
// also call them directly

// Handles an exception with the current stack
Run::handleException( Exception $exception )
 #=> null

// Handles an error with the current stack. Errors are
// converted into SPL ErrorException instances
Run::handleError( int $level, string $message, string $file = null, int $line = null)
 #=> null

// Hooked as a shutdown handler, captures fatal errors and handles them
// through the current stack:
Run::handleShutdown()
 #=> null

Whoops\Handler\Handler & Whoops\Handler\HandlerInterface

This abstract class contains the base methods for concrete handler implementations. Custom handlers can extend it, or implement the Whoops\Handler\HandlerInterface interface.

Constants

int Handler::DONE          // If returned from HandlerInterface::handle, does absolutely nothing.
int Handler::LAST_HANDLER  // ...tells whoops to not execute any more handlers after this one.
int Handler::QUIT          // ...tells whoops to quit script execution immediately.

Methods

// Custom handlers should expose this method, which will be called once an
// exception needs to be handled. The Handler::* constants can be used to
// signal the underlying logic as to what to do next.
HandlerInterface::handle()
 #=> null | int

// Sets the Run instance for this handler
HandlerInterface::setRun( Whoops\Run $run)
 #=> null

// Sets the Inspector instance for this handler
HandlerInterface::setInspector( Whoops\Exception\Inspector $inspector)
 #=> null

// Sets the Exception for this handler to handle
HandlerInterface::setException( Exception $exception )
 #=> null

Whoops\Exception\Inspector

The Inspector class provides methods to inspect an exception instance, with particular focus on its frames/stack-trace.

Methods

Inspector::__construct( Exception $exception )
 #=> null

// Returns the Exception instance being inspected
Inspector::getException()
 #=> Exception

// Returns the string name of the Exception being inspected
// A faster way of doing get_class($inspector->getException())
Inspector::getExceptionName()
 #=> string

// Returns the string message for the Exception being inspected
// A faster way of doing $inspector->getException()->getMessage()
Inspector::getExceptionMessage()
 #=> string

// Returns an iterator instance for all the frames in the stack
// trace for the Exception being inspected.
Inspector::getFrames()
 #=> Whoops\Exception\FrameIterator

Whoops\Exception\Frame

The Frame class models a single frame in an exception's stack trace. You can use it to retrieve info about things such as frame context, file, line number. Additionally, you have available functionality to add comments to a frame, which is made available to other handlers.

Methods

// Returns the file path for the file where this frame occured.
// The optional $shortened argument allows you to retrieve a
// shorter, human-readable file path for display.
Frame::getFile( bool $shortened = false )
 #=> string | null (Some frames do not have a file path)

// Returns the line number for this frame
Frame::getLine()
 #=> int | null

// Returns the class name for this frame, if it occured
// within a class/instance.
Frame::getClass()
 #=> string | null

// Returns the function name for this frame, if it occured
// within a function/method
Frame::getFunction()
 #=> string | null

// Returns an array of arguments for this frame. Empty if no
// arguments were provided.
Frame::getArgs()
 #=> array

// Returns the full file contents for the file where this frame
// occured.
Frame::getFileContents()
 #=> string | null

// Returns an array of lines for a file, optionally scoped to a
// given range of line numbers. i.e: Frame::getFileLines(0, 3)
// returns the first 3 lines after line 0 (1)
Frame::getFileLines( int $start = 0, int $length = null)
 #=> array | null

// Adds a comment to this Frame instance. Comments are shared
// with everything that can access the frame instance, obviously,
// so they can be used for a variety of inter-operability purposes.
// The context option can be used to improve comment filtering.
Frame::addComment( string $comment, string $context = 'global' )
 #=> null

// Returns all comments for this instance optionally filtered by
// a string context identifier.
Frame::getComments( string $filter = null )
 #=> array

Core Handlers

Whoops\Handler\CallbackHandler

The CallbackHandler handler wraps regular PHP closures as valid handlers. Useful for quick prototypes or simple handlers. **When you pass a closure to Run::pushHandler, it's automatically converted to a CallbackHandler instance.

<?php

use Whoops\Handler\Handler;

$run->pushHandler(function($exception, $inspector, $run) {
    var_dump($exception->getMessage());
    return Handler::DONE;
});

$run->popHandler() // #=> Whoops\Handler\CallbackHandler

Methods

CallbackHandler::__construct( $callable )
 #=> null

CallbackHandler::handle()
 #=> int | null