README

A comprehensive PHP package for interacting with Greece's ERGANI II system, enabling automated submissions for employee data including work cards, hiring declarations, terminations, and more.

Features

• Work Cards - Employee check-in/check-out submissions
• Work Time Declarations - Daily and weekly work schedules
• Hiring Forms (E3) - New hires, modifications, deletions, and lending arrangements
• Internship Declarations (E3.5) - Internship and practical training submissions
• Termination Forms (E5) - Voluntary resignations, retirements, and death terminations
• Dismissal Forms (E6) - Employer-initiated terminations, transfers, and loan endings
• Fixed-Term Terminations (E7) - Contract expirations and early terminations
• Construction Forms (E12) - Construction work personnel declarations and censuses
• Employment Modifications (MA/MAD) - Changes to employment terms
• Overtime Declarations - Regular and retrospective overtime submissions
• Sixth Day Declarations - Sixth day / extra shift submissions
• Pre-Announcement Exemptions - Pre-announcement exemption declarations
• Query Services - Employer info, branch details, parameter lookups, and employee status
• PSR-16 Caching - Opt-in caching for service responses with bundled file-based and in-memory implementations
• Model Factories - Laravel-inspired factories generating valid Greek test data (AFM, AMKA, names)
• CLI Tools - enum:check and schema:check to verify local code stays in sync with the live API

Requirements

• PHP ^8.2
• Guzzle HTTP ^7.9
• ERGANI credentials (username and password)

Installation

composer require oxygensuite/oxygen-ergani

Quick Start

1. Set Up Token Management

The package handles JWT authentication automatically. Configure it once at application boot:

use OxygenSuite\OxygenErgani\Storage\FileToken;
use OxygenSuite\OxygenErgani\Storage\Token;
use OxygenSuite\OxygenErgani\Enums\Environment;

Token::setCurrentTokenManager(
    new FileToken('your-username', 'your-password'),
    Environment::TEST // or Environment::PRODUCTION
);

2. Submit a Work Card

use OxygenSuite\OxygenErgani\Ergani;
use OxygenSuite\OxygenErgani\Models\WorkCard\Card;
use OxygenSuite\OxygenErgani\Models\WorkCard\CardDetail;
use OxygenSuite\OxygenErgani\Enums\CardDetailType;

$card = Card::make()
    ->setEmployerTin('999999999')
    ->setBranchCode(0)
    ->setComments('')
    ->addDetails(
        CardDetail::make()
            ->setTin('888888888')
            ->setLastName('DOE')
            ->setFirstName('JOHN')
            ->setType(CardDetailType::CHECK_IN)
            ->setReferenceDate(date('Y-m-d'))
            ->setDate(date('Y-m-d\TH:i:s.uP'))
    );

$ergani = new Ergani();
$response = $ergani->sendWorkCards($card);

echo $response[0]->protocol; // e.g., 'ΕΥΣ92'

3. Submit a Hiring Declaration (E3)

use OxygenSuite\OxygenErgani\Ergani;
use OxygenSuite\OxygenErgani\Models\Hiring\NewDeclaration;

$declaration = NewDeclaration::make()
    ->setEmployerTin('999999999')
    ->setBranchCode(0)
    ->setLastName('ΠΑΠΑΔΟΠΟΥΛΟΣ')
    ->setFirstName('ΙΩΑΝΝΗΣ')
    ->setTin('888888888')
    ->setAmka('01018012345')
    ->setHiringDate('15/01/2025')
    // ... additional fields
    ->withDefaults(); // Fill remaining fields with empty strings

$ergani = new Ergani();
$response = $ergani->sendHiringNew($declaration);

Documentation

Full documentation is available at oxygensuite.github.io/oxygen-ergani.

Guides

• Getting Started
• Token Management
• Work Cards
• Work Time Declarations
• Hiring Forms (E3)
• Termination Forms (E5)
• Dismissal Forms (E6)
• Fixed-Term Terminations (E7)
• Employment Modifications (MA/MAD)
• Construction Forms (E12)
• Sixth Day Declarations
• Pre-Announcement Exemptions
• Internship Declarations (E3.5)
• Query Services
• Error Handling
• Model Factories
• CLI Tools

API Reference

• Ergani Facade
• Enums
• Responses
• Exceptions

Upgrading

If you're upgrading from v1.x, please see the UPGRADING.md guide for breaking changes and migration instructions.

Development

# Install dependencies
composer install

# Run tests
composer test

# Static analysis (PHPStan level 7)
composer analyse

# Code style (PER)
composer lint

# Mutation testing
composer infect

# Run all checks
composer check

Security

If you discover a security vulnerability, please send an email to security@oxygen.gr. All security vulnerabilities will be promptly addressed. Please see SECURITY.md for more details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Changelog

Please see CHANGELOG.md for information about recent changes.

License

This package is open-source software licensed under the MIT License.

Copyright 2025 Oxygen Suite.