The history of one class for error handling.

Preface (Feel free to skip)

Have a nice time of day.

I had a desire to share a story with you. The history of the error handling class. Why not just bring the “as is” class and not let you judge its merits and demerits? The reason is simple. In this case, it will not be possible to understand why he became exactly what he is. It will be impossible to detect errors in the logic of its creation. It is impossible to understand whether your situation is similar to mine and whether it is possible for you to use it or, perhaps, it is better to turn your attention to another class of error handling. Fortunately, you will find many of them.

And with what such a fright did I even start writing my own error handling class? After all, there is a lot of groundwork in this area. The accumulation of serious, very intelligent people. The reason is simple. Different reasons led to the creation of these classes; the creation of these classes pursued different goals. And, as we all know well, there are few bicycles and they all taste different.

First, I had a need to write several classes that I could use in my projects and which would be simpler and faster than analogs and, most importantly, would implement the functionality that I need. No more and no less. No redundancy.

First drafts

No sooner said than done. Classes were written. And, quite naturally, they all had to somehow work with errors. Here are the requirements I made for such processing:

Errors should not be thrown into the stream. Classes are used in different projects, and often in scripts that are accessed using AJAX. Anyway, classes should never come into contact with presentation logic.
The error may correspond to descriptive text.
After the method is executed, it should be possible to determine whether an error occurred during its operation and what its descriptive text is.
Checking for an error should not be based on the value returned by the method, because sometimes it is impossible to return false / true, it is necessary to return data.

So, everything is relatively simple. What we add to the class to implement error handling:

The err flag, which will be false if there is no error and the message assigned to the error otherwise. The flag should not be directly accessible outside the class.
There must be a method that clears the error flag. If an error has occurred, but it is not critical and its possibility is provided by the program logic, then the error should be reset the next time any class method is called, so that its state always corresponds to the presence or absence of errors during the last call to the class method.
There must be a method for cocking the error flag.
There should be a method that checks if there was an error and returns false if it is absent and the message assigned to the error otherwise.

Copy Source | Copy HTMLclass test_class{
    private $err;
 
    public function set_err($msg=''){
        $this->err=$msg;
    }
 
    public function clear_err(){
        $this->err=false;
    }
 
    public function is_err(){
        return $this->err;
    } 
 
    public function some_method(){
        $this->clear_err();
        if(some_err){
            $this->set_err($msg='Some error appear.');
            return false;
        }
        return true;
    }
 
    public function complex_method(){
        $this->clear_err();
        $this->some_method();
        if($this->is_err()!==false){
            return false;
        }
        return true;
    }
}
 
define('some_err',true);
$test_instance = new test_class;
$test_instance->complex_method();
if($test_instance->is_err()!==false){
    die($test_instance->is_err());
}
die('No error appear.');

Separation of functionality in a separate class

Here you go. Everything is working. There is only one unpleasant moment. This code is repeated in every class. While the class was one, everything was fine. But as soon as the number of classes grew, it became, at a minimum, uncomfortable. So the code was allocated in a separate class.

Copy Source | Copy HTMLclass error_class{
    private $err=false;
 
    public function set_err($msg=''){
        $this->err=$msg;
    }
 
    public function clear_err(){
        $this->err=false;
    }
 
    public function is_err(){
        return $this->err;
    } 
}
class test_class{
    public $err;
 
    public function __construct(){
        $this->err = new error_class();
    }
 
    public function some_method(){
        $this->err->clear_err();
        if(some_err){
            $this->err->set_err($msg='Some error appear.');
            return false;
        }
        return true;
    }
 
    public function complex_method(){
        $this->err->clear_err();
        $this->some_method();
        if($this->err->is_err()!==false){
            return false;
        }
        return true;
    }
}
 
define('some_err',true);
$test_instance = new test_class;
$test_instance->complex_method();
if($test_instance->err->is_err()!==false){
    die($test_instance->err->is_err());
}
die('No error appear.');

Handling critical errors using exceptions.

Here you go. Already better. You can use it with any class by adding it once at the beginning of the class file that uses it. That's just the information about the presence of errors, he transmits, but does not deal with their processing. It would be rather strange to create an additional class to intercept and direct errors to the handler, so let's expand its functionality a little:
Copy Source | Copy HTMLrequire_once("error_class.php");

Simplify critical error handling. That is, such errors that should immediately cause the script to stop working and pass an error to the handler.
We implement the ability to assign a custom error handler. Such a handler cannot be unified and, accordingly, it should allow connecting a user-defined function.

We use exceptions to handle critical errors .
set_exception_handler - Defines a custom exception handler.
restore_exception_handler - restores the previous handler for exceptions.
Exception is the base class for all exceptions.

Everything is elementary.

In the class constructor, we add an additional argument $ callback, which contains the callback function.
Add the variable $ exception_handler - this is a flag that indicates that a custom exception handler has been assigned. It is needed to determine in the destructor whether the previous exception handler needs to be restored.
We add the fire_err method to the class, with the help of which it will be possible to raise exceptions in case of a critical error.
We create a class destructor, which will, if necessary, restore the exception handler to its previous state.

And our code takes the following form: Using the class will now look like this:

Copy Source | Copy HTMLclass error_class{
 
    private $err=false;
    private $exception_handler=false;
 
    public function __construct($callback=null){
        if($callback!=null){
            $this->exception_handler=true;
            set_exception_handler($callback);
        }
    }
 
    public function set_err($msg=''){
        $this->err=$msg;
    }
 
    public function clear_err(){
        $this->err=false;
    }
 
    public function is_err(){
        return $this->err;
    }
 
    public function fire_err($msg='',$code=0){
        $this->err=$msg;
        throw new Exception($msg,$code);
    }
 
    public function __destruct(){
        if($this->exception_handler){
            restore_exception_handler();
        }
    }
}

Copy Source | Copy HTML 
define('some_err',true);
$err = new error_class("err_overwork");
$test_instance = new test_class;
$test_instance->complex_method();
if($test_instance->err->is_err()!==false){
    $err->fire_err($test_instance->err->is_err(),-1);
}
 
function err_overwork($error){
    die("Ошибка: ".$error->getMessage()."<br/>Файл: ".$error->getFile()."<br/>Строка: ".$error->getLine());
}

Handling errors generated by the interpreter.

Here you go. Now it remains to add only one. The ability (namely the opportunity) to transmit the user-defined error handling functions and errors generated by the interpreter (except, of course, syntax errors). In this way, a uniform display of errors can be achieved. Of course, the need for this is extremely controversial. Use or not - you decide. It seems to me that this can sometimes be appropriate.

set_error_handler - allows you to pass error handling to the user exit.
restore_error_handler - restores the previous error handler.
ErrorException - An exception class to represent the error.

In principle, there is nothing complicated. Using set_error_handlerinstall the handler and you're done. As additional arguments in the constructor, we accept:

$ err_redirect - Whether to catch the errors that the interpreter generates. Values: [true | false].
$ level - Permissible level of errors caught. Values: Constants defined for the interpreter . For example: E_ALL.

But there is a nuance. In the case of an error generated by us, the handler receives an Exception object . But if the error was generated by the interpreter, it receives a set of arguments. Naturally, it is appropriate to make the processor receive homogeneous data regardless of the source. An ErrorException object was developed specifically for this . So, we add the redirect_err function to the error handling class, which will handle the error, namely, to raise an exception that will already be caught by the handler assigned by the user. In addition, we add a flag that will indicate that the errors generated by the interpreter are intercepted and that it is necessary to restore, if necessary, the previous handler in the class’s destructor using the functionrestore_error_handler .
And now our class takes on a finished and ready-to-use look: And here is a really existing code example, using it:

Copy Source | Copy HTMLclass error_class{
 
    private $err=false;
    private $exception_handler=false;
    private $err_handler=false;
 
    public function __construct($callback=null,$err_redirect=true,$level=E_ALL){
        if($callback!=null){
            $this->exception_handler=true;
            set_exception_handler($callback);
            if($err_redirect){
                $this->err_handler = true;
                set_error_handler(array("error_class","redirect_err"),$level);
            }
        }
    }
 
    public function redirect_err($errno, $errstr, $errfile, $errline, $errcontext){
        throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
        return true;
    }
 
    public function set_err($msg=''){
        $this->err=$msg;
    }
 
    public function clear_err(){
        $this->err=false;
    }
 
    public function is_err(){
        return $this->err;
    }
 
    public function fire_err($msg='',$code=0){
        $this->err=$msg;
        throw new Exception($msg,$code);
    }
 
    public function __destruct(){
        if($this->exception_handler){
            restore_exception_handler();
        }
        if($this->err_redirect){
            restore_error_handler();
        }
    }
}

Copy Source | Copy HTML<?php
    session_start();
    require_once("error_class.php");
    require_once("mail_class.php");
 
    $err = new error_class("err_overwork");
 
    if(
       !isset($_POST['email'])||
       !isset($_POST['message'])||
       !isset($_POST['captcha'])
       ){
        $err->fire_err("Не все переменные заданы",-1);
    }
    if($_SESSION['captcha']!=$_POST['captcha']){
        $err->fire_err("Неверно введен код обратного теста Тьюринга",-1);
    }else{
        unset($_SESSION['captcha']);
    }
 
    $mailer = new mail_class();
 
    if(!$mailer->text(addslashes(htmlspecialchars($_POST['message'])))){
        $err->fire_err($mailer->err->is_err(),-1);
    }
    if(!$mailer->to("Студия «Ночной народ»","raven@nightfolk.net")){
        $err->fire_err($mailer->err->is_err(),-1);
    }
    if(!$mailer->from(addslashes($_POST['email']))){
        $err->fire_err($mailer->err->is_err(),-1);
    }
    if(!$mailer->subj('Сообщение от посетителя')){
        $err->fire_err($mailer->err->is_err(),-1);
    }
    if(!$mailer->reply_to(addslashes($_POST['email']))){
        $err->fire_err($mailer->err->is_err(),-1);
    }
    if(!$mailer->send()){
        $err->fire_err($mailer->err->is_err(),-1);
    }
 
    header("location:../confirm.html");
    die();
 
    function err_overwork($error){
        $_SESSION['error_message']=$error->getMessage();
        header("location:../error.php");
        die();
    }
?>

Enlightenment (IMPORTANT)

After stormy and productive communication with a mass of very angry people,
Read the article " Handling Exceptional Situations in OOP "
Three times re-reading the documentation on the exception mechanism in php
And, finally, discussing the problem on the phpclub.ru forum .
I realized that exceptions are a sufficient mechanism for implementing error handling and it makes no sense to drag something else.
However, in order not to duplicate the destination code of the default exception handler and the error message handler generated by the interpreter at each entry point, it makes sense that the class exists in the following form: Now you can assign the handler in one line: Well, the script will look like this:

Copy Source | Copy HTMLclass error_class{
 
    private $err_handler=false;
 
    public function __construct($callback=null,$err_redirect=true,$level=E_ALL){
        if($callback==null){
            throw new Exception("Не определена callback функция.",E_ERROR);
        }
        set_exception_handler($callback);
        if($err_redirect){
            $this->err_handler = true;
            set_error_handler(array("error_class","redirect_err"),$level);
        }
    }
 
    public function redirect_err($errno, $errstr, $errfile, $errline, $errcontext){
        throw new ErrorException($errstr, 0, $errno, $errfile, $errline);
        return true;
    }
 
 
    public function __destruct(){
        restore_exception_handler();
        if($this->err_handler){
            restore_error_handler();
        }
    }
}

Copy Source | Copy HTMLnew error_class('err_overwork');
function err_overwork($error){ 
}

Copy Source | Copy HTML<?php
    session_start();
    header("content-type: text/html; charset=utf-8");
 
    require_once("mail_class.php");
    require_once("error_class.php");
 
    $err = new error_class("err_overwork"); 
 
    if(
       !isset($_POST['email'])||
       !isset($_POST['message'])||
       !isset($_POST['captcha'])
       ){
        throw new Exception("Не все переменные заданы",E_ERROR);
    }
 
    if($_SESSION['captcha']!=$_POST['captcha']){
        throw new Exception("Неверный код подтверждения",E_ERROR);
    }else{
        unset($_SESSION['captcha']);
    }
 
    $mailer = new mail_class(); 
    $mailer->text(addslashes(htmlspecialchars($_POST['message'])));
    $mailer->to("Студия «Ночной народ»","raven@nightfolk.net");
    $mailer->from(addslashes($_POST['email']));
    $mailer->subj('Сообщение от посетителя');
    $mailer->reply_to(addslashes($_POST['email']));
    $mailer->send();
 
    header("location:../confirm.html");
    die();
 
    function err_overwork($error){
        $_SESSION['error_message']=$error->getMessage();
        header("location:../error.php");
        die();
    }
?>

Послесловие (В принципе — ничего особо важного)

I hope that this article will be interesting to you or even bring some benefit.
I will be very happy about this.
I would be very grateful if you could write your thoughts about the class and the process of its development.
If you see something that can be improved, write.
If you see any flaws, vulnerabilities or errors - write .
And, if you write, then in this world, perhaps, at least for a long time it will become one happy me more.
And also, write whether you liked the article or if it turned out to be lengthy and tedious. I want to know whether I should write more ... Or it will be just the agony of a graphomaniac.
PS I can also describe a caching class or template engine. But you never know what. The main thing is that it would be interesting to you.

Acknowledgments (Read Required)

Thanks to sunnybear for the invitation to Habrahabr, for the wonderful YASS framework and for being glued. I still liked him at RITA.
Thanks to habraname for showing interest in YASS, writing a funny wrapper and just pleasant to talk to.
Thanks to zerkms for taking the time to clarify and pushing for additional experiments.

Tags: