PHP Exceptions

Update:

This repository has been archived and for the time being is considered abandonware. Please use at your own discretion.

Synopsis

PHP Exceptions is an attempt to encapsulate a larger variation of exception classes that do not exist within PHP's SPL, and separate them in an orchestrated fashion by containing them within their own \Exceptions namespace.

As said by Arnout Boks:

"Proper exception handling takes quite some effort, but will eventually result in a much more stable application. A sensible exception handling strategy makes it clear what exceptions should be expected (and thus handled!) at a given point in the code. Moreover it will maintain the encapsulation and abstraction you carefully applied to your object-oriented design. Last but not least, it should make debugging a breeze."

Proper Exception handling is a must in PHP applications, and application development in general. This library hopes to encourage developers to properly handle exceptions, by giving them new and more tailored exception classes to work with. This package adds a new variety and flavor when building applications. For example, there are now exceptions for:

The File System

throw new \Exceptions\FileSystem\FileNotFoundException();

throw new \Exceptions\FileSystem\DirectoryAlreadyExistsException();

Arrays, objects & JSON

throw new \Exceptions\Collection\ArrayNotExistsException();

throw new \Exceptions\Collection\ObjectAlreadyExistsException();

throw new \Exceptions\Collection\InvalidJSONException();

Arithmetic

throw new \Exceptions\Operation\DivideByNegativeNumberException();

Revised PHP SPL's

throw new \Exceptions\JsonException();

throw new \Exceptions\RuntimeException();

throw new \Exceptions\DomainException();

And quite a few more with new ones being implemented all the time. All tested with PHPUnit 8+. And take note that these may be treated just like any standard PHP exceptions since they in fact extend these same standard PHP exceptions. Meaning that an optional message, code, etc may be passed into the __construct(). Framework versions will be available shortly after the official v.1.0 release.

Table of contents

• Synopsis
• Contributing
• Useful Links
• Requirements
• Installation
• License

Class Blueprint

Take a look at the following class blueprint (PHP.net):

namespace Exceptions\NamespaceName;
    
class ExampleException extends \RuntimeException
{
    /* Properties */
    protected string $message;
    protected int $code;
    protected string $file;
    protected int $line;

    /* Methods */
    public __construct ([ string $message = "" [, int $code = 0 [, Throwable $previous = NULL ]]] )
    final public getMessage ( void ) : string
    final public getPrevious ( void ) : Throwable
    final public getCode ( void ) : mixed
    final public getFile ( void ) : string
    final public getLine ( void ) : int
    final public getTrace ( void ) : array
    final public getTraceAsString ( void ) : string
    public __toString ( void ) : string
    final private __clone ( void ) : void
}

Useful Links

• Package Tests
• PHP Links:
  • PHP Exceptions
  • PHP SPL
• PHP FIG:
  • PHP-FIG PSR4
• Composer:
  • Get Composer

Requirements

• PHP >= 7.4 and ext-json
  • Due to the use of \JsonException and the use of typed properties [link].
• Composer

Installation

composer require jason-napolitano/php-exceptions

Basic Usage

// Require composer's autoloader
require_once = '/path/to/vendor/autoload.php';

try {
   $person = [
   	'name' => 'My Name',
   	'age'  => 21,
   	'city' => null
   ];
   if ( array_key_exists('gender', $person) ) {
       return $person['gender'];
       
   } else {
   	throw new \Exceptions\Collection\ArrayKeyNotExistsException();
   }
} catch (Exception $e) {
   echo 'Caught Exception: ',  $e->getMessage(), "\n";
}

OOP Usage:

• Don't forget your composer autoload.php file

class ClassName
{
    use \Exceptions\Helpers\ExceptionHelpers;

    public function methodName()
    {
        // Using a namespace
        self::throwNew('FileNotFoundException', 'FileSystem');

        // Using default namespace
        self::throwNew('RangeException');

        // Using the default \Exceptions\RuntimeException
        self::throwNew();
    }
}

License

MIT License

Copyright (c) 2019 Jason Napolitano

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.