Merge pull request #9 from Rican7/feature/null-safe-context

Feature - Null safe context

src/Incoming/Hydrator/AbstractDelegateContextualBuilder.php

@@ -22,6 +22,37 @@
 abstract class AbstractDelegateContextualBuilder extends AbstractDelegateBuilder implements ContextualBuilder
 {
 
+    /**
+     * Properties
+     */
+
+    /**
+     * Whether or not to provide a fallback empty context, when a `null` context
+     * is otherwise provided, to make processes simpler by not having to rely on
+     * null checks of the actual parameter before usage.
+     *
+     * @var bool
+     */
+    private $provide_fallback_context = false;
+
+
+    /**
+     * Methods
+     */
+
+    /**
+     * Constructor
+     *
+     * @param bool $provide_fallback_context Whether or not to provide a
+     *  fallback empty context, when a `null` context is otherwise provided, to
+     *  make processes simpler by not having to rely on null checks of the
+     *  actual parameter before usage.
+     */
+    protected function __construct(bool $provide_fallback_context = false)
+    {
+        $this->provide_fallback_context = $provide_fallback_context;
+    }
+
     /**
      * {@inheritdoc}
      *
@@ -34,6 +65,11 @@ public function build($incoming, Map $context = null)
     {
         $callable = $this->getDelegate();
 
+        if (null === $context && $this->provide_fallback_context) {
+            // Provide a non-null context so null checks aren't later required
+            $context = new Map();
+        }
+
         return $callable($incoming, $context);
     }
 }

src/Incoming/Hydrator/AbstractDelegateContextualBuilderHydrator.php

@@ -26,6 +26,37 @@ abstract class AbstractDelegateContextualBuilderHydrator extends AbstractDelegat
     ContextualHydrator
 {
 
+    /**
+     * Properties
+     */
+
+    /**
+     * Whether or not to provide a fallback empty context, when a `null` context
+     * is otherwise provided, to make processes simpler by not having to rely on
+     * null checks of the actual parameter before usage.
+     *
+     * @var bool
+     */
+    private $provide_fallback_context = false;
+
+
+    /**
+     * Methods
+     */
+
+    /**
+     * Constructor
+     *
+     * @param bool $provide_fallback_context Whether or not to provide a
+     *  fallback empty context, when a `null` context is otherwise provided, to
+     *  make processes simpler by not having to rely on null checks of the
+     *  actual parameter before usage.
+     */
+    protected function __construct(bool $provide_fallback_context = false)
+    {
+        $this->provide_fallback_context = $provide_fallback_context;
+    }
+
     /**
      * {@inheritdoc}
      *
@@ -38,6 +69,11 @@ public function build($incoming, Map $context = null)
     {
         $callable = $this->getDelegateBuilder();
 
+        if (null === $context && $this->provide_fallback_context) {
+            // Provide a non-null context so null checks aren't later required
+            $context = new Map();
+        }
+
         return $callable($incoming, $context);
     }
 
@@ -54,6 +90,11 @@ public function hydrate($incoming, $model, Map $context = null)
     {
         $callable = $this->getDelegateHydrator();
 
+        if (null === $context && $this->provide_fallback_context) {
+            // Provide a non-null context so null checks aren't later required
+            $context = new Map();
+        }
+
         return $callable($incoming, $model, $context);
     }
 }

src/Incoming/Hydrator/AbstractDelegateContextualHydrator.php

@@ -22,6 +22,37 @@
 abstract class AbstractDelegateContextualHydrator extends AbstractDelegateHydrator implements ContextualHydrator
 {
 
+    /**
+     * Properties
+     */
+
+    /**
+     * Whether or not to provide a fallback empty context, when a `null` context
+     * is otherwise provided, to make processes simpler by not having to rely on
+     * null checks of the actual parameter before usage.
+     *
+     * @var bool
+     */
+    private $provide_fallback_context = false;
+
+
+    /**
+     * Methods
+     */
+
+    /**
+     * Constructor
+     *
+     * @param bool $provide_fallback_context Whether or not to provide a
+     *  fallback empty context, when a `null` context is otherwise provided, to
+     *  make processes simpler by not having to rely on null checks of the
+     *  actual parameter before usage.
+     */
+    protected function __construct(bool $provide_fallback_context = false)
+    {
+        $this->provide_fallback_context = $provide_fallback_context;
+    }
+
     /**
      * {@inheritdoc}
      *
@@ -35,6 +66,11 @@ public function hydrate($incoming, $model, Map $context = null)
     {
         $callable = $this->getDelegate();
 
+        if (null === $context && $this->provide_fallback_context) {
+            // Provide a non-null context so null checks aren't later required
+            $context = new Map();
+        }
+
         return $callable($incoming, $model, $context);
     }
 }

src/Incoming/Hydrator/Exception/IncompatibleProcessException.php

@@ -0,0 +1,110 @@
+<?php
+/**
+ * Incoming
+ *
+ * @author    Trevor Suarez (Rican7)
+ * @copyright (c) Trevor Suarez
+ * @link      https://github.com/Rican7/incoming
+ * @license   MIT
+ */
+
+declare(strict_types=1);
+
+namespace Incoming\Hydrator\Exception;
+
+use Incoming\Hydrator\Builder;
+use Incoming\Hydrator\Hydrator;
+use Throwable;
+use UnexpectedValueException;
+
+/**
+ * An exception to be thrown when a hydrator or builder is incompatible with an
+ * expected process strategy, such as when a non-context-compatible hydrator is
+ * provided with a non-null context.
+ */
+class IncompatibleProcessException extends UnexpectedValueException
+{
+
+    /**
+     * Constants
+     */
+
+    /**
+     * The default exception message.
+     *
+     * @var string
+     */
+    const DEFAULT_MESSAGE = 'Provided or resolved process is not compatible';
+
+    /**
+     * The exception code for when context compatibility is required.
+     *
+     * @var int
+     */
+    const CODE_FOR_REQUIRED_CONTEXT_COMPATIBILITY = 1;
+
+    /**
+     * The exception code for when a hydrator is used as the process.
+     *
+     * @var int
+     */
+    const CODE_FOR_HYDRATOR = 2;
+
+    /**
+     * The exception code for when a builder is used as the process.
+     *
+     * @var int
+     */
+    const CODE_FOR_BUILDER = 4;
+
+    /**
+     * The message extension (appended to the default message) for when context
+     * compatibility is required.
+     *
+     * @var string
+     */
+    const MESSAGE_EXTENSION_FOR_REQUIRED_CONTEXT_COMPATIBILITY = ' due to requiring context compatibility';
+
+
+    /**
+     * Properties
+     */
+
+    /**
+     * The exception message.
+     *
+     * @var string
+     */
+    protected $message = self::DEFAULT_MESSAGE;
+
+
+    /**
+     * Methods
+     */
+
+    /**
+     * Create an exception instance for when context compatibility is required.
+     *
+     * @param object|null $process The incompatible process.
+     * @param int $code The exception code.
+     * @param Throwable|null $previous A previous exception used for chaining.
+     * @return static The newly created exception.
+     */
+    public static function forRequiredContextCompatibility(
+        $process = null,
+        int $code = self::CODE_FOR_REQUIRED_CONTEXT_COMPATIBILITY,
+        Throwable $previous = null
+    ): self {
+        if (self::CODE_FOR_REQUIRED_CONTEXT_COMPATIBILITY === $code) {
+            if ($process instanceof Hydrator) {
+                $code += self::CODE_FOR_HYDRATOR;
+            } elseif ($process instanceof Builder) {
+                $code += self::CODE_FOR_BUILDER;
+            }
+        }
+
+        $message = self::DEFAULT_MESSAGE . self::MESSAGE_EXTENSION_FOR_REQUIRED_CONTEXT_COMPATIBILITY;
+
+        return new static($message, $code, $previous);
+    }
+}