Update docs, add test cases

Author: Enno Woortmann

docs/source/complexTypes/object.rst

@@ -93,12 +93,15 @@ Naming
 Naming of classes
 ^^^^^^^^^^^^^^^^^
 
-If the given main object in a JSON-Schema file contains a `$id` the id will be used as class name. Otherwise the name of the file will be used.
+If the given main object in a JSON-Schema file contains a `title`, the title will be used as class name.
+Otherwise, if an `$id` is present, the basename of the $id and as a last fallback the name of the file will be used.
 
 Naming of nested classes
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-For the class name of a nested class the `$id` property of the nested object is used. If the id property isn't present the property key will be prefixed with the parent class. If an object `Person` has a nested object `car` without a `$id` the class for car will be named **Person_Car**.
+For the class name of a nested class the `title` property (fallback to `$id`) of the nested object is used.
+If neither the title nor the $id property is present the property key will be prefixed with the parent class.
+If an object `Person` has a nested object `car` without a `title` and an `$id` the class for car will be named **Person_Car**.
 
 Property Name Normalization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/source/generic/references.rst

@@ -11,10 +11,20 @@ Supported reference types
 * relative reference based on the location on the file system to a complete file (example: `"$ref": "./../modules/myObject.json"`)
 * relative reference based on the location on the file system to an object by id (example: `"$ref": "./../modules/myObject.json#IdOfMyObject"`)
 * relative reference based on the location on the file system to an object by path (example: `"$ref": "./../modules/myObject.json#/definitions/myObject"`)
+* absolute reference based on the location on the file system to a complete file (example: `"$ref": "/modules/myObject.json"`)
+* absolute reference based on the location on the file system to an object by id (example: `"$ref": "/modules/myObject.json#IdOfMyObject"`)
+* absolute reference based on the location on the file system to an object by path (example: `"$ref": "/modules/myObject.json#/definitions/myObject"`)
 * network reference to a complete file (example: `"$ref": "https://my.domain.com/schema/modules/myObject.json"`)
 * network reference to an object by id (example: `"$ref": "https://my.domain.com/schema/modules/myObject.json#IdOfMyObject"`)
 * network reference to an object by path (example: `"$ref": "https://my.domain.com/schema/modules/myObject.json#/definitions/myObject"`)
 
+If an `$id` is present in the schema, the `$ref` will be resolved relative to the `$id` (except the `$ref` already is an absolute reference, e.g. a full URL).
+The behaviour of `$ref` resolving can be overwritten by implementing a custom **SchemaProviderInterface**, for example when you want to use network references behind an authorization.
+
+.. note::
+
+    For absolute local references, the default implementation traverses up the directory tree until it finds a matching file to find the project root
+
 Object reference
 ----------------
 

tests/Objects/ReferencePropertyTest.php

@@ -10,6 +10,7 @@
 use PHPModelGenerator\Exception\RenderException;
 use PHPModelGenerator\Exception\SchemaException;
 use PHPModelGenerator\Model\GeneratorConfiguration;
+use PHPModelGenerator\Model\Schema;
 use PHPModelGenerator\Tests\AbstractPHPModelGeneratorTestCase;
 use stdClass;
 
@@ -24,13 +25,12 @@ class ReferencePropertyTest extends AbstractPHPModelGeneratorTestCase
 
     /**
      * @dataProvider internalReferenceProvider
-     * @dataProvider notResolvedExternalReferenceProvider
      *
      * @throws FileSystemException
      * @throws RenderException
      * @throws SchemaException
      */
-    public function testNotResolvedReferenceThrowsAnException(string $reference): void
+    public function testNotResolvedInternalReferenceThrowsAnException(string $reference): void
     {
         $this->expectException(SchemaException::class);
         $this->expectExceptionMessageMatches(
@@ -57,16 +57,6 @@ public function externalReferenceProvider(): array
         ];
     }
 
-    public function notResolvedExternalReferenceProvider(): array
-    {
-        return [
-            'External non existing file' => ['../ReferencePropertyTest_external/notExisting'],
-            'External path reference in non existing file' => ['../ReferencePropertyTest_external/notExisting#person'],
-            'External non existing path reference' => ['../ReferencePropertyTest_external/library.json#/definitions/animal'],
-            'External non existing direct reference' => ['../ReferencePropertyTest_external/library.json#animal'],
-        ];
-    }
-
     /**
      * @dataProvider internalReferenceProvider
      * @dataProvider externalReferenceProvider
@@ -452,6 +442,47 @@ public function nestedReferenceProvider(): array
         ];
     }
 
+    /**
+     * @dataProvider nonResolvableExternalReferenceProvider
+     */
+    public function testNonResolvableExternalReference(string $id, string $reference): void
+    {
+        $this->expectException(SchemaException::class);
+        $this->expectExceptionMessageMatches(
+            sprintf('/Unresolved Reference %s#\/definitions\/family in file .*\.json/', str_replace('/', '\/', $reference)),
+        );
+
+        $this->generateClassFromFileTemplate('NestedExternalReference.json', [$id, $reference]);
+    }
+
+    public function nonResolvableExternalReferenceProvider(): array
+    {
+        $baseURL = 'https://raw.githubusercontent.com/wol-soft/php-json-schema-model-generator/master/tests/Schema/';
+
+        return [
+            'local reference - relative' => [
+                'NestedExternalReference.json',
+                '../ReferencePropertyTest_external/nonexistent.json',
+            ],
+            'local reference - context absolute' => [
+                'NestedExternalReference.json',
+                '/ReferencePropertyTest_external/nonexistent.json',
+            ],
+            'network reference - full URL' => [
+                'NestedExternalReference.json',
+                $baseURL . 'ReferencePropertyTest_external/nonexistent.json',
+            ],
+            'network reference - relative path to full URL $id' => [
+                $baseURL . 'ReferencePropertyTest/NestedExternalReference.json',
+                '../ReferencePropertyTest_external/nonexistent.json',
+            ],
+            'network reference - absolute path to full URL $id' => [
+                $baseURL . 'ReferencePropertyTest/NestedExternalReference.json',
+                '/wol-soft/php-json-schema-model-generator/master/tests/Schema/ReferencePropertyTest_external/nonexistent.json',
+            ],
+        ];
+    }
+
     public function testInvalidBaseReferenceThrowsAnException(): void
     {
         $this->expectException(SchemaException::class);