Merge branch 'release/v0.16.0'

decodelabs · Oct 2, 2020 · 710fa5c · 710fa5c
2 parents 4cad132 + 4c91860
commit 710fa5c
Show file tree

Hide file tree

Showing 19 changed files with 71 additions and 1,326 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## v0.16.0 (2020-10-02)
+* Moved exception Factory to Exceptional
+* Removed all Exception generation functionality
+
 ## v0.15.10 (2020-09-30)
 * Switched to Exceptional for exception generation
 

diff --git a/README.md b/README.md
@@ -9,9 +9,9 @@
 
 ### Better tools for when things go wrong
 
-Glitch is a standalone PHP package designed to improve end-to-end error generation, handling and inspection when developing your applications.
+Glitch is a standalone PHP package designed to improve error handling and inspection when developing your applications.
 
-The project aims to provide a radically enhanced Exception framework that decouples the _meaning_ of an Exception from the underlying _implementation_ functionality, alongside deep data inspection tools and an Exception handling interface.
+The project aims to provide deep data inspection tools and an Exception handling interface.
 
 ![v0.15.0 interface](docs/v0.15.0.png)
 
@@ -162,138 +162,9 @@ class MyClass implements Dumpable {
 }
 ```
 
-The <code>Dumpable</code> interface is **NOT** _required_ - Glitch will check for the existence of the method regardless, which is useful if you do not want to rely on a dependency on the Glitch library just to provide better dump handling. However if you _do_ have Glitch in your dependency tree, it is recommended you fully implement the <code>Dumpable</code> interface for the best possible compatibility.
+The <code>Dumpable</code> interface is **NOT** _required_ - Glitch will check for the existence of the method regardless, which is useful if you do not want to rely on a dependency on the Glitch library just to provide better dump handling.
 
-
-## Exceptions
-**Please be aware, Glitch Exceptions are being deprecated in favour of a new standalone library (TBC)**
-
-Glitch exceptions can be used to greatly simplify how you create and throw errors in your code, especially if you are writing a shared library.
-
-Throw <code>Glitches</code> rather than <code>Exceptions</code>, passing interface names to be mixed in as the method name (custom generated error interfaces must be prefixed with E) to the Glitch call.
-
-```php
-throw Glitch::EOutOfBounds('This is out of bounds');
-
-// Implement multiple interfaces
-throw Glitch::{'ENotFound,EBadMethodCall'}(
-    "Didn't find a thing, couldn't call the other thing"
-);
-
-// You can associate a http code too..
-throw Glitch::ECompletelyMadeUpMeaning('My message', [
-    'code' => 1234,
-    'http' => 501
-]);
-
-// Implement already existing Exception interfaces
-throw Glitch::{'EInvalidArgument,Psr\\Cache\\InvalidArgumentException'}(
-    'Cache items must implement Cache\\IItem',
-    ['http' => 500],  // params
-    $item             // data
-);
-
-// Reference interfaces using a path style
-throw Glitch::{'../OtherNamespace/OtherInterface'}('My exception');
-```
-
-Catch a Glitch in the normal way using whichever scope you require:
-
-```php
-try {
-    throw Glitch::{'ENotFound,EBadMethodCall'}(
-        "Didn't find a thing, couldn't call the other thing"
-    );
-} catch(\Exception | \EGlitch | \ENotFound | MyLibrary\EGlitch | MyLibrary\AThingThatDoesStuff\EBadMethodCall | BadMethodCallException $e) {
-    // All these types will catch
-    dd($e);
-}
-```
-
-
-### Traits
-
-Custom functionality can be mixed in to the generated Glitch automatically by defining traits at the same namespace level as any of the interfaces being implemented.
-
-```php
-namespace MyLibrary;
-
-trait EBadThingTrait {
-
-    public function getCustomData(): ?string {
-        return $this->params['customData'] ?? null;
-    }
-}
-
-class Thing {
-    public function doAThing() {
-        throw Glitch::EBadThing('A bad thing happened', [
-            'customData' => 'My custom info'
-        ]);
-    }
-}
-```
-
-
-## Wrapping exceptions
-
-If you want to present a unified interface in your own libraries, you ideally need to ensure that the only exceptions you throw from your library are from your libraries namespace - exceptions thrown by third party libraries called by _your_ library may need to be wrapped to maintain namespace isolation.
-
-The old, long way:
-
-```php
-namespace My\Library;
-
-use Someone\Elses\Thing;
-
-class MyClass {
-    public function doSomething() {
-        $thing = new Thing();
-
-        try {
-            return $thing->doIt();
-        } catch(Someone\Elses\ThingException $e) {
-            throw new My\Library\ThingException($e->getMessage(), $e->getCode(), $e);
-        }
-    }
-}
-```
-
-Glitch offers a <code>contain()</code> method that will wrap your third party code and automatically convert any throw exceptions to Glitch exceptions from the primary stack frame and namespace of your library:
-
-```php
-namespace My\Library;
-
-use Someone\Elses\Thing;
-
-class MyClass {
-    public function doSomething() {
-        $thing = new Thing();
-
-        /*
-         * If doIt() throws an exception from Someone\Elses namespace, Glitch will
-         * wrap it and throw a Glitch exception from My\Library.
-         */
-        return Glitch::contain(function() use($thing) {
-            return $thing->doIt();
-        }, function($e) {
-            /*
-             * Optionally, you can send a second function to contain() inspect the source
-             * exception and return the required types for the output Glitch
-             */
-            if($e instanceof Someone\Elses\ThingException) {
-                return 'EThingGoneWrong';
-            } else {
-                return 'ERuntime';
-            }
-        });
-    }
-}
-```
-
-## Other information
-- [Rationale for Glitch Exceptions](docs/Rationale.md)
-- [An explanation of how the Glitch interface works](docs/HowItWorks.md)
+However, the <code>Dumpable</code> interface is provided by [glitch-support](https://github.com/decodelabs/glitch-support) package which contains only the bear essentials for libraries to provide support to Glitch without including the entire library as a dependency.
 
 
 ## Licensing

diff --git a/composer.json b/composer.json
@@ -12,19 +12,19 @@
         "php": "^7.2",
         "symfony/polyfill-mbstring": "^1.7",
 
-        "decodelabs/glitch-support": "^0.1",
-        "decodelabs/exceptional": "^0.2",
-        "decodelabs/veneer": "^0.5",
-        "decodelabs/enlighten": "^0.7",
+        "decodelabs/glitch-support": "^0.1.4",
+        "decodelabs/exceptional": "^0.2.6",
+        "decodelabs/veneer": "^0.5.3",
+        "decodelabs/enlighten": "^0.7.4",
 
         "psr/log": "^1.0",
         "components/jquery": "~3.3"
     },
     "require-dev": {
         "phpunit/phpunit": "^8",
-        "phpstan/phpstan": "^0.12.19",
+        "phpstan/phpstan": "^0.12.45",
         "phpstan/extension-installer": "^1.0",
-        "decodelabs/phpstan-decodelabs": "^0.3",
+        "decodelabs/phpstan-decodelabs": "^0.3.4",
 
         "symfony/var-dumper": "^4.3",
         "php-ds/php-ds": "~1.2"
@@ -34,14 +34,12 @@
             "DecodeLabs\\Glitch\\": "src/Glitch"
         },
         "files": [
-            "src/EGlitch.php",
-            "src/EGlitchTrait.php",
             "src/helpers.php"
         ]
     },
     "extra": {
         "branch-alias": {
-            "dev-develop": "0.15.x-dev"
+            "dev-develop": "0.16.x-dev"
         }
     }
 }
diff --git a/docs/HowItWorks.md b/docs/HowItWorks.md