Skip to content

Commit

Permalink
small updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcarbone
dcarbone committed Jan 14, 2025
1 parent b3034e9 commit 9b690a9
Show file tree
Hide file tree
Showing 3 changed files with 67 additions and 122 deletions.
103 changes: 2 additions & 101 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,108 +4,9 @@ Tools for creating PHP classes from the HL7 FHIR Specification
If you're looking to use the classes generated by this library, you may want the
[php-fhir-generated](https://github.com/dcarbone/php-fhir-generated) repo instead.

<!-- TOC -->
* [php-fhir](#php-fhir)
* [Install as Standalone Generator](#install-as-standalone-generator)
* [Install as Library](#install-as-library)
* [Version Table](#version-table)
* [Basic Usage](#basic-usage)
* [Class Generation](#class-generation)
* [Generation Example](#generation-example)
* [Data Querying](#data-querying)
* [Response Parsing](#response-parsing)
* [Parsing Example](#parsing-example)
* [Serialization](#serialization)
* [JSON Serialization](#json-serialization)
* [XML Serialization](#xml-serialization)
* [Testing](#testing)
* [TODO](#todo)
* [Suggestions and help](#suggestions-and-help)
<!-- TOC -->

# Install as Standalone Generator
If you wish to use this package as a standalone generator:

1. Check out the desired branch or tag
2. Execute `composer install` from root of project directory
3. Execute `./bin/generate.sh`
4. Answer all prompts
* If no custom configuration file is defined, definitions will be downloaded to `./input` and
classes will be generated under `./output`
* You can execute `./bin/generate.sh --help` for details on how to utilize this script
* You can configure various aspects of this script by altering the values in [./bin/config.php](./bin/config.php)

This script will download configured major versions of FHIR into the `input` folder and
generate classes for every version in the `output` folder.

# Install as Library
If you wish to use the generator as part of a project, you can include it as a composer
dependency:

```shell
composer require dcarbone/php-fhir
```

From there, you can reference the [Example](#generation-example) block for a quick example on how to
configure and execute the generator.

# Version Table

| PHPFHIR Version | PHP Versions | FHIR Versions |
|-----------------|--------------|----------------------------------|
| v2 | 5.4-7.4 | DSTU1, DSTU2, STU3, R4 (<v4.3.0) |
| v3 | 8.1+ | DSTU1, DSTU2, STU3, R4, R5 |

# Basic Usage

The first step is to determine the version of the FHIR spec your implementation supports. Once done, download
the appropriate class definition XSDs from [http://hl7.org/fhir/directory.html](http://hl7.org/fhir/directory.html).

Uncompress the XSD's and place them in a directory that is readable by PHP's runtime user.

Next comes the fun:

## Class Generation

The class generator utility included with this library is designed to parse the XSD's provided by the FHIR
group into PHP classes, complete with markup and type hinting.

There are 2 important things to note with this section:

1. Your exact implementation will probably vary, don't hesitate to ask if you need some help
2. The class generation should be run ONCE per FHIR version. Once the classes have been generated they should only
ever be re-generated if your server switches to a new FHIR spec

### Generation Example

You can view an example config array here: [bin/config.php](./bin/config.php).

```php
// first, build new configuration class
$config = new \DCarbone\PHPFHIR\Config(require 'config.php');

// if you wish to limit the versions generated to a subset of those configured:
// $config->setVersionsToGenerate(['DSTU2', 'STU3']);

// next, iterate through all configured versions and render code:
foreach ($config->getVersionsIterator() as $versionConfig) {
$versionConfig->getDefinition()->getBuilder()->render();
}
```

## Data Querying

Currently only a very simple client intended for debugging use is generated. A future goal is to generate a more
fully-featured client.

## Response Parsing

As part of the class generation above, a response parsing class called `PHPFHIRResponseParser` will be created
and added into the root namespace directory. It currently supports JSON and XML response types.
# Documentation

The parser class takes a single optional boolean argument that will determine if it should
attempt to load up the generated Autoloader class. By default it will do so, but you are free to configure your
own autoloader and not use the generated one if you wish.
Please refer to our wiki for the latest documentation: https://github.com/dcarbone/php-fhir/wiki

## Parsing Example

Expand Down
39 changes: 34 additions & 5 deletions src/Version/DefaultConfig.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,13 +57,28 @@ public function setUnserializeConfig(array $config): self
if ([] === $config) {
return $this;
}
if (isset($config['libxmlOpts']) && isset($config['libxmlOptMask'])) {
if (array_key_exists('libxmlOpts', $config) && array_key_exists('libxmlOptMask', $config)) {
throw new \DomainException('Cannot specify both "libxmlOpts" and "libxmlOptMask" keys.');
}
foreach (self::_UNSERIALIZE_CONFIG_KEYS as $k) {
if (isset($config[$k]) || array_key_exists($k, $config)) {
$this->_unserializeConfig[$k] = $config[$k];
if (!array_key_exists($k, $config)) {
continue;
}
$this->_unserializeConfig[$k] = match ($k) {
'libxmlOpts' => intval($config[$k]),
'libxmlOptMask' => is_string($config[$k]) && preg_match('{^[A-Z0-9_\s|]+}$}', $config[$k])
? $config[$k]
: throw new \InvalidArgumentException(sprintf(
'Value provided to "libxmlOptMask" is either not a string or is an invalid options mask: %s',
$config[$k],
)),
'jsonDecodeMaxDepth' => intval($config[$k]),

default => throw new \UnexpectedValueException(sprintf(
'Unknown unserialize config key "%s"',
$k,
))
};
}
return $this;
}
Expand All @@ -87,8 +102,22 @@ public function setSerializeConfig(array $config): self
return $this;
}
foreach (self::_SERIALIZE_CONFIG_KEYS as $k) {
if (isset($config[$k]) || array_key_exists($k, $config)) {
$this->_serializeConfig[$k] = $config[$k];
if (!array_key_exists($k, $config)) {
continue;
}
$this->_serializeConfig[$k] = match ($k) {
'overrideSourceXMLNS' => (bool)$config[$k],
'rootXMLNS' => null === $config[$k] ? null : (string)$config[$k],

default => throw new \UnexpectedValueException(sprintf(
'Unknown serialize config key "%s"',
$k,
))
};
if ($this->_serializeConfig['overrideSourceXMLNS'] ?? false) {
if (!isset($this->_serializeConfig['rootXMLNS']) || '' === $this->_serializeConfig['rootXMLNS']) {
throw new \DomainException('Must specify rootXMLNS if overrideSourceXMLNS is true');
}
}
}
return $this;
Expand Down
47 changes: 31 additions & 16 deletions template/core/class_autoloader.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,19 @@ abstract class <?php echo PHPFHIR_CLASSNAME_AUTOLOADER; ?>
{
private const _ROOT_NAMESPACE = '<?php echo $config->getFullyQualifiedName(false); ?>\\';

private const _VERSION_AUTOLOADER_MAP = [
<?php foreach($config->getVersionsIterator() as $i => $version): ?>
<?php echo $i; ?> => [
'<?php echo $version->getFullyQualifiedName(false); ?>\\',
'<?php echo $version->getFullyQualifiedName(false, PHPFHIR_CLASSNAME_AUTOLOADER); ?>',
<?php echo FileUtils::buildAutoloaderRelativeFilepath(
$config->getFullyQualifiedName(false),
$version->getFullyQualifiedName(false, PHPFHIR_CLASSNAME_AUTOLOADER),
); ?>,
],
<?php endforeach; ?>
];

private const _CORE_CLASS_MAP = [
// core types
<?php foreach($config->getCoreFiles()->getIterator() as $coreFile): if ($coreFile->isAutoloader() || $coreFile->isTest()) { continue; } ?>
Expand All @@ -47,10 +60,16 @@ abstract class <?php echo PHPFHIR_CLASSNAME_AUTOLOADER; ?>

private static bool $_registered = false;

private static array $_versionRegistered = [
<?php foreach($config->getVersionsIterator() as $i => $version) : ?>
<?php echo $i; ?> => false,
<?php endforeach; ?>
];

public static function register(): bool
{
if (!self::$_registered) {
self::$_registered = spl_autoload_register(__CLASS__ . '::loadClass', true);
self::$_registered = spl_autoload_register(__CLASS__ . '::loadClass');
}
return self::$_registered;
}
Expand All @@ -72,22 +91,18 @@ public static function loadClass(string $class): null|bool
return (bool)require self::_CORE_CLASS_MAP[$class];
} else if (!str_starts_with($class, self::_ROOT_NAMESPACE)) {
return null;
}<?php foreach($config->getVersionsIterator() as $version): ?> else if (str_starts_with($class, '<?php echo $version->getFullyQualifiedName(false); ?>\\')) {
if (!class_exists('<?php echo $version->getFullyQualifiedName(true, PHPFHIR_CLASSNAME_AUTOLOADER); ?>', false)) {
if (((bool)require <?php echo FileUtils::buildAutoloaderRelativeFilepath(
$config->getFullyQualifiedName(false),
$version->getFullyQualifiedName(false, PHPFHIR_CLASSNAME_AUTOLOADER),
); ?>) && <?php echo $version->getFullyQualifiedName(true, PHPFHIR_CLASSNAME_AUTOLOADER); ?>::register()) {
if ($class !== '<?php echo $version->getFullyQualifiedName(false, PHPFHIR_CLASSNAME_AUTOLOADER); ?>') {
return <?php echo $version->getFullyQualifiedName(true, PHPFHIR_CLASSNAME_AUTOLOADER); ?>::loadClass($class);
} else {
return true;
}
} else {
return false;
}
}<?php foreach($config->getVersionsIterator() as $i => $version): ?> else if (str_starts_with($class, self::_VERSION_AUTOLOADER_MAP[<?php echo $i; ?>][0])) {
if (self::$_versionRegistered[<?php echo $i; ?>]) {
return null;
}
require self::_VERSION_AUTOLOADER_MAP[<?php echo $i; ?>][2];
<?php echo $version->getFullyQualifiedName(true, PHPFHIR_CLASSNAME_AUTOLOADER); ?>::register();
self::$_versionRegistered[<?php echo $i; ?>] = true;
if ($class !== self::_VERSION_AUTOLOADER_MAP[<?php echo $i; ?>][1]) {
return <?php echo $version->getFullyQualifiedName(true, PHPFHIR_CLASSNAME_AUTOLOADER); ?>::loadClass($class);
} else {
return true;
}
return null;
}<?php endforeach; ?> else {
return null;
}
Expand Down

0 comments on commit 9b690a9

Please sign in to comment.