PHP Classes

Deferred Exceptions: Queue exceptions and throws them afterwards

Recommend this page to a friend!
  Info   Documentation   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 68%Total: 139 All time: 9,230 This week: 455Up
Version License PHP version Categories
deferredexceptions 0.3.1GNU General Publi...5.6PHP 5, Language, Traits
Description 

Author

This package provides a trait that can queue exceptions and throws them afterwards.

It provides a function that queues exceptions and store the exception objects internally.

The trait can also throw later the last or all the queued exceptions.

Innovation Award
PHP Programming Innovation award nominee
July 2016
Number 9
Sometimes you need to call different functions in sequence and be able to see what exceptions they throw.

Usually if one function throws one exception, you cannot see what exceptions the other functions would have thrown.

This package provides a trait that allows you to queue multiple exceptions thrown by classes that use the trait. This way you can have access to the whole list of thrown exceptions throw the last or all exceptions that happened.

Manuel Lemos
Picture of magog
  Performance   Level  
Name: magog <contact>
Classes: 3 packages by
Country: Russian Federation Russian Federation
Age: 47
All time rank: 286379 in Russian Federation Russian Federation
Week rank: 288 Up16 in Russian Federation Russian Federation Up
Innovation award
Innovation award
Nominee: 2x

Documentation

DeferredExceptions

Introduction

DeferredExceptions trait provides a clean, fluent possibility to choose: to throw an exception now, later or simply handle errors. Also it accumulate exceptions of all classes that use this trait.

Description

Sometimes you need to call different functions in sequence and be able to see what exceptions they throw.

Usually if one function throws one exception, you cannot see what exceptions the other functions would have thrown.

This package provides a trait that allows you to queue multiple exceptions thrown by classes that use the trait. This way you can have access to the whole list of thrown exceptions throw the last or all exceptions that happened.

License

DeferredExceptions is open-sourced software licensed under the GPL-3.0.

Install

composer require seotils/deferred-exceptions
composer selfupdate
composer update

Usage

Let's say we have a problem with the class code. Transform it as follows:

<?php

namespace My;

use Seotils\Traits\DeferredExceptions;

/
 * Exception class to clearly understand
 * the class of the error occurred (will be autodetected)
 */
class SomeClassException extends \Exception {

}

/
 * Custom exception class (must be to passed as last argument to the ::exception() function)
 */
class MyCustomException extends \Exception {

}

class SomeClass {
    use DeferredExceptions;

    public function troubles(){
        try {
            // A problem code ..
        } catch( Exception $exc ) {
            // Old behavior:
            // throw new SomeClassException('Oh no!', 0, $exc);

            // Short syntax. Exception class will be detected as `My\SomeClassException`
            $this->exception('Oh no!');

            // Full syntax
            $this->exception(
                'Oh no!', // Error message
                0,        // Error code
                // Previous exception.
                // Used if only exception are thrown immediately with ::useExceptions( true )
                $exc, // Default: null
                // Custom exception class name
                'My\MyCustomException'
            );
        }
    }

    public function anotherTroubles(){
        // You can clear exception stack
        // NOTE. ::releaseExceptions() do not clean global stack of an `DeferredException` class !!!
        //       You must to use ::releaseGlobalExceptions()
        $this->releaseExceptions();
        try {
            // A problem code ..
        } catch( Exception $exc ) {
            ...
        }
    }

    public function andTroubles(){
        // You can detect if an instance of the class has deffered exceptions
        if( $this->hasExceptions() ){
            // Do somthing. For example assign default properties.
        }
        try {
            // A problem code ..
        } catch( Exception $exc ) {
            ...
        }
    }
}

And use it:

<?php
...
foreach( $list as $item){
    /@var $item \My\SomeClass/

    // Don't throws an exceptions.
    $item->useExceptions( false );
    ...
    // Calls a "bad" functions
    $item->troubles();
    $item->anotherTroubles();
    $item->andTroubles();
    ...
    // throws last exception was occured
    $item->throwLast(
        true // Release last exception in stack after throw
    );

    // throws an exception with a list of all exception was occured
    // using custom template of each item in the list
    $item->throwAll(
        true, // Release exception stack after throw
        // Template
        '`::class` exception was thrown at ::microtime with code #::code and say "::message"'
    );

    // Get an array of all exceptions of this class instance
    $errors = $item->getExceptions();
    foreach( $errors as $error)
    {
        $error ['time'];    // Microtime of an exception
        $error ['class'];   // Class of an exception
        $error ['code'];    // Error code
        $error ['message']; // Error message
    }
}
...
// If some exeptions was occured
if( DeferredExceptions::hasGlobalExceptions() ) {
    // Throws exception with a list of all exceptions of all derived classes.
    DeferredExceptions::throwGlobal(
        true, // Release exception stack after throw
        // Template
        '`::class` exception was thrown at ::microtime with code #::code and say "::message"')
    );
    // Or just get a list of exceptions for manual processing
    $errors = DeferredExceptions::getGlobalExceptions();
    foreach( $errors as $error)
    {
        $error ['time'];    // Microtime of an exception
        $error ['class'];   // Class of an exception
        $error ['code'];    // Error code
        $error ['message']; // Error message
    }
}

// Now we can clear the global exception stack and try another sequence
// NOTE. ::releaseGlobalExceptions() do not clear exceptions stacks of instances of a `DeferredException` class !!!
//       You must to use ::releaseExceptions() for each instance if you are want to use these
//       class instanses in second time with a clean exceptions history.
DeferredExceptions::releaseGlobalExceptions();
foreach( $secondList as $item){
    /@var $item \My\SomeClass/
    // Don't throws an exceptions.
    $item->useExceptions( false );

    // If $item was used in the previous sequence,
    // then clear the exceptions stack of an instance
    if( $item->hasExceptions()){
        $item->releaseExceptions();
    }
    ...
    // Calls a "bad" functions
    $item->troubles();
    $item->anotherTroubles();
    $item->andTroubles();
    ...
}
...

That`s all!


  Files folder image Files (4)  
File Role Description
Files folder imagesrc (1 file)
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file README.md Doc. Class source

  Files folder image Files (4)  /  src  
File Role Description
  Plain text file DeferredExceptions.php Class Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Reuses Unique User Downloads Download Rankings  
 100%1
Total:139
This week:0
All time:9,230
This week:455Up
User Ratings User Comments (2)
 All time
Utility:100%StarStarStarStarStarStar
Consistency:93%StarStarStarStarStar
Documentation:93%StarStarStarStarStar
Examples:-
Tests:-
Videos:-
Overall:68%StarStarStarStar
Rank:382
 
Thats a very good class to catch exceptions ;-)
8 years ago (José Filipe Lopes Santos)
70%StarStarStarStar
I once had such a need for implementing some kind of "bullet-...
8 years ago (Christian Vigh)
65%StarStarStarStar