Error handling.

src/Exceptions/AcceptDebugContext.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+/**
+ * @see AcceptsDebugContext
+ * @internal
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+trait AcceptDebugContext
+{
+    public ?Context $context = null;
+
+//    public function context(callable $code): self
+//    {
+//        $this->context ??= new Context();
+//        $code($this->context, $this);
+//        return $this;
+//    }
+
+    public function tag(string $key, mixed $value): self
+    {
+        $this->context ??= new Context();
+        $this->context->tag($key, $value);
+        return $this;
+    }
+
+    public function push(string $key, mixed $value): self
+    {
+        $this->context ??= new Context();
+        $this->context->push($key, $value);
+        return $this;
+    }
+}

src/Exceptions/AcceptsDebugContext.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+/**
+ * @internal
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+interface AcceptsDebugContext
+{
+//    public function context(callable $code): self;
+
+    public function tag(string $key, mixed $value): self;
+
+    public function push(string $key, mixed $value): self;
+}

src/Exceptions/ChildKeyCollision.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown when a child node is being added with a key that would overwrite another child with the same key.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class ChildKeyCollision extends RuntimeException implements FailsIntegrity, AcceptsDebugContext
+{
+    use AcceptDebugContext;
+}

src/Exceptions/ConfigurationIssue.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use LogicException;
+
+/**
+ * ConfigurationIssue
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class ConfigurationIssue extends LogicException implements FailsIntegrity
+{
+}

src/Exceptions/Context.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+/**
+ * Context meant for debugging issues.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class Context
+{
+    public array $bag = [];
+
+    public function tag(string $key, mixed $value): self
+    {
+        $this->bag[$key] = $value;
+        return $this;
+    }
+
+    public function push(string $key, mixed $value): self
+    {
+        if (!isset($this->bag[$key])) {
+            $this->bag[$key] = [];
+        }
+        $this->bag[$key][] = $value;
+        return $this;
+    }
+}

src/Exceptions/ExtractorReturnValueIssue.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use LogicException;
+
+/**
+ * A problem with return value of an extractor.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class ExtractorReturnValueIssue extends LogicException implements FailsIntegrity, AcceptsDebugContext
+{
+    use AcceptDebugContext;
+}

src/Exceptions/FailsIntegrity.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+/**
+ * Base interface for exceptions indicating a problem on the integration side,
+ * be it either a configuration issue or invalid source data.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+interface FailsIntegrity extends IndicatesTreeIssue
+{
+}

src/Exceptions/IndicatesInternalFault.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+/**
+ * Indicates internal logic fault.
+ * Implementors should never see these being thrown.
+ *
+ * @internal
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+interface IndicatesInternalFault extends IndicatesTreeIssue
+{
+
+}

src/Exceptions/IndicatesTreeIssue.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+/**
+ * Base exception interface for Oliva-specific exceptions.
+ * This can be used to catch all exceptions thrown by Oliva.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+interface IndicatesTreeIssue
+{
+
+}

src/Exceptions/InternalLogicException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use LogicException;
+
+/**
+ * Sorry.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class InternalLogicException extends LogicException implements IndicatesInternalFault
+{
+}

src/Exceptions/InvalidInputData.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Indicates invalid input data or argument.
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class InvalidInputData extends RuntimeException implements FailsIntegrity, AcceptsDebugContext
+{
+    use AcceptDebugContext;
+}

src/Exceptions/InvalidNodeFactoryReturnValue.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use Dakujem\Oliva\MovableNodeContract;
+use LogicException;
+use Throwable;
+
+/**
+ * Every node factory callable must return a movable node implementation instance, otherwise the builders can not work.
+ * @see MovableNodeContract
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class InvalidNodeFactoryReturnValue extends LogicException implements FailsIntegrity, AcceptsDebugContext
+{
+    use AcceptDebugContext;
+
+    public function __construct($message = null, $code = null, Throwable $previous = null)
+    {
+        parent::__construct(
+            $message ?? ('The node factory must return a movable node instance (' . MovableNodeContract::class . ').'),
+            $code ?? 0,
+            $previous,
+        );
+    }
+}

src/MaterializedPath/InvalidTreePath.php → src/Exceptions/InvalidTreePath.php

@@ -2,16 +2,18 @@
 
 declare(strict_types=1);
 
-namespace Dakujem\Oliva\MaterializedPath;
+namespace Dakujem\Oliva\Exceptions;
 
 use RuntimeException;
 use Throwable;
 
 /**
  * @author Andrej Rypak <xrypak@gmail.com>
  */
-final class InvalidTreePath extends RuntimeException
+final class InvalidTreePath extends RuntimeException implements FailsIntegrity, AcceptsDebugContext
 {
+    use AcceptDebugContext;
+
     public function __construct($message = null, $code = null, Throwable $previous = null)
     {
         parent::__construct($message ?? 'The given value is not a valid tree path.', $code ?? 0, $previous);

src/Exceptions/NodeNotMovable.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Dakujem\Oliva\Exceptions;
+
+use Dakujem\Oliva\MovableNodeContract;
+use LogicException;
+use Throwable;
+
+/**
+ * Builders can only work with movable nodes:
+ * @see MovableNodeContract
+ *
+ * @author Andrej Rypak <xrypak@gmail.com>
+ */
+final class NodeNotMovable extends LogicException implements IndicatesTreeIssue
+{
+    public mixed $node;
+
+    public function __construct(mixed $node, $message = null, $code = null, Throwable $previous = null)
+    {
+        $this->node = $node;
+        parent::__construct($message ?? 'Encountered a non-movable node while manipulating a tree.', $code ?? 0, $previous);
+    }
+}

src/MaterializedPath/Path.php

@@ -4,8 +4,9 @@
 
 namespace Dakujem\Oliva\MaterializedPath;
 
+use Dakujem\Oliva\Exceptions\ConfigurationIssue;
+use Dakujem\Oliva\Exceptions\InvalidTreePath;
 use Dakujem\Oliva\TreeNodeContract;
-use LogicException;
 
 /**
  * @author Andrej Rypak <xrypak@gmail.com>
@@ -24,7 +25,7 @@ final class Path
     public static function delimited(string $delimiter, callable $accessor): callable
     {
         if (strlen($delimiter) !== 1) {
-            throw new LogicException('The delimiter must be a single character.');
+            throw new ConfigurationIssue('The delimiter must be a single character.');
         }
         return function (mixed $data, mixed $inputIndex = null, ?TreeNodeContract $node = null) use (
             $delimiter,
@@ -35,8 +36,11 @@ public static function delimited(string $delimiter, callable $accessor): callabl
                 return [];
             }
             if (!is_string($path)) {
-                // TODO improve exceptions (index/path etc)
-                throw new InvalidTreePath('Invalid tree path returned by the accessor. A string is required.');
+                throw (new InvalidTreePath('Invalid tree path returned by the accessor. A string is required.'))
+                    ->tag('path', $path)
+                    ->tag('data', $data)
+                    ->tag('index', $inputIndex)
+                    ->tag('node', $node);
             }
             $path = trim($path, $delimiter);
             if ('' === $path) {
@@ -66,8 +70,11 @@ public static function fixed(int $levelWidth, callable $accessor): callable
                 return [];
             }
             if (!is_string($path)) {
-                // TODO improve exceptions (index/path etc)
-                throw new InvalidTreePath('Invalid tree path returned by the accessor. A string is required.');
+                throw (new InvalidTreePath('Invalid tree path returned by the accessor. A string is required.'))
+                    ->tag('path', $path)
+                    ->tag('data', $data)
+                    ->tag('index', $inputIndex)
+                    ->tag('node', $node);
             }
             return str_split($path, $levelWidth);
         };

src/MaterializedPath/Support/ShadowNode.php

@@ -4,6 +4,7 @@
 
 namespace Dakujem\Oliva\MaterializedPath\Support;
 
+use Dakujem\Oliva\Exceptions\InternalLogicException;
 use Dakujem\Oliva\MovableNodeContract;
 use Dakujem\Oliva\Node;
 use Dakujem\Oliva\TreeNodeContract;
@@ -58,15 +59,15 @@ public function realNode(): ?MovableNodeContract
     public function addChild(TreeNodeContract $child, string|int|null $key = null): self
     {
         if (!$child instanceof self) {
-            throw new LogicException('Invalid use of a shadow node. Only shadow nodes can be children of shadow nodes.');
+            throw new InternalLogicException('Invalid use of a shadow node. Only shadow nodes can be children of shadow nodes.');
         }
         return parent::addChild($child, $key);
     }
 
     public function setParent(?TreeNodeContract $parent): self
     {
         if (!$parent instanceof self) {
-            throw new LogicException('Invalid use of a shadow node. Only shadow nodes can be parents of shadow nodes.');
+            throw new InternalLogicException('Invalid use of a shadow node. Only shadow nodes can be parents of shadow nodes.');
         }
         return parent::setParent($parent);
     }