1: <?php
  2: /**
  3:  * This file contains the implementation of the class SmartException. It extends the standard
  4:  * exception by the string code and type of excetion.
  5:  *
  6:  * Since the error texts can be localized, the unique code of the error might be important fo using
  7:  * in comparison.
  8:  * The type of the error might be useful for decision how to show the error on the client. If it is a
  9:  * user error, the full error texts should be shown. If it is a programming error, the detailed text should
 10:  * be shown only in the debug mode to prevent that the hackers get sensible information about the system.
 11:  *
 12:  * @package System
 13:  *
 14:  * @author Oleg Schildt
 15:  */
 16: 
 17: namespace SmartFactory;
 18: 
 19: /**
 20:  * Class for extended exception collection used in the SmartFactory library. It allows to collect many errors
 21:  * and report them at once.
 22:  *
 23:  * @author Oleg Schildt
 24:  */
 25: class SmartExceptionCollection extends \Exception
 26: {
 27:     /**
 28:      * Internal variable for storing the single errors.
 29:      *
 30:      * @var array
 31:      *
 32:      * @author Oleg Schildt
 33:      */
 34:     protected array $errors = [];
 35: 
 36:     /**
 37:      * Stores the error to be reported.
 38:      *
 39:      * @param string $message
 40:      * The error message to be reported.
 41:      *
 42:      * @param array $details
 43:      * The details might be useful if the message translations are provided on the client, not
 44:      * on the server, and the message should contain some details that may vary from case to case.
 45:      * In that case, the servers return the message id instead of final text and the details, the client
 46:      * uses the message id, gets the final translated text and substitutes the parameters through the details.
 47:      *
 48:      * @param string $related_element
 49:      * The error element associated with the error.
 50:      *
 51:      * @param string $code
 52:      * The error code to be reported.
 53:      *
 54:      * @param string $technical_info
 55:      * The technical information for the error. Displaying
 56:      * of this part might be controlled over an option
 57:      * "debug_mode".
 58:      *
 59:      * @param string $file
 60:      * The source file where the error occurred. Per default, the file where the adding error called.
 61:      *
 62:      * @param string $line
 63:      * The source file line where the error occurred. Per default, the file line where the adding error called.
 64:      *
 65:      * @return void
 66:      *
 67:      * @author Oleg Schildt
 68:      */
 69:     public function addError(string $message, array $details = [], string $related_element = "", string $code = "", string $technical_info = "", string $file = "", string $line = ""): void
 70:     {
 71:         if (empty($message)) {
 72:             return;
 73:         }
 74: 
 75:         if (empty($file) || empty($line)) {
 76:             $backfiles = debug_backtrace();
 77: 
 78:             if (empty($file)) {
 79:                 $file = empty($backfiles[0]['file']) ? "" : $backfiles[0]['file'];
 80:             }
 81: 
 82:             if (empty($line)) {
 83:                 $line = empty($backfiles[0]['line']) ? "" : $backfiles[0]['line'];
 84:             }
 85:         }
 86: 
 87:         $this->errors[md5($message . implode("#", $details))] = [
 88:             "message" => $message,
 89:             "details" => $details,
 90:             "related_element" => $related_element,
 91:             "code" => $code,
 92:             "technical_info" => $technical_info,
 93:             "file" => $file,
 94:             "line" => $line
 95:         ];
 96:     }
 97: 
 98:     /**
 99:      * Throws itself if any error has been collected.
100:      *
101:      * @return void
102:      *
103:      * @throws SmartExceptionCollection
104:      * Throws itself if there are errors.
105:      *
106:      * @author Oleg Schildt
107:      */
108:     public function throwIfErrors(): void
109:     {
110:         if (count($this->errors) > 0) {
111:             throw $this;
112:         }
113:     }
114: 
115:     /**
116:      * Returns the array of errors if any have been stored.
117:      *
118:      * @return array
119:      * Returns the array of errors if any have been stored.
120:      *
121:      * @author Oleg Schildt
122:      */
123:     public function getErrors(): array
124:     {
125:         return $this->errors;
126:     }
127: } // SmartExceptionCollection