restructure constructor arguments

remove addContext(), setSeverity()
refactor to use traits
fix tests

README.md

@@ -8,7 +8,7 @@ _Exceptables_ make exceptions exceptional.  Exceptables provide some nice utilit
 dependencies
 ------------
 
-Requires php 7.0 or later.
+Requires php 7.1 or later.
 
 installation
 ------------
@@ -56,6 +56,9 @@ see more in [the wiki](https://github.com/php-enspired/exceptable/wiki).
 docs
 ----
 
+**Note**, version 2.0 requires PHP 7.1 or greater, and also introduces a number of changes from the version 1 api.
+[Read more](https://github.com/php-enspired/exceptable/wiki/new-in-2.0).
+
 - API:
   - [The Exceptable Interface](https://github.com/php-enspired/exceptable/wiki/API:-The-Exceptable-Interface)
   - [The Exception Class](https://github.com/php-enspired/exceptable/wiki/API:-The-Exception-Class)

src/Exceptable.php

@@ -2,7 +2,7 @@
 /**
  * @package    at.exceptable
  * @author     Adrian <adrian@enspi.red>
- * @copyright  2014 - 2016
+ * @copyright  2014 - 2018
  * @license    GPL-3.0 (only)
  *
  *  This program is free software: you can redistribute it and/or modify it
@@ -32,17 +32,8 @@
  *    exceptable::getSeverity() will need to be aliased when the trait is used.
  *  - implementations cannot extend from PDOException,
  *    because it breaks the Throwable interface (its getCode() returns a string).
- *
- * @method string    Throwable::__toString( void )
- * @method int       Throwable::getCode( void )
- * @method string    Throwable::getFile( void )
- * @method int       Throwable::getLine( void )
- * @method string    Throwable::getMessage( void )
- * @method Throwable Throwable::getPrevious( void )
- * @method array     Throwable::getTrace( void )
- * @method string    Throwable::getTraceAsString( void )
  */
-interface Exceptable extends \Throwable {
+interface Exceptable extends Throwable {
 
   /**
    * exception severity levels.
@@ -55,53 +46,30 @@ interface Exceptable extends \Throwable {
   const WARNING = E_WARNING;
   const NOTICE = E_NOTICE;
 
-  /**
-   * default info for unknown/generic exception cases.
-   *
-   * @type int   DEFAULT_CODE
-   * @type int   DEFAULT_MESSAGE
-   * @type int   DEFAULT_SEVERITY
-   */
-  const DEFAULT_CODE = 0;
-  const DEFAULT_MESSAGE = '';
-  const DEFAULT_SEVERITY = self::ERROR;
-
   /**
    * gets information about a code known to the implementing class.
    *
-   * @param int $code             the exception code to look up
-   * @throws ExceptableException  if the code is not known to the implementation
-   * @return array                a map of info about the code,
-   *                              including (at a minimum) its "code", "severity", and "message".
+   * @param int $code    the exception code to look up
+   * @throws Exceptable  if the code is not known to the implementation
+   * @return array       a map of info about the error condition
    */
-  public static function get_info(int $code) : array;
+  public static function getInfo(int $code) : array;
 
   /**
    * checks whether the implementation has info about the given code.
    *
    * @param int $code  the code to check
    * @return bool      true if the code is known; false otherwise
    */
-  public static function has_info(int $code) : bool;
+  public static function hasInfo(int $code) : bool;
 
   /**
-   * @param string    $0          exception message
-   *                              if omitted, a message must be set based on the exception code
-   * @param int       $1          exception code
-   *                              if omitted, a default code must be set
-   * @param Throwable $2          previous exception
-   * @param array     $3          additional exception context
-   * @throws ExceptableException  if argument(s) are invalid
+   * @param int       $code       exception code
+   * @param array     $context    additional exception context
+   * @param Throwable $previous   previous exception
+   * @throws ExceptableException  if code is invalid
    */
-  public function __construct(...$args);
-
-  /**
-   * adds contextual info to this exception.
-   *
-   * @param array $context  map of info to add
-   * @return $this
-   */
-  public function addContext(array $context) : Exceptable;
+  public function __construct(int $code, array $context = [], Throwable $previous = null);
 
   /**
    * gets contextual info about this exception.
@@ -115,42 +83,12 @@ public function getContext() : array;
    *
    * @return Throwable  the root exception
    */
-  public function getRoot() : \Throwable;
+  public function getRoot() : Throwable;
 
   /**
    * gets exception severity.
    *
    * @return int  the exception severity
    */
   public function getSeverity() : int;
-
-  /**
-   * checks the exception severity.
-   *
-   * @return bool  true if exception severity is "Error"; false otherwise
-   */
-  public function isError() : bool;
-
-  /**
-   * checks the exception severity.
-   *
-   * @return bool  true if exception severity is "Warning"; false otherwise
-   */
-  public function isWarning() : bool;
-
-  /**
-   * checks the exception severity.
-   *
-   * @return bool  true if exception severity is "Notice"; false otherwise
-   */
-  public function isNotice() : bool;
-
-  /**
-   * adds contextual info to this exception.
-   *
-   * @param int $severity         one of Exceptable::ERROR|WARNING|NOTICE
-   * @throws ExceptableException  if severity is invalid
-   * @return $this
-   */
-  public function setSeverity(int $severity) : Exceptable;
 }

src/ExceptableException.php

@@ -20,47 +20,24 @@
 
 namespace at\exceptable;
 
-use at\exceptable\Exceptable,
-    at\exceptable\Exception;
+use at\exceptable\ {
+  Exceptable,
+  Exception
+};
 
 /**
  * exceptableexceptionsexceptableexceptionsexceptableexceptions
- *
- * @method int       \Exception::getCode( void )
- * @method string    \Exception::getFile( void )
- * @method int       \Exception::getLine( void )
- * @method string    \Exception::getMessage( void )
- * @method Throwable \Exception::getPrevious( void )
- * @method array     \Exception::getTrace( void )
- * @method string    \Exception::getTraceAsString( void )
- *
- * @method array      Exception::get_info( int $code )
- * @method bool       Exception::has_info( int $code )
- * @method void       Exception::__construct( string|int|Throwable|array …$args )
- * @method string     Exception::__toString( void )
- * @method Exceptable Exception::addContext( array $context )
- * @method array      Exception::getContext( void )
- * @method Throwable  Exception::getRoot( void )
- * @method int        Exception::getSeverity( void )
- * @method bool       Exception::isError( void )
- * @method bool       Exception::isWarning( void )
- * @method bool       Exception::isNotice( void )
- * @method Exceptable Exception::setSeverity( int $severity )
  */
 class ExceptableException extends Exception {
 
   /**
-   * @type int NO_SUCH_CODE            invalid exception code.
-   * @type int INVALID_CONSTRUCT_ARGS  invalid/out-of-order constructor arguments.
-   * @type int INVALID_SEVERITY        invalid severity level.
-   * @type int UNCAUGHT_EXCEPTION      uncaught/unhandled exception during runtime.
-   * @type int INVALID_HANDLER         invalid handler (e.g., wrong signature, or throws).
+   * @type int NO_SUCH_CODE        invalid exception code
+   * @type int UNCAUGHT_EXCEPTION  uncaught/unhandled exception during runtime
+   * @type int INVALID_HANDLER     invalid handler (e.g., wrong signature, or throws)
    */
   const NO_SUCH_CODE = 1;
-  const INVALID_CONSTRUCT_ARGS = (1<<1);
-  const INVALID_SEVERITY = (1<<2);
-  const UNCAUGHT_EXCEPTION = (1<<3);
-  const INVALID_HANDLER = (1<<4);
+  const UNCAUGHT_EXCEPTION = 2;
+  const INVALID_HANDLER = 3;
 
   /** @see Exceptable::INFO */
   const INFO = [
@@ -69,17 +46,6 @@ class ExceptableException extends Exception {
       'severity' => Exceptable::WARNING,
       'tr_message' => "no exception code '{code}' is known"
     ],
-    self::INVALID_CONSTRUCT_ARGS => [
-      'message' => 'constructor arguments are invalid and/or out of order',
-      'severity' => Exceptable::ERROR,
-      'tr_message' => "constructor arguments are invalid and/or out of order: {args}"
-    ],
-    self::INVALID_SEVERITY => [
-      'message' => 'invalid severity',
-      'severity' => Exceptable::WARNING,
-      'tr_message' =>
-        'severity must be one of Exceptable::ERROR|WARNING|NOTICE; {severity} provided'
-    ],
     self::UNCAUGHT_EXCEPTION => [
       'message' => 'uncaught exception',
       'severity' => Exceptable::ERROR,