Overview

The mini-eric-php SDK provides an object-oriented PHP wrapper around the CLI binaries for easy integration into PHP applications.

What is mini-eric-php?

mini-eric-php is a PHP SDK that wraps the ceric and cotto binaries, providing:

• Object-oriented interface for processing ELSTER XML documents

• Structured result objects with parsed error and hint information

• Automatic binary management with built-in validation

• Error handling with detailed error messages

• Easy integration into existing PHP applications

Key Features

• PHP 8.3+ support with modern syntax

• Type-safe with strict typing and comprehensive type hints

• Comprehensive testing with 100% test coverage

• PSR-4 autoloading for easy Composer integration

• Symfony Process integration for reliable process execution

• Error handling with parsed XML results

Installation

Install via Composer:

composer require rechtlogisch/mini-eric-php

Quick start

Basic Usage

<?php
use Rechtlogisch\MiniEric\Ceric;
use Rechtlogisch\MiniEric\Dto\CericInput;

$ceric = new Ceric();
$result = $ceric->draft(new CericInput(
    dataType: 'Kontoinformation',
    pathXml: '/path/to/info.xml',
));

// Check if processing was successful
if ($result->cericOutput->exitCode === '0') {
    echo "PDF generated: " . $result->cericOutput->pathOutputFile;
} else {
    echo "Error: " . $result->cericOutput->message;
}

Error Handling

$result = $ceric->draft($input);

// Check binary exit code
if ($result->cericOutput->exitCode !== '0') {
    echo "ceric exit code: " . $result->cericOutput->exitCode;
    return;
}

// Check ERiC processing result
if (!$result->ericProcessResult->success) {
    echo "ERiC processing failed:";
    foreach ($result->ericProcessResult->errors as $error) {
        echo "- " . $error->message . " (ID: " . $error->technicalId . ")";
    }
    return;
}

// Check for hints (warnings)
if (count($result->ericProcessResult->hints) > 0) {
    echo "Processing completed with hints:";
    foreach ($result->ericProcessResult->hints as $hint) {
        echo "- " . $hint->message . " (ID: " . $hint->technicalId . ")";
    }
}

Core Classes

Ceric

The main class for interacting with the ERiC binary.

$ceric = new Ceric(
    runner: new SymfonyProcessRunner(),     // Process runner (optional)
    binaryPath: '/custom/path/ceric',       // Custom binary path (optional)
    parser: new EricProcessResultParser(),  // Result parser (optional)
    validateBinary: true                    // Validate binary exists (optional)
);

Methods:

• draft(CericInput $input, ?string $cwd = null): Result - Validate and generate PDF preview

• send(CericInput $input, ?string $cwd = null): Result - Validate, transmit, and generate PDF confirmation

• transmit(CericInput $input, ?string $cwd = null): Result - Validate and transmit (no PDF)

• download(CottoInput $input, ?string $cwd = null): Result - Download data by UUID

• help(?string $cwd = null): Result - Get binary help

• version(?string $cwd = null): Result - Get binary version

Input DTOs

CericInput

Input DTO for ERiC operations.

$input = new CericInput(
    dataType: 'Kontoinformation',               // Required: Data type
    pathXml: '/path/to/info.xml',               // Required: Input XML file
    usecase: CericUsecase::DRAFT,               // Optional: Usecase (default: DRAFT)
    pathVendor: '/path/to/eric/plugins',        // Optional: ERiC plugins directory
    pathStorage: '/path/to/storage/',           // Optional: Storage directory
    timestamp: '202501011200450100'             // Optional: 18-digit timestamp for PDF footer and filename
);

CottoInput

Input DTO for download operations.

$input = new CottoInput(
    objectUuid: '41a42915-d8ba-45c7-89e6-6b875a853fc4',  // Required: Object UUID
    pathVendor: '/path/to/eric/plugins',                 // Optional: ERiC plugins directory
    pathStorage: '/path/to/storage/',                    // Optional: Download directory
    fileExtension: 'xml'                                 // Optional: File extension (default: xml)
);

Result Objects

Result

The main result object containing all operation data.

$result = $ceric->draft($input);

// Access different parts of the result
$cericOutput = $result->cericOutput;             // CericOutput: ceric binary response data
$ericProcessResult = $result->ericProcessResult; // EricProcessResult: Parsed XML errors/hints
$processRunResult = $result->processRunResult;   // ProcessRunResult: Raw process info

CericOutput

Contains the JSON response from the ceric binary:

$output = $result->cericOutput;
echo $output->exitCode;        // "0" for success
echo $output->message;         // Human-readable ceric message
echo $output->pathOutputFile;  // Path to generated PDF or retrieved file
echo $output->ericCode;        // ERiC error code
echo $output->ericMessage;     // ERiC error message
echo $output->processResult;   // Raw XML ERiC process result
echo $output->serverResponse;  // Raw XML ELSTER server response
echo $output->otherOutput;     // Other output by ceric (designated for debug)

EricProcessResult

Parsed XML result with structured error and hint information:

$process = $result->ericProcessResult;
echo $process->success;        // bool: true if no errors
echo count($process->errors);  // int: number of errors
echo count($process->hints);   // int: number of hints

// Access individual errors
foreach ($process->errors as $error) {
    echo $error->technicalId;  // Error technical ID
    echo $error->message;      // Error message
}

// Access individual hints
foreach ($process->hints as $hint) {
    echo $hint->technicalId;   // Hint technical ID
    echo $hint->message;       // Hint message
}

Usecases

1. Draft Validation

Validate XML document and generate PDF previews without transmission:

$result = $ceric->draft(new CericInput(
    dataType: 'Kontoinformation',
    pathXml: 'info.xml',
    pathStorage: '/path/to/storage/',
    timestamp: '202501011200450100'
));

if ($result->cericOutput->exitCode === '0') {
    echo "PDF created: " . $result->cericOutput->pathOutputFile;
}

2. Document Sending

Send document to ELSTER servers and create PDF:

$result = $ceric->send(new CericInput(
    dataType: 'Kontoinformation',
    pathXml: 'info.xml',
    pathStorage: '/path/to/storage/',
));

3. Document Transmission

Transmit document to ELSTER servers without creating a PDF:

$result = $ceric->transmit(new CericInput(
    dataType: 'Kontoinformation',
    pathXml: 'info.xml',
    pathStorage: '/path/to/storage/'
));

4. Data Download

Download data from OTTER server:

$result = $ceric->download(new CottoInput(
    objectUuid: '41a42915-d8ba-45c7-89e6-6b875a853fc4',
    pathStorage: '/path/to/storage/',
));

if ($result->cericOutput->exitCode === '0') {
    echo "Downloaded: " . $result->cericOutput->pathOutputFile;
}

Configuration

Custom Binary Path

$ceric = new Ceric(binaryPath: '/custom/path/ceric');

Disable Binary Validation

$ceric = new Ceric(validateBinary: false);

Custom Process Runner

use Rechtlogisch\MiniEric\Process\ProcessRunner;

class CustomRunner implements ProcessRunner
{
    public function run(array $command, ?string $cwd = null, array $env = []): ProcessRunResult
    {
        // Custom implementation
    }
}

$ceric = new Ceric(runner: new CustomRunner());

Next Steps

• Examples - Real-world usage examples