CLI Tools
For contributors
These tools live in the repository's bin/ folder and run as Composer scripts of this package. They are excluded from the published package, so clone the repository to use them.
The repository includes four maintainer tools for keeping the package in sync with ERGANI:
| Command | What it checks | Needs credentials |
|---|---|---|
composer enum:check | Enums against ERGANI's parameter lists | Yes |
composer schema:check | Local XSDs against the live schema endpoint, and action-code coverage | Yes |
composer xsd:sync | Local XSDs against a downloaded ERGANI help-files bundle | No |
composer submit:check | Every document's payload against ERGANI's own validator, using invalid business data | Yes |
composer test also runs XsdComplianceTest, which validates every document's factory payload against the XSDs in xsd/ offline.
Configuration
Both tools read credentials from a .env file in the project root, or from environment variables:
# .env
ERGANI_USERNAME=your_username
ERGANI_PASSWORD=your_password
ERGANI_ENV=test # or 'production'Alternatively, set environment variables directly:
ERGANI_USERNAME=xxx ERGANI_PASSWORD=xxx composer enum:check -- --all$env:ERGANI_USERNAME="xxx"; $env:ERGANI_PASSWORD="xxx"; composer enum:check -- --allSchema Check
Compares document field schemas from the live API against local XSD files. Useful for detecting when the ERGANI API adds, removes, or reorders fields.
Documents that share the same XSD (e.g., the 6 daily work time and overtime documents in the WTO group, validated against WTO_v1.xsd; leave uses the WTOLeave group and WTO_v2.xsd) are grouped together, and their API fields are unioned for a single comparison per XSD.
Usage
# Check a specific schema group
composer schema:check E6LT
# Check a group by document name (resolves to its group)
composer schema:check DailyWorkTime # → resolves to WTO group
# Check all schemas
composer schema:check -- --all
# Show only schemas with mismatches
composer schema:check -- --all --errors-only
# Show field order differences
composer schema:check -- --all --show-order
# List all available schema groups
composer schema:check -- --list
# Check API coverage (which submissions we implement)
composer schema:check -- --coverage
# Clear cache and re-fetch from API
composer schema:check -- --all --freshFlags
| Flag | Description |
|---|---|
--all | Check all schema groups |
--list | List available schema groups and their documents |
--errors-only | With --all, suppress passing groups and only show mismatches |
--show-order | Show field order differences when fields match but order differs |
--coverage | Cross-reference implemented documents against the API submissions list |
--fresh | Clear cached API responses and re-fetch from the live API |
--help | Show usage information |
Output
For single-document groups:
E6LT (xsd/E6LT_v1.xsd)
------------------------
✓ Fields match: 47
✓ Order matchesFor multi-document groups (e.g., WTO with 6 documents sharing one XSD):
WTO (xsd/WTO_v1.xsd)
Documents: DailyWorkTime, DailyWorkTimeA, DailyWorkTimeD, Overtime, ...
---------------------
✓ Fields match: 13 (union of 6 API schemas)When mismatches are found:
E3N (xsd/E3N_v1.xsd)
---------------------
✓ Fields match: 85
⚠ In API but not in XSD: 2
+ f_new_field_1
+ f_new_field_2
✗ In XSD but not in API: 1
- f_removed_fieldName Resolution
You can use either a group name or a document name as the argument:
composer schema:check WTO— checks the entire WTO group (6 daily/overtime documents)composer schema:check DailyWorkTime— resolves to the WTO group and checks all 6composer schema:check E6LT— single-document group, checks just that one
Use --list to see all groups, documents, and their XSD files.
Coverage Report
The --coverage flag fetches the API's available submissions list and cross-references it against implemented document classes:
composer schema:check -- --coverageAPI Coverage Report
========================================
✓ Covered: 30/32 API submissions
WTODaily → DailyWorkTime
WebE3N → E3N
...
⚠ Not covered: 2 API submissions
NewAction — Νέα Υποβολή Δήλωσης
...Enum Check
Compares local PHP enum values against the live ERGANI API parameter lists. Detects when the API adds new values or removes existing ones.
Usage
# Check a specific enum
composer enum:check WorkCardDelayReason
# Check all enums
composer enum:check -- --all
# List available enums
composer enum:check -- --list
# Clear cache and re-fetch from API
composer enum:check -- --all --freshFlags
| Flag | Description |
|---|---|
--all | Check all enums |
--list | List available enums with their parameter types and classes |
--fresh | Clear cached API responses and re-fetch from the live API |
--help | Show usage information |
Available Enums
| Enum | Parameter Type | Description |
|---|---|---|
WorkCardDelayReason | WorkCardDelayReason | Work card delay reason codes |
WorkTimeType | WorkTimeType | Work time type codes (work, rest, leave, overtime) |
Output
WorkCardDelayReason
-------------------
✓ Matched: 5
✓ Enum is in sync with APIWhen differences are found:
WorkTimeType
------------
✓ Matched: 38
⚠ Missing in enum: 2
- ΝΕΟΣ1 (Νέος Τύπος Εργασίας)
- ΝΕΟΣ2 (Νέος Τύπος Αδείας)
✗ Extra in enum (not in API): 1
- ΠΑΛΑΙΟΣCaching
Both tools cache API responses locally (in .cache/data/) with a 1-day TTL to speed up repeated runs. On subsequent invocations the cached data is used instead of calling the live API, making the typical fix-and-recheck loop much faster.
Use the --fresh flag to clear the cache and force a fresh API fetch:
composer schema:check -- --all --fresh
composer enum:check -- --all --freshTIP
Authentication (login/token refresh) still happens on every run — only the schema and parameter data is cached.
Exit Codes
Both tools exit with code 0 when all checks pass, and 1 when any mismatch is found. This makes them suitable for CI pipelines:
# Example CI step
- run: composer schema:check -- --all
- run: composer enum:check -- --allxsd:sync
Compares the xsd/ folder with an ERGANI help-files bundle (the HELP_FILES_SAMPLES… download that comes with each interoperability guide update). No credentials are needed.
composer xsd:sync -- "path/to/HELP_FILES_SAMPLES_trial2_v3"
composer xsd:sync -- "path/to/bundle" --changed-only # hide identical files
composer xsd:sync -- "path/to/bundle" --apply # copy changed files into xsd/It reports:
- Identical / changed / missing for every XSD in
xsd/, with field-level differences for changed files (added and removed elements, changed enumerations, patterns, lengths and occurrence) - Newer schema versions in the bundle, e.g.
E3N_v1.xsd -> E3N_v2.xsd. Schema file versions are independent of the bundle's own release number, and ERGANI often publishes a newer_vN.xsdbefore activating it, so confirm withsubmit:checkwhich version ERGANI validates against before switching - Bundle schemas not used by the package (possible new or legacy forms)
It exits with 1 when changed files are found (without --apply).
submit:check
Checks every document against ERGANI's own validator. For each document in bin/schema-map.php, the package builds its normal payload from the model factory, then replaces the business identifiers with values that pass the XSD but can never pass ERGANI's business rules:
| Field | Replaced with |
|---|---|
every *afm* field | 123456789 (wrong check digit) |
every *amka* field | 01010101011 (wrong Luhn check digit) |
f_aa_pararthmatos | 999 (branch that does not exist) |
f_ypiresia_sepe / f_ypiresia_oaed | 99999 / 999999 (services that do not exist) |
ERGANI validates the XSD before the business rules, so the response tells you whether the package's structure is accepted:
| Result | Meaning |
|---|---|
STRUCTURE OK | Rejected by a business rule: the structure passed ERGANI's XSD validation |
XSD REJECTED | ERGANI rejected the structure: the package sends an invalid payload |
NOT AVAILABLE | The form is not enabled in that environment (Type … not valid / XSD File not found) |
SKIPPED | Fewer than two values could be made invalid (with --keep-branch: fewer than two AFM/AMKA), so it is not safe to send |
composer submit:check # trial environment (default)
composer submit:check -- --production # production environment
composer submit:check -- --production --keep-branch # keep branch 0: ERGANI rejects the invalid AFM instead
composer submit:check -- --only=E14,FastAna # specific documents
composer submit:check -- --list # document namesReal submissions
submit:check sends real requests to ERGANI. Every payload is built to be rejected, and anything that is unexpectedly accepted is cancelled immediately and reported, but prefer the trial environment and use --production deliberately. ERGANI_ENV is ignored: only --production selects production.
By default the branch is replaced too, so ERGANI usually stops at "branch does not exist". With --keep-branch the real branch (0) is sent, ERGANI gets past the branch check and rejects the invalid AFM instead, which exercises more of its validation. Because nothing but the invalid identifiers stands between the payload and a real filing in that mode, only AFM/AMKA replacements count and documents with fewer than two are skipped.
ERGANI's schema endpoint used by schema:check can disagree with the validator (it has omitted fields the validator requires, and listed fields in the wrong order), so submit:check is the authoritative check.
Documents whose default factory output targets another variant of the same schema (weekly work time, leave) use the factories listed in bin/factory-overrides.php.