allow settings context on references without resolving these

this gives better control over iterating the spec by keeping the
reference structure

Author: cebe

src/Reader.php

@@ -64,8 +64,9 @@ public static function readFromYaml(string $yaml, string $baseType = OpenApi::cl
     public static function readFromJsonFile(string $fileName, string $baseType = OpenApi::class, $resolveReferences = true): SpecObjectInterface
     {
         $spec = static::readFromJson(file_get_contents($fileName), $baseType);
+        $spec->setReferenceContext(new ReferenceContext($spec, $fileName));
         if ($resolveReferences) {
-            $spec->resolveReferences(new ReferenceContext($spec, $fileName));
+            $spec->resolveReferences();
         }
         return $spec;
     }
@@ -88,8 +89,9 @@ public static function readFromJsonFile(string $fileName, string $baseType = Ope
     public static function readFromYamlFile(string $fileName, string $baseType = OpenApi::class, $resolveReferences = true): SpecObjectInterface
     {
         $spec = static::readFromYaml(file_get_contents($fileName), $baseType);
+        $spec->setReferenceContext(new ReferenceContext($spec, $fileName));
         if ($resolveReferences) {
-            $spec->resolveReferences(new ReferenceContext($spec, $fileName));
+            $spec->resolveReferences();
         }
         return $spec;
     }

src/SpecBaseObject.php

@@ -246,7 +246,7 @@ public function __unset($name)
      * Resolves all Reference Objects in this object and replaces them with their resolution.
      * @throws exceptions\UnresolvableReferenceException in case resolving a reference fails.
      */
-    public function resolveReferences(ReferenceContext $context)
+    public function resolveReferences(ReferenceContext $context = null)
     {
         foreach ($this->_properties as $property => $value) {
             if ($value instanceof Reference) {
@@ -264,4 +264,26 @@ public function resolveReferences(ReferenceContext $context)
             }
         }
     }
+
+    /**
+     * Set context for all Reference Objects in this object.
+     */
+    public function setReferenceContext(ReferenceContext $context)
+    {
+        foreach ($this->_properties as $property => $value) {
+            if ($value instanceof Reference) {
+                $value->setContext($context);
+            } elseif ($value instanceof SpecObjectInterface) {
+                $value->setReferenceContext($context);
+            } elseif (is_array($value)) {
+                foreach ($value as $k => $item) {
+                    if ($item instanceof Reference) {
+                        $item->setContext($context);
+                    } elseif ($item instanceof SpecObjectInterface) {
+                        $item->setReferenceContext($context);
+                    }
+                }
+            }
+        }
+    }
 }

src/SpecObjectInterface.php

@@ -34,5 +34,10 @@ public function getErrors(): array;
     /**
      * Resolves all Reference Objects in this object and replaces them with their resolution.
      */
-    public function resolveReferences(ReferenceContext $context);
+    public function resolveReferences(ReferenceContext $context = null);
+
+    /**
+     * Set context for all Reference Objects in this object.
+     */
+    public function setReferenceContext(ReferenceContext $context);
 }

src/spec/Callback.php

@@ -82,10 +82,20 @@ public function getErrors(): array
      * Resolves all Reference Objects in this object and replaces them with their resolution.
      * @throws UnresolvableReferenceException
      */
-    public function resolveReferences(ReferenceContext $context)
+    public function resolveReferences(ReferenceContext $context = null)
     {
         if ($this->_pathItem !== null) {
             $this->_pathItem->resolveReferences($context);
         }
     }
+
+    /**
+     * Set context for all Reference Objects in this object.
+     */
+    public function setReferenceContext(ReferenceContext $context)
+    {
+        if ($this->_pathItem !== null) {
+            $this->_pathItem->setReferenceContext($context);
+        }
+    }
 }

src/spec/Paths.php

@@ -189,7 +189,7 @@ public function getIterator()
      * Resolves all Reference Objects in this object and replaces them with their resolution.
      * @throws UnresolvableReferenceException
      */
-    public function resolveReferences(ReferenceContext $context)
+    public function resolveReferences(ReferenceContext $context = null)
     {
         foreach ($this->_paths as $key => $path) {
             if ($path === null) {
@@ -198,4 +198,17 @@ public function resolveReferences(ReferenceContext $context)
             $path->resolveReferences($context);
         }
     }
+
+    /**
+     * Set context for all Reference Objects in this object.
+     */
+    public function setReferenceContext(ReferenceContext $context)
+    {
+        foreach ($this->_paths as $key => $path) {
+            if ($path === null) {
+                continue;
+            }
+            $path->setReferenceContext($context);
+        }
+    }
 }

src/spec/Reference.php

@@ -25,6 +25,7 @@ class Reference implements SpecObjectInterface
 {
     private $_to;
     private $_ref;
+    private $_context;
 
     private $_errors = [];
 
@@ -88,11 +89,36 @@ public function getReference()
 
     /**
      * @param ReferenceContext $context
+     */
+    public function setContext(ReferenceContext $context)
+    {
+        $this->_context = $context;
+    }
+
+    /**
+     * @return ReferenceContext
+     */
+    public function getContext() : ?ReferenceContext
+    {
+        return $this->_context;
+    }
+
+    /**
+     * Resolve this reference.
+     * @param ReferenceContext $context the reference context to use for resolution.
+     * If not specified, `getContext()` will be called to determine the context, if
+     * that does not return a context, the UnresolvableReferenceException will be thrown.
      * @return SpecObjectInterface the resolved spec type.
      * @throws UnresolvableReferenceException in case of errors.
      */
-    public function resolve(ReferenceContext $context)
+    public function resolve(ReferenceContext $context = null)
     {
+        if ($context === null) {
+            $context = $this->getContext();
+            if ($context === null) {
+                throw new UnresolvableReferenceException('No context given for resolving reference.');
+            }
+        }
         if (($pos = strpos($this->_ref, '#')) === 0) {
             // resolve in current document
             $jsonPointer = substr($this->_ref, 1);
@@ -111,7 +137,7 @@ public function resolve(ReferenceContext $context)
         /** @var $referencedObject SpecObjectInterface */
         $referencedObject = new $this->_to($referencedData);
         if ($jsonPointer === '') {
-            $referencedObject->resolveReferences(new ReferenceContext($referencedObject, $file));
+            $referencedObject->setReferenceContext(new ReferenceContext($referencedObject, $file));
         } else {
             // TODO resolving references recursively does not work as we do not know the base type of the file at this point
 //            $referencedObject->resolveReferences(new ReferenceContext($referencedObject, $file));
@@ -183,8 +209,17 @@ private function fetchReferencedFile($uri)
      * Resolves all Reference Objects in this object and replaces them with their resolution.
      * @throws UnresolvableReferenceException
      */
-    public function resolveReferences(ReferenceContext $context)
+    public function resolveReferences(ReferenceContext $context = null)
     {
         throw new UnresolvableReferenceException('Cyclic reference detected, resolveReferences() called on a Reference Object.');
     }
+
+    /**
+     * Set context for all Reference Objects in this object.
+     * @throws UnresolvableReferenceException
+     */
+    public function setReferenceContext(ReferenceContext $context)
+    {
+        throw new UnresolvableReferenceException('Cyclic reference detected, setReferenceContext() called on a Reference Object.');
+    }
 }

src/spec/Responses.php

@@ -185,7 +185,7 @@ public function getIterator()
      * Resolves all Reference Objects in this object and replaces them with their resolution.
      * @throws UnresolvableReferenceException
      */
-    public function resolveReferences(ReferenceContext $context)
+    public function resolveReferences(ReferenceContext $context = null)
     {
         foreach ($this->_responses as $k => $response) {
             if ($response instanceof Reference) {
@@ -195,4 +195,18 @@ public function resolveReferences(ReferenceContext $context)
             }
         }
     }
+
+    /**
+     * Set context for all Reference Objects in this object.
+     */
+    public function setReferenceContext(ReferenceContext $context)
+    {
+        foreach ($this->_responses as $k => $response) {
+            if ($response instanceof Reference) {
+                $response->setContext($context);
+            } else {
+                $response->setReferenceContext($context);
+            }
+        }
+    }
 }