add comments, optimize tests for #125

Author: cebe

Makefile

@@ -41,11 +41,15 @@ install: composer.lock yarn.lock
 	$(DOCKER_PHP) composer install --prefer-dist --no-interaction --no-progress --ansi
 	$(DOCKER_NODE) yarn install
 
-test:
+test: unit test-recursion.json test-recursion2.yaml test-empty-maps.json
+
+unit:
 	$(DOCKER_PHP) php $(PHPARGS) $(XPHPARGS) vendor/bin/phpunit --verbose --colors=always $(TESTCASE)
-	$(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
+
+# 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

src/SpecBaseObject.php

@@ -190,8 +190,11 @@ public function getSerializableData()
             if ($v instanceof SpecObjectInterface) {
                 $data[$k] = $v->getSerializableData();
             } elseif (is_array($v)) {
+                // test if php arrays should be represented as object in YAML/JSON
                 $toObject = false;
                 if (!empty($v)) {
+                    // case 1: non-empty array should be an object if it does not contain
+                    // consecutive numeric keys
                     $j = 0;
                     foreach ($v as $i => $d) {
                         if ($j++ !== $i) {
@@ -202,7 +205,7 @@ public function getSerializableData()
                         }
                     }
                 } elseif (isset($this->attributes()[$k]) && is_array($this->attributes()[$k]) && 2 === count($this->attributes()[$k])) {
-                    // An empty Map, which is an empty array in PHP but needs to be an empty object in output.
+                    // case 2: Attribute type is an object (specified in attributes() by an array which specifies two items (key and value type)
                     $toObject = true;
                 }
                 if ($toObject) {