Merge remote-tracking branch 'origin/master' into feature/pass-objects

Author: SilverFire

.gitignore

@@ -1,5 +1,6 @@
 /vendor
 /composer.lock
 
+/node_modules
 
 /.php_cs.cache

.travis.yml

@@ -32,6 +32,7 @@ matrix:
 
 install: make install
 script:
+  - make lint
   - make test
   - if [[ $TRAVIS_PHP_VERSION = "7.3" || $TRAVIS_PHP_VERSION = "nightly" ]]; then true; else make check-style; fi
   - make coverage

Makefile

@@ -1,3 +1,6 @@
+TESTCASE=
+PHPARGS=
+#PHPARGS=-dzend_extension=xdebug.so -dxdebug.remote_enable=1
 
 all:
 
@@ -11,9 +14,16 @@ fix-style:
 
 install:
 	composer install --prefer-dist --no-interaction
+	yarn install
 
 test:
-	vendor/bin/phpunit
+	php $(PHPARGS) vendor/bin/phpunit $(TESTCASE)
+
+lint:
+	php $(PHPARGS) bin/php-openapi validate tests/spec/data/reference/playlist.json
+	php $(PHPARGS) bin/php-openapi validate tests/spec/data/recursion.json
+	node_modules/.bin/speccy lint tests/spec/data/reference/playlist.json
+	node_modules/.bin/speccy lint tests/spec/data/recursion.json
 
 # copy openapi3 json schema
 schemas/openapi-v3.0.json: vendor/oai/openapi-specification/schemas/v3.0/schema.json
@@ -32,5 +42,5 @@ coverage: .php-openapi-covA .php-openapi-covB
 .php-openapi-covB:
 	grep -rhPo '^class \w+' src/spec/ | awk '{print $$2}' |grep -v '^Type$$' | sort > $@
 
-.PHONY: all check-style fix-style install test coverage
+.PHONY: all check-style fix-style install test lint coverage
 

README.md

@@ -5,6 +5,7 @@ Read and write [OpenAPI](https://www.openapis.org/) 3.0.x YAML and JSON files an
 It also provides a CLI tool for validating and converting OpenAPI 3.0.x YAML and JSON files.
 
 [![Latest Stable Version](https://poser.pugx.org/cebe/php-openapi/v/stable)](https://packagist.org/packages/cebe/php-openapi)
+[![Total Downloads](https://poser.pugx.org/cebe/php-openapi/downloads)](https://packagist.org/packages/cebe/php-openapi)
 [![Build Status](https://travis-ci.org/cebe/php-openapi.svg?branch=master)](https://travis-ci.org/cebe/php-openapi)
 [![License](https://poser.pugx.org/cebe/php-openapi/license)](https://packagist.org/packages/cebe/php-openapi)
 
@@ -227,6 +228,8 @@ This library is currently work in progress, the following list tracks completene
 
 # Support
 
+**Need help with your API project?**
+
 Professional support, consulting as well as software development services are available:
 
 https://www.cebe.cc/en/contact

bin/php-openapi

@@ -8,6 +8,8 @@
  * @license https://github.com/cebe/php-openapi/blob/master/LICENSE
  */
 
+use cebe\openapi\ReferenceContext;
+
 $composerAutoload = [
     __DIR__ . '/../vendor/autoload.php', // standalone with "composer install" run
     __DIR__ . '/../../../autoload.php',  // script is installed as a composer binary
@@ -97,15 +99,21 @@ foreach($argv as $k => $arg) {
 switch ($command) {
     case 'validate':
 
+        $errors = [];
+
         $openApi = read_input($inputFile, $inputFormat);
+        $referenceContext = new ReferenceContext($openApi, $inputFile ? realpath($inputFile) : '');
+        $referenceContext->throwException = false;
+        $openApi->resolveReferences($referenceContext);
 
         // Validate
 
         $openApi->validate();
-        $errors = $openApi->getErrors();
+        $errors = array_merge($errors, $openApi->getErrors());
 
         $validator = new JsonSchema\Validator;
-        $validator->validate($openApi->getSerializableData(), (object)['$ref' => 'file://' . dirname(__DIR__) . '/schemas/openapi-v3.0.json']);
+        $openApiData = $openApi->getSerializableData();
+        $validator->validate($openApiData, (object)['$ref' => 'file://' . dirname(__DIR__) . '/schemas/openapi-v3.0.json']);
 
         if ($validator->isValid() && empty($errors)) {
             print_formatted("The supplied API Description \B\Gvalidates\C against the OpenAPI v3.0 schema.\n", STDERR);
@@ -115,13 +123,20 @@ switch ($command) {
         if (!empty($errors)) {
             print_formatted("\BErrors found while reading the API Description:\C\n", STDERR);
             foreach ($errors as $error) {
-                fwrite(STDERR, "- $error\n");
+                if (($openPos = strpos($error, '[')) !== false && ($closePos = strpos($error, ']')) !== false && $openPos < $closePos) {
+                    $error = escape_formatted(substr($error, 0, $openPos + 1)) . '\Y'
+                           . escape_formatted(substr($error, $openPos + 1, $closePos - $openPos - 1)) . '\C'
+                           . escape_formatted(substr($error, $closePos));
+                } else {
+                    $error = escape_formatted($error);
+                }
+                print_formatted("- " . $error . "\n", STDERR);
             }
         }
         if (!$validator->isValid()) {
             print_formatted("\BOpenAPI v3.0 schema violations:\C\n", STDERR);
             foreach ($validator->getErrors() as $error) {
-                print_formatted(sprintf("- [\Y%s\C] %s\n", $error['property'], $error['message']), STDERR);
+                print_formatted(sprintf("- [\Y%s\C] %s\n", escape_formatted($error['property']), escape_formatted($error['message'])), STDERR);
             }
         }
         exit(2);
@@ -130,6 +145,11 @@ switch ($command) {
     case 'convert':
 
         $openApi = read_input($inputFile, $inputFormat);
+        try {
+            $openApi->resolveReferences();
+        } catch (\cebe\openapi\exceptions\UnresolvableReferenceException $e) {
+            error("[\e[33m{$e->context}\e[0m] " . $e->getMessage());
+        }
 
         if ($outputFile === null) {
             if ($outputFormat === null) {
@@ -202,11 +222,12 @@ function read_input($inputFile, $inputFormat)
                 }
             }
             if ($inputFormat === 'json') {
-                $openApi = \cebe\openapi\Reader::readFromJsonFile(realpath($inputFile));
+                $openApi = \cebe\openapi\Reader::readFromJsonFile(realpath($inputFile), \cebe\openapi\spec\OpenApi::class, false);
             } else {
-                $openApi = \cebe\openapi\Reader::readFromYamlFile(realpath($inputFile));
+                $openApi = \cebe\openapi\Reader::readFromYamlFile(realpath($inputFile), \cebe\openapi\spec\OpenApi::class, false);
             }
         }
+        $openApi->setDocumentContext($openApi, new \cebe\openapi\json\JsonPointer(''));
     } catch (Symfony\Component\Yaml\Exception\ParseException $e) {
         error($e->getMessage());
         exit(1);
@@ -269,7 +290,7 @@ EOF
  * @return void
  */
 function error($message, $callback = null) {
-    print_formatted("\B\RError\C: " . $message . "\n", STDERR);
+    print_formatted("\B\RError\C: " . escape_formatted($message) . "\n", STDERR);
     if (is_callable($callback)) {
         call_user_func($callback);
     }
@@ -283,5 +304,10 @@ function print_formatted($string, $stream) {
             '\\R' => "\033[31m", // green
             '\\B' => "\033[1m", // bold
             '\\C' => "\033[0m", // clear
+            '\\\\' => '\\',
     ]));
 }
+
+function escape_formatted($string) {
+    return strtr($string, ['\\' => '\\\\']);
+}

package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "speccy": "^0.11.0"
+  }
+}

src/DocumentContextInterface.php

@@ -0,0 +1,40 @@
+<?php
+
+/**
+ * @copyright Copyright (c) 2018 Carsten Brandt <mail@cebe.cc> and contributors
+ * @license https://github.com/cebe/php-openapi/blob/master/LICENSE
+ */
+
+namespace cebe\openapi;
+
+use cebe\openapi\json\JsonPointer;
+
+/**
+ * Interface implemented by OpenAPI objects that provide functionality for context in the document.
+ *
+ * Allows an object to reference the base OpenAPI document as well as its own position inside of
+ * the document in form of a [JSON pointer](https://tools.ietf.org/html/rfc6901).
+ */
+interface DocumentContextInterface
+{
+    /**
+     * Provide context information to the object.
+     *
+     * Context information contains a reference to the base object where it is contained in
+     * as well as a JSON pointer to its position.
+     * @param SpecObjectInterface $baseDocument
+     * @param JsonPointer $jsonPointer
+     */
+    public function setDocumentContext(SpecObjectInterface $baseDocument, JsonPointer $jsonPointer);
+
+    /**
+     * @return SpecObjectInterface|null returns the base document where this object is located in.
+     * Returns `null` if no context information was provided by [[setDocumentContext]].
+     */
+    public function getBaseDocument(): ?SpecObjectInterface;
+    /**
+     * @return JsonPointer|null returns a JSON pointer describing the position of this object in the base document.
+     * Returns `null` if no context information was provided by [[setDocumentContext]].
+     */
+    public function getDocumentPosition(): ?JsonPointer;
+}

src/ReferenceContext.php

@@ -14,6 +14,11 @@
  */
 class ReferenceContext
 {
+    /**
+     * @var bool whether to throw UnresolvableReferenceException in case a reference can not
+     * be resolved. If `false` errors are added to the Reference Objects error list instead.
+     */
+    public $throwException = true;
     /**
      * @var SpecObjectInterface
      */

src/SpecBaseObject.php

@@ -7,9 +7,10 @@
 
 namespace cebe\openapi;
 
-use cebe\openapi\exceptions\ReadonlyPropertyException;
 use cebe\openapi\exceptions\TypeErrorException;
 use cebe\openapi\exceptions\UnknownPropertyException;
+use cebe\openapi\json\JsonPointer;
+use cebe\openapi\json\JsonReference;
 use cebe\openapi\spec\Reference;
 use cebe\openapi\spec\Type;
 
@@ -19,10 +20,15 @@
  * Implements property management and validation basics.
  *
  */
-abstract class SpecBaseObject implements SpecObjectInterface
+abstract class SpecBaseObject implements SpecObjectInterface, DocumentContextInterface
 {
     private $_properties = [];
     private $_errors = [];
+    private $_recursing = false;
+
+    private $_baseDocument;
+    private $_jsonPointer;
+
 
     /**
      * @return array array of attributes available in this object.
@@ -146,6 +152,12 @@ private function instantiate($type, $data)
      */
     public function getSerializableData()
     {
+        if ($this->_recursing) {
+            // return a reference
+            return (object) ['$ref' => JsonReference::createFromUri('', $this->getDocumentPosition())->getReference()];
+        }
+        $this->_recursing = true;
+
         $data = $this->_properties;
         foreach ($data as $k => $v) {
             if ($v instanceof SpecObjectInterface) {
@@ -166,6 +178,9 @@ public function getSerializableData()
                 }
             }
         }
+
+        $this->_recursing = false;
+
         return (object) $data;
     }
 
@@ -176,19 +191,36 @@ public function getSerializableData()
      */
     public function validate(): bool
     {
+        // avoid recursion to get stuck in a loop
+        if ($this->_recursing) {
+            return true;
+        }
+        $this->_recursing = true;
+        $valid = true;
         foreach ($this->_properties as $v) {
             if ($v instanceof SpecObjectInterface) {
-                $v->validate();
+                if (!$v->validate()) {
+                    $valid = false;
+                }
             } elseif (is_array($v)) {
                 foreach ($v as $item) {
                     if ($item instanceof SpecObjectInterface) {
-                        $item->validate();
+                        if (!$item->validate()) {
+                            $valid = false;
+                        }
                     }
                 }
             }
         }
+        $this->_recursing = false;
+
         $this->performValidation();
-        return \count($this->getErrors()) === 0;
+
+        if (!empty($this->_errors)) {
+            $valid = false;
+        }
+
+        return $valid;
     }
 
     /**
@@ -197,7 +229,21 @@ public function validate(): bool
      */
     public function getErrors(): array
     {
-        $errors = [$this->_errors];
+        // avoid recursion to get stuck in a loop
+        if ($this->_recursing) {
+            return [];
+        }
+        $this->_recursing = true;
+
+        if (($pos = $this->getDocumentPosition()) !== null) {
+            $errors = [
+                array_map(function ($e) use ($pos) {
+                    return "[{$pos->getPointer()}] $e";
+                }, $this->_errors)
+            ];
+        } else {
+            $errors = [$this->_errors];
+        }
         foreach ($this->_properties as $v) {
             if ($v instanceof SpecObjectInterface) {
                 $errors[] = $v->getErrors();
@@ -209,6 +255,9 @@ public function getErrors(): array
                 }
             }
         }
+
+        $this->_recursing = false;
+
         return array_merge(...$errors);
     }
 
@@ -331,4 +380,48 @@ public function setReferenceContext(ReferenceContext $context)
             }
         }
     }
+
+    /**
+     * Provide context information to the object.
+     *
+     * Context information contains a reference to the base object where it is contained in
+     * as well as a JSON pointer to its position.
+     * @param SpecObjectInterface $baseDocument
+     * @param JsonPointer $jsonPointer
+     */
+    public function setDocumentContext(SpecObjectInterface $baseDocument, JsonPointer $jsonPointer)
+    {
+        $this->_baseDocument = $baseDocument;
+        $this->_jsonPointer = $jsonPointer;
+
+        foreach ($this->_properties as $property => $value) {
+            if ($value instanceof DocumentContextInterface) {
+                $value->setDocumentContext($baseDocument, $jsonPointer->append($property));
+            } elseif (is_array($value)) {
+                foreach ($value as $k => $item) {
+                    if ($item instanceof DocumentContextInterface) {
+                        $item->setDocumentContext($baseDocument, $jsonPointer->append($property)->append($k));
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * @return SpecObjectInterface|null returns the base document where this object is located in.
+     * Returns `null` if no context information was provided by [[setDocumentContext]].
+     */
+    public function getBaseDocument(): ?SpecObjectInterface
+    {
+        return $this->_baseDocument;
+    }
+
+    /**
+     * @return JsonPointer|null returns a JSON pointer describing the position of this object in the base document.
+     * Returns `null` if no context information was provided by [[setDocumentContext]].
+     */
+    public function getDocumentPosition(): ?JsonPointer
+    {
+        return $this->_jsonPointer;
+    }
 }