README

PHP client library for the EDU-DEX Data API. Framework-agnostic with optional SilverStripe integration.

Features

🎯 Complete API Coverage - All endpoints from the EDU-DEX OpenAPI specification
🔌 Framework Agnostic - Works with any PHP 8.1+ project
🔧 Optional SilverStripe Integration - Full Config API, Extensions, and Injector support
🎨 Clean Architecture - PSR-4 autoloading, typed models, endpoint classes
🛡️ Type Safe - PHP 8.1+ with strict type hints and return types
📦 Smart Models - Automatic hydration, serialization, and type casting
🌍 Localization - Built-in LocalizedString helper for multi-language content
✅ Validation - Pre-submission validation for programs, metadata, and discounts
🔐 Secure - Bearer token authentication with environment variable support
📝 Well Documented - Comprehensive PHPDoc blocks and usage examples

Installation

Install via Composer:

composer require restruct/edudex-api-client

Quick Start

Basic Usage (Any PHP Project)

<?php
require 'vendor/autoload.php';

use Restruct\EduDex\Client;

// Initialize with bearer token
$client = new Client('your-jwt-bearer-token');

// Or use environment variable EDUDEX_API_TOKEN
$client = new Client();

// Fetch organizations
$organizations = $client->organizations()->list();

foreach ($organizations as $org) {
    echo $org->getLocalizedName('nl') . "\n";
}

Configuration

use Restruct\EduDex\Client;

// From array
$config = [
    'bearer_token' => 'your-token',
    'api_base_url' => 'https://api.edudex.nl/data/v1/',
    'timeout' => 30,
];
$client = Client::fromConfig($config);

// From environment variable
// Set EDUDEX_API_TOKEN in your .env file
$client = new Client();

Usage Examples

Working with Organizations

use Restruct\EduDex\Client;

$client = new Client();

// List all organizations
$organizations = $client->organizations()->list();

// Get specific organization
$org = $client->organizations()->get('organization-id');

echo "Name: " . $org->getLocalizedName('nl') . "\n";
echo "Roles: " . implode(', ', $org->roles) . "\n";
echo "Supplier: " . ($org->isSupplier() ? 'Yes' : 'No') . "\n";

// Working with catalogs
$catalogs = $client->organizations()->listStaticCatalogs('org-id');

foreach ($catalogs as $catalog) {
    echo "{$catalog->title}: {$catalog->countActive}/{$catalog->countTotal} programs\n";
}

Managing Programs

// List programs for a supplier
$programs = $client->suppliers()->listPrograms('supplier-id');

// Get specific program
$program = $client->suppliers()->getProgram('supplier-id', 'program-id', 'client-id');

echo "Title: " . $program->getTitle('nl') . "\n";
echo "Description: " . $program->getDescription('en') . "\n";

// Create or update program
$programData = [
    'editor' => 'Admin User',
    'format' => 'application/vnd.edudex.program+json',
    'generator' => 'My CMS v1.0',
    'lastEdited' => date('c'),
    'programDescriptions' => [
        'title' => ['nl' => 'Cursus Titel', 'en' => 'Course Title'],
    ],
    // ... additional program data
];

$client->suppliers()->upsertProgram('supplier-id', 'program-id', 'client-id', $programData);

Validating Data

// Validate program before submission
$result = $client->validations()->validateProgram($programData);

if ($result->isValid()) {
    echo "✓ Validation passed!\n";

    // Submit the program
    $client->suppliers()->upsertProgram(...);
} else {
    echo "✗ Validation failed:\n";

    foreach ($result->getErrors() as $error) {
        echo "  • {$error->message}";
        if ($error->contextPath) {
            echo " (at {$error->contextPath})";
        }
        echo "\n";
    }
}

Bulk Operations

// Fetch multiple programs at once
$programsToFetch = [
    ['orgUnitId' => 'supplier-1', 'programId' => 'prog-1', 'clientId' => 'public'],
    ['orgUnitId' => 'supplier-2', 'programId' => 'prog-2', 'clientId' => 'client-1'],
];

$response = $client->programs()->bulk($programsToFetch);

// Process results
$successful = $client->programs()->getSuccessful($response);
$failed = $client->programs()->getFailed($response);

echo "Retrieved " . count($successful) . " programs\n";
echo "Failed: " . count($failed) . " programs\n";

Error Handling

use Restruct\EduDex\Exceptions\AuthenticationException;
use Restruct\EduDex\Exceptions\ValidationException;
use Restruct\EduDex\Exceptions\ApiException;
use Restruct\EduDex\Exceptions\EduDexException;

try {
    $org = $client->organizations()->get('org-id');

} catch (AuthenticationException $e) {
    // Handle 401/403 errors
    echo "Authentication error: {$e->getMessage()}\n";

} catch (ValidationException $e) {
    // Handle validation errors with detailed messages
    foreach ($e->getErrors() as $error) {
        echo "Error: {$error['message']}\n";
    }

} catch (ApiException $e) {
    // Handle other API errors
    echo "API error: {$e->getMessage()}\n";

} catch (EduDexException $e) {
    // Catch-all
    echo "Error: {$e->getMessage()}\n";
}

SilverStripe Integration

For SilverStripe projects, use the optional integration layer:

composer require restruct/edudex-api-client
composer require silverstripe/framework:^5.0

Configuration

Add to app/_config/edudex.yml:

---
Name: app-edudex
---

# SilverStripe Client configuration (optional)
Restruct\EduDex\Integration\SilverStripe\SilverStripeClient:
  api_base_url: 'https://api.edudex.nl/data/v1/'
  timeout: 30

# Configure Injector
SilverStripe\Core\Injector\Injector:
  Restruct\EduDex\Client:
    class: Restruct\EduDex\Integration\SilverStripe\SilverStripeClient

# Add CMS integration
SilverStripe\SiteConfig\SiteConfig:
  extensions:
    - Restruct\EduDex\Integration\SilverStripe\Extensions\SiteConfigExtension

Usage in SilverStripe

use Restruct\EduDex\Integration\SilverStripe\SilverStripeClient;

// Using singleton
$client = SilverStripeClient::singleton();

// Or via Injector
$client = Injector::inst()->get(SilverStripeClient::class);

// Same API as standalone
$organizations = $client->organizations()->list();

See docs/SILVERSTRIPE_INTEGRATION.md for complete documentation.

API Reference

Endpoints

Organizations - Manage organizations, catalogs, and webhooks
Suppliers - Supplier management, programs, discounts, metadata
Accreditors - Accreditor management and accreditations
Programs - Bulk program operations
Validations - Validate programs, metadata, and discounts

Models

Organization - Organization with roles and accreditations
Supplier - Training provider
Accreditor - Accreditation organization
Accreditation - Supplier accreditation with validity
StaticCatalog - Manual program catalog
DynamicCatalog - Automatic catalog with filters
Webhook - Event notification endpoint
Program - Training program/course
ValidationResult - Validation response

Type Helpers

LocalizedString - Multi-language content handler
ValidationMessage - Validation message with severity

Exceptions

EduDexException - Base exception
AuthenticationException - 401/403 errors
ValidationException - 400 validation errors
ApiException - Other HTTP errors

Documentation

Standalone Usage Guide - Complete guide for non-SilverStripe projects
SilverStripe Integration - SilverStripe-specific setup and usage
Implementation Details - Technical implementation overview
Working Examples - Ready-to-run code examples

Requirements

PHP 8.1 or higher (PHP 7.4 version in backport branch)
GuzzleHTTP ^7.0
PSR-3 Logger interface

Optional:

SilverStripe Framework ^5.0 (for SilverStripe integration)

Testing

# Install dev dependencies
composer install

# Run tests
composer test

# Run static analysis
composer phpstan

# Check code style
composer cs-check

# Fix code style
composer cs-fix

Support

Issues: https://github.com/restruct/edudex-api-client/issues
EDU-DEX Data API Documentation: https://api.edudex.nl/data/v1/
EDU-DEX Data API in Swagger: https://api.edudex.nl/data/v1/openapi/swagger-ui
EDUDOX: https://www.edudex.nl/edudox/
API Getting started: https://mijn.edudex.nl/api-getting-started/

License

This library is open-sourced software licensed under the MIT license.

Credits

Michael van Schaik (Restruct.nl) - development
Bart van Irsel (Webium) - AI consultant/guru
Claude (Anthropic) - AI co-author and code generation
EDU-DEX API by WebHare BV

restruct / edudex-api-client

Maintainers

Details

README

Features

Installation

Quick Start

Basic Usage (Any PHP Project)

Configuration

Usage Examples

Working with Organizations

Managing Programs

Validating Data

Bulk Operations

Error Handling

SilverStripe Integration

Configuration

Usage in SilverStripe

API Reference

Endpoints

Models

Type Helpers

Exceptions

Documentation

Requirements

Testing

Support

License

Credits