Merge branch 'master' into openapi-31

* master: (22 commits)
  Catch recursion when resolving inside included file
  Improve Responses resolving references
  Fixes default value for exclusiveMinimum and exclusiveMaximum
  more specific deprecation
  add hasPropertyValue() method
  add comments, optimize tests for #125
  During serialization convert empty Map fields to empty Objects
  Add test to demonstrate OpenAPI v3.0 schema validation fails with empty Path properties
  yarn upgrade
  Added docker environment for local development
  Add symfony 6 support (#151)
  Bump node-fetch from 2.6.1 to 2.6.7 (#149)
  Fix CI badge in Readme (#150)
  Temporarily skip broken test (#145)
  Run speccy through yarn
  Add windows and macos cases
  Temporarily skip broken test
  Rework CI
  Run all tests (#136)
  Drop licence badge from readme (#137)
  ...

Conflicts:
	README.md
	composer.json
	src/SpecBaseObject.php
	tests/ReaderTest.php

Author: cebe

.github/workflows/code-style.yml

@@ -0,0 +1,21 @@
+name: Code Style
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  code-style:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: 7.1
+
+      - name: Check code style
+        run: make check-style

.github/workflows/php.yml

@@ -1,4 +1,4 @@
-name: PHP Composer
+name: CI
 
 on:
   push:
@@ -7,35 +7,49 @@ on:
     branches: [ master, openapi-31 ]
 
 jobs:
-  build:
-
+  phpunit:
+    name: Tests
     strategy:
       fail-fast: false
       matrix:
-#        os: [ubuntu-latest, macos-latest, windows-latest]
         os: [ubuntu-latest]
-        php: ['7.1', '7.2', '7.3', '7.4', '8.0']
-        # max 4.4.16, see https://github.com/symfony/symfony/issues/39521
-        # max 5.1.8, see https://github.com/symfony/symfony/issues/39521
-        yaml: ['5.2.9', '5.1.11', '4.4.24', '^3.4']
+        php:
+          - "7.1"
+          - "7.2"
+          - "7.3"
+          - "7.4"
+          - "8.0"
+        dependencies:
+          - "lowest"
+          - "highest"
+        symfony-yaml: ['^3.4', '^4', '^5', '^6']
+        include:
+          - os: "windows-latest"
+            php: "8.0"
+            dependencies: "highest"
+            symfony-yaml: '5.4.2'
+          - os: "macos-latest"
+            php: "8.0"
+            dependencies: "highest"
+            symfony-yaml: '^5'
         exclude:
-          # Symfony YAML does not run on PHP 7.1
+          # symfony/yaml v5 does not run on PHP 7.1
           - php: '7.1'
-            yaml: '5.1.11'
+            symfony-yaml: '^5'
+          # symfony/yaml v6 does not run on PHP 7.*
           - php: '7.1'
-            yaml: '5.2.9'
-        include:
-          - php: '7.4'
-            os: windows-latest
-            yaml: '5.2.9'
+            symfony-yaml: '^6'
+          - php: '7.2'
+            symfony-yaml: '^6'
+          - php: '7.3'
+            symfony-yaml: '^6'
           - php: '7.4'
-            os: macos-latest
-            yaml: '5.2.9'
-
+            symfony-yaml: '^6'
+          # symfony/yaml v3.4 is not compatible with PHP 8.0 but has no upper-bound, so it installs on it
+          - php: '8.0'
+            symfony-yaml: '^3.4'
 
     runs-on: ${{ matrix.os }}
-    env:
-      YAML:  ${{ matrix.yaml }}
 
     steps:
       - uses: actions/checkout@v2
@@ -44,60 +58,22 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
-          ini-values: date.timezone='UTC'
           coverage: pcov
           tools: composer:v2
 
-      - name: Determine composer cache directory (Linux/MacOS)
-        if: matrix.os != 'windows-latest'
-        run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV
-
-      - name: Determine composer cache directory (Windows)
-        if: matrix.os == 'windows-latest'
-        run: echo "COMPOSER_CACHE_DIR=~\AppData\Local\Composer" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+      - name: Require specific symfony/yaml version
+        run: "composer require symfony/yaml:'${{ matrix.symfony-yaml }}' --prefer-dist --no-interaction --ansi --no-install"
 
-      - name: Cache dependencies installed with composer
-        uses: actions/cache@v2
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
         with:
-          path: ${{ env.COMPOSER_CACHE_DIR }}
-          key: php${{ matrix.php }}-os${{ matrix.os }}-yaml${{ matrix.yaml }}-composer-${{ hashFiles('**/composer.json') }}
-
-
-      - name: Validate composer.json and composer.lock
-        run: composer validate --ansi
-
-      - name: Install dependencies (Linux/MacOS)
-        if: matrix.os != 'windows-latest'
-        run: |
-          make install
-          composer require symfony/yaml:"${YAML}" --prefer-dist --no-interaction --ansi
-
-      - name: Install dependencies (Windows)
-        if: matrix.os == 'windows-latest'
-        run: |
-          composer install --prefer-dist --no-interaction --no-progress --ansi
-          composer require symfony/yaml:5.1.8 --prefer-dist --no-interaction --ansi
+          dependency-versions: "${{ matrix.dependencies }}"
 
       - name: Validate test data
-        if: matrix.os == 'ubuntu-latest'
         run: make lint
 
-      - name: PHP Stan analysis
-        if: matrix.os == 'ubuntu-latest'
-        run: make stan
-
-      - name: PHPUnit tests (Linux/MacOS)
-        if: matrix.os != 'windows-latest'
+      - name: PHPUnit tests
         run: make test
 
-      - name: PHPUnit tests (Windows)
-        if: matrix.os == 'windows-latest'
-        run: vendor/bin/phpunit --colors=always
-
-      - name: Check code style
-        if: matrix.os == 'ubuntu-latest'
-        run: make check-style
-
       - name: Code coverage
-        if: matrix.os == 'ubuntu-latest'
         run: make coverage

.github/workflows/phpstan.yml

@@ -0,0 +1,25 @@
+name: PHPStan
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  phpstan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "7.1"
+          tools: composer:v2
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
+
+      - name: PHPStan analysis
+        run: make stan

Makefile

@@ -6,34 +6,61 @@ ifeq ($(XDEBUG),1)
 XPHPARGS=-dzend_extension=xdebug.so -dxdebug.remote_enable=1 -dxdebug.remote_autostart=1
 endif
 
+# Run make with IN_DOCKER=1 to run yarn and php commands in a docker container
+DOCKER_PHP=
+DOCKER_NODE=
+IN_DOCKER=0
+ifeq ($(IN_DOCKER),1)
+DOCKER_PHP=docker-compose run --rm php
+DOCKER_NODE=docker-compose run --rm -w /app node
+endif
+
 all:
+	@echo "the following commands are available:"
+	@echo ""
+	@echo "make check-style              # check code style"
+	@echo "make fix-style                # fix code style"
+	@echo "make install                  # install dependencies"
+	@echo "make test                     # run PHPUnit tests"
+	@echo "make lint                     # check validity of test data"
+	@echo "make stan                     # check code with PHPStan"
+	@echo ""
+	@echo "You may add the IN_DOCKER parameter to run a command inside of docker container and not directly."
+	@echo "make IN_DOCKER=1 ..."
+
 
 check-style: php-cs-fixer.phar
 	PHP_CS_FIXER_IGNORE_ENV=1 ./php-cs-fixer.phar fix src/ --diff --dry-run
 
 fix-style: php-cs-fixer.phar
-	vendor/bin/indent --tabs composer.json
-	vendor/bin/indent --spaces .php_cs.dist
-	./php-cs-fixer.phar fix src/ --diff
-
-install:
-	composer install --prefer-dist --no-interaction --no-progress --ansi
-	yarn install
-
-test:
-	php $(PHPARGS) $(XPHPARGS) vendor/bin/phpunit --verbose --colors=always $(TESTCASE)
-	php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/recursion.json
-	php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/recursion2.yaml
-
-lint:
-	php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/reference/playlist.json
-	php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/recursion.json
-	php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/recursion2.yaml
-	node_modules/.bin/speccy lint tests/spec/data/reference/playlist.json
-	node_modules/.bin/speccy lint tests/spec/data/recursion.json
+	$(DOCKER_PHP) vendor/bin/indent --tabs composer.json
+	$(DOCKER_PHP) vendor/bin/indent --spaces .php_cs.dist
+	$(DOCKER_PHP) ./php-cs-fixer.phar fix src/ --diff
+
+install: composer.lock yarn.lock
+	$(DOCKER_PHP) composer install --prefer-dist --no-interaction --no-progress --ansi
+	$(DOCKER_NODE) yarn install
+
+test: unit test-recursion.json test-recursion2.yaml test-recursion3_index.yaml test-empty-maps.json
+
+unit:
+	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) vendor/bin/phpunit --verbose --colors=always $(TESTCASE)
+
+# test specific JSON files in tests/spec/data/
+# e.g. test-recursion will run validation on tests/spec/data/recursion.json
+test-%: tests/spec/data/%
+	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate $<
+
+lint: install
+	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/reference/playlist.json
+	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/recursion.json
+	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/recursion2.yaml
+	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) bin/php-openapi validate tests/spec/data/empty-maps.json
+	$(DOCKER_NODE) yarn run speccy lint tests/spec/data/reference/playlist.json
+	$(DOCKER_NODE) yarn run speccy lint tests/spec/data/recursion.json
 
 stan:
-	php $(PHPARGS) vendor/bin/phpstan analyse -l 5 src
+	$(DOCKER_PHP) php $(PHPARGS) vendor/bin/phpstan analyse -l 5 src
 
 # copy openapi3 json schema
 schemas/openapi-v3.0.json: vendor/oai/openapi-specification-3.0/schemas/v3.0/schema.json

README.md

@@ -11,8 +11,7 @@ Supported OpenAPI versions:
 
 [![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://github.com/cebe/php-openapi/workflows/PHP%20Composer/badge.svg)](https://github.com/cebe/php-openapi/actions)
-[![License](https://poser.pugx.org/cebe/php-openapi/license)](https://packagist.org/packages/cebe/php-openapi)
+[![Build Status](https://github.com/cebe/php-openapi/workflows/CI/badge.svg)](https://github.com/cebe/php-openapi/actions)
 
 
 ## Install
@@ -200,9 +199,20 @@ references to structures in external files, we must provide the full context.
 
 ```php
 use cebe\openapi\Reader;
+use cebe\openapi\spec\OpenAPI;
+use cebe\openapi\ReferenceContext;
+
+// there are two different modes for resolving references:
+// ALL: resolve all references, which will result in a large description with a lot of repetition
+// but no references (except if there are recursive references, these will stop at some level)
+$mode = ReferenceContext::RESOLVE_MODE_ALL;
+// INLINE: only references to external files are resolved, references to places in the current file
+// are still Reference objects.
+$mode = ReferenceContext::RESOLVE_MODE_INLINE;
+
 // an absolute URL or file path is needed to allow resolving external references
-$openapi = Reader::readFromJsonFile('https://www.example.com/api/openapi.json');
-$openapi = Reader::readFromYamlFile('https://www.example.com/api/openapi.yaml');
+$openapi = Reader::readFromJsonFile('https://www.example.com/api/openapi.json', OpenAPI::class, $mode);
+$openapi = Reader::readFromYamlFile('https://www.example.com/api/openapi.yaml', OpenAPI::class, $mode);
 ```
 
 If data has been loaded in a different way you can manually resolve references like this by giving a context:
@@ -230,6 +240,15 @@ $errors = $openapi->getErrors();
 > but the list of errors given may not be complete. Also a passing validation does not necessarily indicate a completely
 > valid spec.
 
+# Development
+
+You may use the docker environment for local development:
+
+    docker-compose build
+    make IN_DOCKER=1 install
+    make IN_DOCKER=1 test
+    ...
+
 # Support
 
 **Need help with your API project?**

composer.json

@@ -20,8 +20,8 @@
 	"require": {
 		"php": ">=7.1.0",
 		"ext-json": "*",
-		"symfony/yaml": "^3.4 | ^4.0 | ^5.0",
-		"justinrainbow/json-schema": "^5.0"
+		"symfony/yaml": "^3.4 || ^4 || ^5 || ^6",
+		"justinrainbow/json-schema": "^5.2"
 	},
 	"require-dev": {
 		"cebe/indent": "*",
@@ -35,14 +35,17 @@
 		"nexmo/api-specification": "1.0.0",
 		"phpstan/phpstan": "^0.12.0"
 	},
+	"conflict": {
+		"symfony/yaml": "3.4.0 - 3.4.4 || 4.0.0 - 4.4.17 || 5.0.0 - 5.1.9 || 5.2.0"
+	},
 	"autoload": {
 		"psr-4": {
 			"cebe\\openapi\\": "src/"
 		}
 	},
 	"extra": {
 		"branch-alias": {
-			"dev-master": "1.5.x-dev"
+			"dev-master": "1.6.x-dev"
 		}
 	},
 	"bin": [

docker-compose.yml

@@ -0,0 +1,22 @@
+version: "3"
+services:
+    php:
+        build:
+            dockerfile: tests/docker/Dockerfile
+            context: .
+        volumes:
+            - ./tests/tmp/.composer:/root/.composer:rw
+            - .:/app
+        environment:
+            - TZ=UTC
+            - TIMEZONE=UTC
+            - IN_DOCKER=docker
+            - PHP_XDEBUG_ENABLED=1
+            - XDEBUG_CONFIG="remote_host=host.docker.internal"
+            - PHP_IDE_CONFIG="serverName=Docker"
+        tty: true
+    node:
+        image: node:12
+        volumes:
+#            - ./tests/tmp/.composer:/root/.composer:rw
+            - .:/app