feat: initial release of PHP FHIR Tools

Multi-component toolkit for working with FHIR (Fast Healthcare Interoperability Resources) in PHP:

- CodeGeneration: Generate PHP model classes and enums from FHIR Structure Definitions
- Serialization: FHIR-compliant JSON/XML serialization and deserialization
- FHIRPath: FHIRPath expression evaluator
- FHIRBundle: Symfony Bundle integration with console commands
- Models: Pre-generated R4 model classes

Requires PHP 8.3+, Symfony 6.4, PHPStan level 8, PSR-12 compliant.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Ardenexal

.devcontainer/Dockerfile

@@ -0,0 +1,82 @@
+# Use official PHP 8.3 image with CLI and development tools
+FROM php:8.3-cli
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    libpng-dev \
+    libonig-dev \
+    libxml2-dev \
+    libzip-dev \
+    zip \
+    unzip \
+    wget \
+    gnupg2 \
+    software-properties-common \
+    ca-certificates \
+    lsb-release \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install PHP extensions required by the project
+RUN docker-php-ext-install \
+    ctype \
+    iconv \
+    zip \
+    intl \
+    mbstring \
+    xml
+
+# Install Xdebug for debugging and coverage
+RUN pecl install xdebug-3.3.1 \
+    && docker-php-ext-enable xdebug
+
+# Install Composer
+COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+
+# Create a non-root user
+ARG USERNAME=vscode
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+
+RUN groupadd --gid $USER_GID $USERNAME \
+    && useradd --uid $USER_UID --gid $USER_GID -m $USERNAME \
+    && apt-get update \
+    && apt-get install -y sudo \
+    && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
+    && chmod 0440 /etc/sudoers.d/$USERNAME
+
+# Set up Composer cache directory
+RUN mkdir -p /home/$USERNAME/.composer \
+    && chown -R $USERNAME:$USERNAME /home/$USERNAME/.composer
+
+# Install Node.js (useful for any frontend tooling)
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs
+
+# Install additional development tools
+RUN apt-get update && apt-get install -y \
+    vim \
+    nano \
+    htop \
+    tree \
+    jq \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /workspace
+
+# Switch to non-root user
+USER $USERNAME
+
+# Set up shell environment
+RUN echo 'export PATH="$PATH:/workspace/vendor/bin"' >> /home/$USERNAME/.bashrc \
+    && echo 'alias ll="ls -la"' >> /home/$USERNAME/.bashrc \
+    && echo 'alias la="ls -la"' >> /home/$USERNAME/.bashrc \
+    && echo 'alias phpunit="./vendor/bin/phpunit"' >> /home/$USERNAME/.bashrc \
+    && echo 'alias phpstan="./vendor/bin/phpstan.phar"' >> /home/$USERNAME/.bashrc \
+    && echo 'alias pint="./vendor/bin/pint"' >> /home/$USERNAME/.bashrc
+
+# Configure Git (will be overridden by user's git config)
+RUN git config --global init.defaultBranch main \
+    && git config --global pull.rebase false

.devcontainer/devcontainer.json

@@ -0,0 +1,101 @@
+{
+  "name": "PHP FHIRTools Development",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "php",
+  "workspaceFolder": "/workspace",
+  
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {
+      "ppa": true,
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "installDirectlyFromGitHubRelease": true,
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": true,
+      "configureZshAsDefaultShell": true,
+      "installOhMyZsh": true,
+      "upgradePackages": true,
+      "username": "vscode",
+      "userUid": "automatic",
+      "userGid": "automatic"
+    }
+  },
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "bmewburn.vscode-intelephense-client",
+        "xdebug.php-debug",
+        "zobo.php-intellisense",
+        "ms-vscode.vscode-json",
+        "redhat.vscode-yaml",
+        "bradlc.vscode-tailwindcss",
+        "formulahendry.auto-rename-tag",
+        "ms-azuretools.vscode-docker",
+        "eamodio.gitlens",
+        "github.copilot",
+        "github.copilot-chat",
+        "ms-vscode.test-adapter-converter",
+        "recca0120.vscode-phpunit",
+        "sanderronde.phpstan-vscode",
+        "open-southeners.laravel-pint"
+      ],
+      "settings": {
+        "php.validate.executablePath": "/usr/local/bin/php",
+        "php.debug.executablePath": "/usr/local/bin/php",
+        "intelephense.files.maxSize": 5000000,
+        "intelephense.telemetry.enabled": false,
+        "intelephense.format.enable": false,
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+          "source.fixAll": "explicit"
+        },
+        "files.associations": {
+          "*.php": "php",
+          "composer.lock": "json"
+        },
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "git.enableCommitSigning": true,
+        "phpunit.php": "/usr/local/bin/php",
+        "phpunit.phpunit": "./vendor/bin/phpunit",
+        "phpunit.args": [
+          "--configuration",
+          "phpunit.dist.xml"
+        ],
+        "phpstan.enabled": true,
+        "phpstan.path": "./vendor/bin/phpstan.phar",
+        "phpstan.configFile": "./phpstan.neon"
+      }
+    }
+  },
+
+  "forwardPorts": [8000, 9000, 9003],
+  "portsAttributes": {
+    "8000": {
+      "label": "Symfony Dev Server",
+      "onAutoForward": "notify"
+    },
+    "9000": {
+      "label": "PHP-FPM",
+      "onAutoForward": "silent"
+    },
+    "9003": {
+      "label": "Xdebug",
+      "onAutoForward": "silent"
+    }
+  },
+
+  "postCreateCommand": ".devcontainer/setup.sh",
+  "postStartCommand": "composer install --no-interaction",
+
+  "remoteUser": "vscode",
+  "containerUser": "vscode",
+
+  "mounts": [
+    "source=${localWorkspaceFolder}/.devcontainer/php.ini,target=/usr/local/etc/php/conf.d/99-custom.ini,type=bind",
+    "source=fhir-tools-composer-cache,target=/home/vscode/.composer,type=volume"
+  ]
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,40 @@
+version: '3.8'
+
+services:
+  php:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    volumes:
+      - ../:/workspace:cached
+      - composer-cache:/home/vscode/.composer
+    environment:
+      - APP_ENV=dev
+      - XDEBUG_MODE=develop,debug,coverage
+      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003 start_with_request=yes
+      - PHP_IDE_CONFIG=serverName=fhir-tools
+    command: sleep infinity
+    networks:
+      - fhir-tools
+
+  # Optional: Add a database if needed for future FHIR data storage
+  # postgres:
+  #   image: postgres:16-alpine
+  #   environment:
+  #     POSTGRES_DB: fhir_tools
+  #     POSTGRES_USER: fhir_user
+  #     POSTGRES_PASSWORD: fhir_password
+  #   volumes:
+  #     - postgres-data:/var/lib/postgresql/data
+  #   ports:
+  #     - "5432:5432"
+  #   networks:
+  #     - fhir-tools
+
+volumes:
+  composer-cache:
+  # postgres-data:
+
+networks:
+  fhir-tools:
+    driver: bridge

.devcontainer/php.ini

@@ -0,0 +1,60 @@
+; PHP Configuration for FHIRTools Development
+
+; Memory and execution limits
+memory_limit = 512M
+max_execution_time = 300
+max_input_time = 300
+
+; Error reporting for development
+display_errors = On
+display_startup_errors = On
+error_reporting = E_ALL
+log_errors = On
+error_log = /tmp/php_errors.log
+
+; File upload limits (for FHIR packages)
+upload_max_filesize = 100M
+post_max_size = 100M
+max_file_uploads = 20
+
+; Timezone
+date.timezone = UTC
+
+; Xdebug configuration
+xdebug.mode = develop,debug,coverage
+xdebug.start_with_request = yes
+xdebug.client_host = host.docker.internal
+xdebug.client_port = 9003
+xdebug.idekey = VSCODE
+xdebug.log = /tmp/xdebug.log
+xdebug.log_level = 0
+
+; Coverage settings
+xdebug.coverage_enable = 1
+
+; Profiling (disabled by default, enable when needed)
+; xdebug.profiler_enable = 0
+; xdebug.profiler_output_dir = /tmp
+
+; OPcache settings for development
+opcache.enable = 1
+opcache.enable_cli = 1
+opcache.memory_consumption = 128
+opcache.interned_strings_buffer = 8
+opcache.max_accelerated_files = 4000
+opcache.revalidate_freq = 2
+opcache.fast_shutdown = 1
+opcache.validate_timestamps = 1
+
+; Security settings
+expose_php = Off
+allow_url_fopen = On
+allow_url_include = Off
+
+; Session settings
+session.cookie_httponly = 1
+session.use_strict_mode = 1
+
+; Mbstring settings
+mbstring.language = English
+mbstring.encoding_translation = Off

.devcontainer/setup.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+
+# FHIRTools Development Container Setup Script
+set -e
+
+echo "🚀 Setting up PHP FHIRTools development environment..."
+
+# Make sure we're in the workspace directory
+cd /workspace
+
+# Install Composer dependencies if not already installed
+if [ ! -d "vendor" ]; then
+    echo "📦 Installing Composer dependencies..."
+    composer install --no-interaction --optimize-autoloader
+else
+    echo "✅ Composer dependencies already installed"
+fi
+
+# Set up Git hooks directory (if using)
+if [ -d ".git" ]; then
+    echo "🔧 Configuring Git..."
+    git config --local core.hooksPath .githooks 2>/dev/null || true
+fi
+
+# Create necessary directories
+echo "📁 Creating necessary directories..."
+mkdir -p output
+mkdir -p var/cache
+mkdir -p var/log
+mkdir -p coverage
+
+# Set proper permissions
+echo "🔐 Setting permissions..."
+chmod -R 755 bin/console 2>/dev/null || true
+chmod -R 777 var/ 2>/dev/null || true
+chmod -R 777 coverage/ 2>/dev/null || true
+
+# Verify PHP configuration
+echo "🔍 Verifying PHP configuration..."
+php -v
+php -m | grep -E "(xdebug|zip|ctype|iconv|intl)" || echo "⚠️  Some extensions may be missing"
+
+# Test Composer scripts
+echo "🧪 Testing Composer scripts..."
+composer run-script --list
+
+# Verify Symfony console
+echo "🎯 Testing Symfony console..."
+php bin/console --version
+
+# Run initial code quality checks
+echo "🔍 Running initial code quality checks..."
+if [ -f "vendor/bin/phpstan.phar" ]; then
+    echo "Running PHPStan..."
+    composer run phpstan || echo "⚠️  PHPStan found issues - check output above"
+else
+    echo "⚠️  PHPStan not found - run 'composer install' to install dev dependencies"
+fi
+
+if [ -f "vendor/bin/pint" ]; then
+    echo "Running Pint (code style)..."
+    composer run lint || echo "⚠️  Pint found style issues - check output above"
+else
+    echo "⚠️  Pint not found - run 'composer install' to install dev dependencies"
+fi
+
+# Display helpful information
+echo ""
+echo "🎉 Development environment setup complete!"
+echo ""
+echo "📋 Available commands:"
+echo "  composer run test          - Run PHPUnit tests"
+echo "  composer run test-coverage - Run tests with coverage"
+echo "  composer run phpstan       - Run static analysis"
+echo "  composer run lint          - Fix code style"
+echo "  php bin/console list       - List available console commands"
+echo "  php bin/console fhir:generate --help - FHIR generation help"
+echo ""
+echo "🐛 Debugging:"
+echo "  - Xdebug is configured on port 9003"
+echo "  - Set breakpoints in VS Code and start debugging"
+echo "  - Use 'Listen for Xdebug' configuration"
+echo ""
+echo "📁 Important directories:"
+echo "  - src/           - Source code"
+echo "  - tests/         - Test files"
+echo "  - output/        - Generated FHIR classes"
+echo "  - coverage/      - Test coverage reports"
+echo ""
+echo "Happy coding! 🚀"