Stoic:PHP - ReturnHelper

The ReturnHelper class provides a mechanism for creating methods and functions that return more information than a simple scalar value to indicate success. Think of the ReturnHelper as a more specialized tuple, in that it focuses on situations that have clear success/fail conditions.

An Example

Given the following function:


function myTest($inputA, $inputB) {
    if ($inputA === null || $inputB === null) {
        return false;
    }

    if ($inputA < $inputB) {
        return false;
    }

    return true;
}

if (myTest($varA, $varB) === false) {
    // deal with false
}

This function returns a boolean value indicating some kind of success, but it also returns the same false value as a result of the guard against null values.

Returning false as a result of the guard may be sufficient, but sometimes you'd like to know why something has failed for reporting purposes. One approach is, of course, to utilize exceptions, but that is not always appropriate. As another alternative, you can use a ReturnHelper:


function myTest($inputA, $inputB) {
    $ret = new ReturnHelper();

    if ($inputA === null || $inputB === null) {
        $ret->makeBad();
        $ret->addMessage("myTest() received a null valuie");

        return $ret;
    }

    if ($inputA < $inputB) {
        $ret->makeBad();
        $ret->addMessage("inputA is less than inputB");

        return $ret;
    }

    $ret->makeGood();

    return $ret;
}

$ret = myTest($varA, $varB);

if ($ret->isBad()) {
    // deal with false & messages here
}

Now you have the same simple pass/fail approach as before, but with more information if it's useful, and without having to wrap all of your code in a series of try/catches.

Properties

protected string[] $_messages Collection of messages for this return protected mixed[] $_results Collection of results for this return protected integer $_status Integer value of this return's current status

Constants

integer STATUS_BAD Internal status for 'bad' returns integer STATUS_GOOD Internal status for 'good' returns

Methods

public ReturnHelper __construct() Instantiates a new ReturnHelper object set to 'bad' public void addMessage(string $message) Adds a message to the return public void addMessages(string[] $messages) Adds an array of messages to the return public void addResult(mixed $result) Adds a result value to the return public void addResults(mixed[] $results) Adds an array of results to the return public boolean isBad() Returns whether or not the return's status is 'bad' public boolean isGood() Returns whether or not the return's status is 'good' public string[] getMessages() Returns the collection of messages for the return public mixed[] getResults() Returns the collection of results for the return public boolean hasMessages() Returns whether or not the return has messages public boolean hasResults() Returns whether or not the return has messages public void makeBad() Sets the return's status as 'bad' public void makeGood() Sets the return's status as 'good'

Next Up

Continue to read about EnumBase, or visit the Table of Contents.