Skip to content

API Documentation

Jump to bottom Edit New page
filp edited this page Apr 24, 2013 · 19 revisions

API Documentation

Core Classes:

Core 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

// If true, allows Whoops to send output produced by handlers directly
// to the client. You'll want to set this to false if you want to
// package the handlers' response into your HTTP response abstraction
// or something (default: true)
Run::writeToOutput( $send = 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. Returns the
// output produced by handlers.
Run::handleException( Exception $exception )
 #=> string

// 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.
// Additionally, if frames contain URIs, the PrettyPageHandler
// will automagically convert them to clickable anchor elements.
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

// Accepts any valid callable
// For example, a closure, a string function name, an array
// in the format array($class, $method)
CallbackHandler::__construct( $callable )
 #=> null

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

Whoops\Handler\JsonResponseHandler

The JsonResponseHandler, upon receiving an exception to handle, simply constructs a JSON payload, and outputs it. Methods are available to control the detail of the output, and if it should only execute for AJAX requests - paired with another handler under it, such as the PrettyPageHandler, it allows you to have meaningful output for both regular and AJAX requests. Neat!

The JSON body has the following format:

{
  "error": {
    "type": "RuntimeException",
    "message": "Something broke!",
    "file": "/var/project/foo/bar.php",
    "line": 22,

     # if JsonResponseHandler::addTraceToOutput(true):
     "trace": [
        { "file": "/var/project/foo/index.php",
          "line": 157,
          "function": "handleStuffs",
          "class": "MyApplication\DoerOfThings",
          "args": [ true, 10, "yay method arguments" ] },
        # ... more frames here ...
     ]
  }
}

Methods

// Should detailed stack trace output also be added to the
// JSON payload body?
JsonResponseHandler::addTraceToOutput( bool $yes = null )
 #=> bool

// Should output only be sent if the current request is an
// AJAX request?
JsonResponseHandler::onlyForAjaxRequests( bool $yes = null )
 #=> bool

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

Whoops\Handler\PrettyPageHandler

The PrettyPageHandler generates a fancy, detailed error page which includes code views for all frames in the stack trace, environment details, etc. Super neat. It produces a bundled response string that does not require any further HTTP requests, so it's fit to work on pretty much any environment and framework that speaks back to a browser, without you having to explicitly hook it up to your framework/project's routing mechanisms.

Methods

// Adds a key=>value table of arbitrary data, labeled by $label, to
// the output. Useful where you want to display contextual data along
// with the error, about your application or project.
PrettyPageHandler::addDataTable( string $label, array $data )
 #=> null

// Returns all data tables registered with this handler. Optionally
// accepts a string label, and will only return the data under that
// label.
PrettyPageHandler::getDataTables( string $label = null )
 #=> array | array[]

// Sets the title for the error page
PrettyPageHandler::setPageTitle( string $title )
 #=> null

// Returns the title for the error page
PrettyPageHandler::getPageTitle()
 #=> string

// Returns a string path to the location where resources
// used by this handler are stored - the template and CSS
// files. 
PrettyPageHandler::getResourcesPath()
 #=> string

// Sets a string path to the location of resources for the
// handler. Useful if you want to roll your own template
// file (pretty-template.php and pretty-page.css) while
// still using the logic this handler provides
PrettyPageHandler::setResourcesPath( string $resourcesPath )
 #=> null

// Sets an editor to use to open referenced files, either by
// a string identifier, or as an arbitrary callable that returns
// a string that can be used as an href attribute.
// Available built-in editors are:
// - sublime
// - emacs
// - textmate
// - macvim
PrettyPageHandler::setEditor( string $editor )
PrettyPageHandler::setEditor( function($file, $line) { return string } )
 #=> null

// Similar to PrettyPageHandler::setEditor, but allows you
// to name your custom editor, thus sharing it with the
// rest of the application. Useful if, for example, you integrate
// Whoops into your framework or library, and want to share
// support for extra editors with the end-user.
// 
// $resolver may be a callable, like with ::setEditor, or a string
// with placeholders %file and %line.
// For example:
// $handler->addEditor('whatevs', 'whatevs://open?file=file://%file&line=%line')
PrettyPageHandler::addEditor( string $editor, $resolver )
 #=> null

PrettyPageHandler::handle()
 #=> int | null
Add a custom footer
Add a custom sidebar
Clone this wiki locally