Merge pull request #159 from dcarbone/feature/v4-client-updates

Feature/v4 client updates

Author: dcarbone

.github/workflows/tests.yaml

@@ -89,7 +89,7 @@ jobs:
     name: '${{ matrix.test-target }} - PHP ${{ matrix.php-version }} - PHPUnit ${{ matrix.phpunit-version }}'
     services:
       php-fhir-test-server:
-        image: dancarbone/php-fhir-test-server:latest
+        image: ghcr.io/dcarbone/php-fhir-test-server:latest
         ports:
           - '8080:8080'
     steps:

files/constants.php

@@ -87,28 +87,25 @@
 const PHPFHIR_CLASSNAME_AUTOLOADER = 'Autoloader';
 const PHPFHIR_CLASSNAME_VERSION_CONFIG = 'VersionConfig';
 const PHPFHIR_CLASSNAME_CONSTANTS = 'Constants';
+const PHPFHIR_CLASSNAME_FHIR_VERSION = 'FHIRVersion';
 
 // Core interface names
 const PHPFHIR_INTERFACE_VERSION = 'VersionInterface';
 const PHPFHIR_INTERFACE_VERSION_CONFIG = 'VersionConfigInterface';
 const PHPFHIR_INTERFACE_VERSION_TYPE_MAP = 'VersionTypeMapInterface';
 
-// Core enums
-const PHPFHIR_ENUM_VERSION = 'VersionEnum';
-
 // Core exceptions
 const PHPFHIR_EXCEPTION_CLIENT_ABSTRACT_CLIENT = 'AbstractClientException';
 const PHPFHIR_EXCEPTION_CLIENT_ERROR = 'ClientErrorException';
 const PHPFHIR_EXCEPTION_CLIENT_UNEXPECTED_RESPONSE_CODE = 'UnexpectedResponseCodeException';
 
 // Core types entities
 const PHPFHIR_TYPES_INTERFACE_TYPE = 'TypeInterface';
-const PHPFHIR_TYPES_INTERFACE_DSTU1_TYPE = 'DSTU1TypeInterface';
-const PHPFHIR_TYPES_INTERFACE_DSTU1_PRIMITIVE_CONTAINER_TYPE = 'DSTU1PrimitiveContainerTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_PRIMITIVE_TYPE = 'PrimitiveTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_ELEMENT_TYPE = 'ElementTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_PRIMITIVE_CONTAINER_TYPE = 'PrimitiveContainerTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_VALUE_CONTAINER_TYPE = 'ValueContainerTypeInterface';
+const PHPFHIR_TYPES_INTERFACE_RESOURCE_ID_TYPE = 'ResourceIDTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_RESOURCE_TYPE = 'ResourceTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_CONTAINED_TYPE = 'ContainedTypeInterface';
 const PHPFHIR_TYPES_INTERFACE_RESOURCE_CONTAINER_TYPE = 'ResourceContainerTypeInterface';
@@ -125,6 +122,7 @@
 const PHPFHIR_ENCODING_CLASSNAME_RESOURCE_PARSER = 'ResourceParser';
 const PHPFHIR_ENCODING_TRAIT_JSON_SERIALIZATION_OPTIONS = 'JSONSerializationOptionsTrait';
 const PHPFHIR_ENCODING_TRAIT_XML_SERIALIZATION_OPTIONS = 'XMLSerializationOptionsTrait';
+const PHPFHIR_ENCODING_ENUM_SERIALIZE_FORMAT = 'SerializeFormatEnum';
 
 // Core client entities
 const PHPFHIR_CLIENT_INTERFACE_CLIENT = 'ClientInterface';
@@ -135,19 +133,15 @@
 const PHPFHIR_CLIENT_CLASSNAME_RESPONSE_HEADERS = 'ResponseHeaders';
 const PHPFHIR_CLIENT_ENUM_HTTP_METHOD = 'HTTPMethodEnum';
 const PHPFHIR_CLIENT_ENUM_SORT_DIRECTION = 'SortDirectionEnum';
-const PHPFHIR_CLIENT_ENUM_RESPONSE_FORMAT = 'ResponseFormatEnum';
 
-// Version class names
+// Version core entities
 const PHPFHIR_VERSION_CLASSNAME_VERSION = 'Version';
 const PHPFHIR_VERSION_CLASSNAME_VERSION_CONSTANTS = 'VersionConstants';
 const PHPFHIR_VERSION_CLASSNAME_VERSION_TYPE_MAP = 'VersionTypeMap';
 const PHPFHIR_VERSION_CLASSNAME_VERSION_CLIENT = 'VersionClient';
-
-// Version interface names
 const PHPFHIR_VERSION_INTERFACE_VERSION_CONTAINED_TYPE = 'VersionContainedTypeInterface';
-
-// Version enums
-const PHPFHIR_VERSION_ENUM_VERSION_TYPES = 'VersionTypesEnum';
+const PHPFHIR_VERSION_ENUM_VERSION_RESOURCE_TYPE = 'VersionResourceTypeEnum';
+const PHPFHIR_VERSION_INTERFACE_RESOURCE_TYPE = 'VersionResourceTypeInterface';
 
 // Validation entities
 const PHPFHIR_VALIDATION_CLASSNAME_VALIDATOR = 'Validator';
@@ -165,9 +159,6 @@
 
 // Static test type, namespace, and class values.
 const PHPFHIR_TEST_CLASSNAME_CONSTANTS = PHPFHIR_CLASSNAME_CONSTANTS . 'Test';
-const PHPFHIR_TEST_CLASSNAME_AUTOLOADER = PHPFHIR_CLASSNAME_AUTOLOADER . 'Test';
-const PHPFHIR_TEST_CLASSNAME_TYPE_MAP = PHPFHIR_VERSION_CLASSNAME_VERSION_TYPE_MAP . 'Test';
-const PHPFHIR_TEST_CLASSNAME_VERSION_CONFIG = PHPFHIR_CLASSNAME_VERSION_CONFIG . 'Test';
 const PHPFHIR_TEST_ENCODING_CLASSNAME_UNSERIALIZE_CONFIG = PHPFHIR_ENCODING_CLASSNAME_UNSERIALIZE_CONFIG . 'Test';
 const PHPFHIR_TEST_ENCODING_CLASSNAME_SERIALIZE_CONFIG = PHPFHIR_ENCODING_CLASSNAME_SERIALIZE_CONFIG . 'Test';
 const PHPFHIR_TEST_ENCODING_CLASSSNAME_XML_WRITER = PHPFHIR_ENCODING_CLASSNAME_XML_WRITER . 'Test';
@@ -177,7 +168,8 @@
 const PHPFHIR_TEST_TRAIT_MOCK_TYPE_FIELDS = 'MockTypeFieldsTrait';
 const PHPFHIR_TEST_CLASSNAME_MOCK_STRING_PRIMITIVE_TYPE = 'MockStringPrimitiveType';
 const PHPFHIR_TEST_CLASSNAME_MOCK_ELEMENT_TYPE = 'MockElementType';
-const PHPFHIR_TEST_CLASSNAME_MOCK_PRIMITIVE_CONTAINER_TPYE = 'MockPrimitiveContainerType';
+const PHPFHIR_TEST_CLASSNAME_MOCK_PRIMITIVE_CONTAINER_TYPE = 'MockPrimitiveContainerType';
+const PHPFHIR_TEST_CLASSNAME_MOCK_RESOURCE_ID_TYPE = 'MockResourceIDType';
 const PHPFHIR_TEST_CLASSNAME_MOCK_RESOURCE_TYPE = 'MockResourceType';
 
 // Test constant names

src/Builder.php

@@ -108,7 +108,7 @@ public function writeFHIRVersionCoreEntities(string ...$versionNames): void
             }
 
             // write version core files
-            $this->writeCoreFiles($version->getCoreFiles(), ['version' => $version]);
+            $this->writeCoreFiles($version->getVersionCoreFiles(), ['version' => $version]);
 
             $log->endBreak("FHIR Version {$version->getName()} Core File Generation");
         }
@@ -190,7 +190,7 @@ public function writeFHIRVersionTestClasses(string ...$versionNames): void
 
             $log->startBreak(sprintf('FHIR Version %s Test Class Generation', $version->getName()));
 
-            $this->writeCoreFiles($version->getVersionTestFiles(), ['version' => $version]);
+            $this->writeCoreFiles($version->getVersionTestCoreFiles(), ['version' => $version]);
 
             $log->endBreak(sprintf('FHIR Version %s Test Class Generation', $version->getName()));
         }

src/Builder/Import.php

@@ -50,7 +50,7 @@ public function __construct(string $classname, string $namespace, string $aliasN
     /**
      * @return string
      */
-    public function getClassname(): string
+    public function getName(): string
     {
         return $this->_classname;
     }
@@ -87,7 +87,7 @@ public function getImportedName(): string
         if ($this->isAliased()) {
             return $this->getAliasName();
         }
-        return $this->getClassname();
+        return $this->getName();
     }
 
     /**
@@ -123,9 +123,9 @@ public function getUseStatement(): string
     {
         $use = "use {$this->getFullyQualifiedName(false)}";
         if ($this->isAliased()) {
-            $use .= " as {$this->getAliasName()}";
+            return $use . " as {$this->getAliasName()};";
         }
-        return $use . ";\n";
+        return $use . ';';
     }
 
     /**

src/Builder/Imports.php

@@ -35,6 +35,8 @@ class Imports implements \Countable
 
     /** @var \DCarbone\PHPFHIR\Builder\Import[] */
     private array $_imports = [];
+    /** @var bool */
+    private bool $_sorted = false;
 
     /** @var int */
     private int $_requiredImportCount = 0;
@@ -54,59 +56,87 @@ public function __construct(Config $config, string $localNamespace, string $loca
     /**
      * @param string $namespace Namespace of referenced entity
      * @param string $name Name of referenced entity
-     * @return \DCarbone\PHPFHIR\Builder\Imports
+     * @param null|string $alias Explicit alias to use
+     * @return \DCarbone\PHPFHIR\Builder\Import
      */
-    public function addImport(string $namespace, string $name): self
+    public function addImport(string $namespace, string $name, null|string $alias = null): Import
     {
         // ensure clean namespace value
         $namespace = trim($namespace, PHPFHIR_NAMESPACE_SEPARATOR);
 
-        // do not need to import sibling entities.
+        // do not need to explicitly import same-namespace entities.
         $requiresImport = ($namespace !== $this->_localNamespace);
+        if ($requiresImport) {
+            $this->_requiredImportCount++;
+        }
+
+        // check if one with the same name or explicit alias already exists.
+        $current = match ($alias) {
+            null => $this->_imports[$name] ?? null,
+            default => $this->_imports[$alias] ?? null,
+        };
 
-        if (isset($this->_imports[$name])) {
-            // if we have already seen this type, move on.
-            if ($this->_imports[$name]->getNamespace() === $namespace) {
-                return $this;
+        // if match found...
+        if ($current) {
+            // ...and is an exact match, return it
+            if ($current->getNamespace() === $namespace) {
+                return $current;
             }
-            // if there is a conflicting imported type here...
-            $aliasName = $this->_findNextAliasName($name);
-            $this->_imports[$aliasName] = new Import($name, $namespace, $aliasName, $requiresImport);
+
+            // otherwise, if alias was explicitly provided, bail out now as this indicates faulty logic somewhere
+            // along the line.
+            if (null !== $alias) {
+                throw new \LogicException(sprintf(
+                    'Explicit alias "%s" for type "%s" at namespace "%s" collides with alias for type "%s" at namespace "%s".',
+                    $alias,
+                    $name,
+                    $namespace,
+                    $current->getName(),
+                    $current->getNamespace(),
+                ));
+            }
+
+            // otherwise, find next available alias and create import
+            $import = new Import($name, $namespace, $this->_findNextAliasName($name), $requiresImport);
         } else if ($name === $this->_localName && $namespace != $this->_localNamespace) {
             // if the referenced type has the same name but exists in a different namespace, alias it.
-            $aliasName = $this->_findNextAliasName($name);
-            $this->_imports[$aliasName] = new Import($name, $namespace, $aliasName, $requiresImport);
+            $import = new Import($name, $namespace, $alias ?? $this->_findNextAliasName($name), $requiresImport);
         } else {
             // otherwise, go ahead and add to map.
-            $this->_imports[$name] = new Import($name, $namespace, '', $requiresImport);
+            $import = new Import($name, $namespace, $alias ?? '', $requiresImport);
         }
 
-        if ($requiresImport) {
-            $this->_requiredImportCount++;
-        }
+        // add new import to local map
+        $this->_sorted = false;
+        $this->_imports[$import->getImportedName()] = $import;
 
-        uasort(
-            $this->_imports,
-            function (Import $a, Import $b) {
-                return strnatcasecmp($a->getFullyQualifiedName(false), $b->getFullyQualifiedName(false));
-            }
-        );
+        return $import;
+    }
 
-        return $this;
+    /**
+     * Add specific core file to imported list with optional explicit alias.
+     *
+     * @param \DCarbone\PHPFHIR\CoreFile $coreFile
+     * @param string|null $alias
+     * @return \DCarbone\PHPFHIR\Builder\Import
+     */
+    public function addCoreFileImport(CoreFile $coreFile, null|string $alias = null): Import
+    {
+        return $this->addImport($coreFile->getFullyQualifiedNamespace(false), $coreFile->getEntityName(), $alias);
     }
 
-    public function addCoreFileImports(CoreFile ...$coreFile): self
+    public function addCoreFileImports(CoreFile ...$coreFiles): self
     {
-        foreach ($coreFile as $cf) {
-            $this->addImport($cf->getFullyQualifiedNamespace(false), $cf->getEntityName());
+        foreach ($coreFiles as $cf) {
+            $this->addCoreFileImport($cf);
         }
         return $this;
     }
 
     public function addCoreFileImportsByName(string ...$entityNames): self
     {
         foreach ($entityNames as $en) {
-            $this->addCoreFileImports(
+            $this->addCoreFileImport(
                 $this->_config->getCoreFiles()->getCoreFileByEntityName($en),
             );
         }
@@ -116,7 +146,7 @@ public function addCoreFileImportsByName(string ...$entityNames): self
     public function addVersionCoreFileImportsByName(Version $version, string ...$entityNames): self
     {
         foreach ($entityNames as $en) {
-            $coreFile = $version->getCoreFiles()->getCoreFileByEntityName($en);
+            $coreFile = $version->getVersionCoreFiles()->getCoreFileByEntityName($en);
             $this->addImport($coreFile->getNamespace(), $coreFile->getEntityName());
         }
         return $this;
@@ -135,6 +165,7 @@ public function addVersionTypeImports(Type ...$types): self
      */
     public function getIterator(): iterable
     {
+        $this->_sort();
         return new \ArrayIterator($this->_imports);
     }
 
@@ -168,8 +199,9 @@ public function getImportByType(Type $type): Import
      */
     public function getImportByClassAndNamespace(string $classname, string $namespace): null|Import
     {
+        $this->_sort();
         foreach ($this->_imports as $import) {
-            if ($import->getNamespace() === $namespace && $import->getClassname() === $classname) {
+            if ($import->getNamespace() === $namespace && $import->getName() === $classname) {
                 return $import;
             }
         }
@@ -208,4 +240,18 @@ private function _findNextAliasName(string $classname): string
         }
         return $aliasName;
     }
+
+    private function _sort(): void
+    {
+        if ($this->_sorted) {
+            return;
+        }
+        uasort(
+            $this->_imports,
+            function (Import $a, Import $b) {
+                return strnatcasecmp($a->getFullyQualifiedName(false), $b->getFullyQualifiedName(false));
+            }
+        );
+        $this->_sorted = true;
+    }
 }

src/Config.php

@@ -18,6 +18,7 @@
  * limitations under the License.
  */
 
+use DCarbone\PHPFHIR\Config\VersionConfig;
 use DCarbone\PHPFHIR\Utilities\FileUtils;
 use DCarbone\PHPFHIR\Utilities\NameUtils;
 use Psr\Log\LoggerAwareInterface;
@@ -76,7 +77,7 @@ class Config implements LoggerAwareInterface
 
     /**
      * @param string $libraryPath
-     * @param iterable $versions
+     * @param array[]|\DCarbone\PHPFHIR\Config\VersionConfig[] $versions Array of VersionConfig maps or intsances.
      * @param string $libraryNamespacePrefix
      * @param null|string $testsPath
      * @param string $testNamespacePrefix
@@ -149,11 +150,11 @@ public static function fromArray(array $data): Config
         if (!isset($data['libraryPath'])) {
             throw new \InvalidArgumentException('Key "libraryPath" is required.');
         }
-        if (isset($data['versions']) && !is_iterable($data['versions'])) {
+        if (!isset($data['versions']) || !is_iterable($data['versions'])) {
             throw new \InvalidArgumentException('Key "versions" must be iterable.');
         }
         if (isset($data['logger']) && !($data['logger'] instanceof LoggerInterface)) {
-            throw new \InvalidArgumentException('Key "logger" must be an instance of Psr\Log\LoggerInterface');
+            throw new \InvalidArgumentException(sprintf('Key "logger" must be undefined or be an instance of %s', LoggerInterface::class));
         }
         return new Config(
             libraryPath: $data['libraryPath'],
@@ -257,27 +258,17 @@ public function setLibraryNamespacePrefix(string $libraryNamespacePrefix): self
     }
 
     /**
-     * @param array|\DCarbone\PHPFHIR\Version $version
+     * @param array|\DCarbone\PHPFHIR\Config\VersionConfig $versionConfig
      * @return self
      */
-    public function addVersion(array|Version $version): self
+    public function addVersion(array|VersionConfig $versionConfig): self
     {
-        if (is_array($version)) {
-            if (!isset($version['name'])) {
-                throw new \InvalidArgumentException('Version name is required');
-            }
-            if (!isset($version['schemaPath'])) {
-                throw new \InvalidArgumentException('Path to schemas for version is required');
-            }
-            $version = new Version(
-                config: $this,
-                name: $version['name'],
-                schemaPath: $version['schemaPath'],
-                namespace: $version['namespace'] ?? null,
-                defaultConfig: $version['defaultConfig'] ?? null,
-            );
+        if (is_array($versionConfig)) {
+            $versionConfig = VersionConfig::fromArray($versionConfig);
         }
 
+        $version = new Version(config: $this, versionConfig: $versionConfig);
+
         // ensure unique version name
         if (isset($this->_versions[$version->getName()])) {
             throw new \InvalidArgumentException(sprintf('Version "%s" has already been added.', $version->getName()));
@@ -301,7 +292,7 @@ public function addVersion(array|Version $version): self
     }
 
     /**
-     * @param iterable<array|\DCarbone\PHPFHIR\Version> $versions Iterable containing Versions or Version configuration maps.
+     * @param iterable<array|\DCarbone\PHPFHIR\Config\VersionConfig> $versions
      * @return self
      */
     public function setVersions(iterable $versions): self