ngsoft / cronicle-tasks-client
PHP HTTP client for the Cronicle JSON REST API, with typed DTOs and OpenAPI schema
Requires
- php: >=8.2
- ext-curl: *
- ext-json: *
- ext-mbstring: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2|^3
- phpstan/phpstan: ^2.0
- rector/rector: ^2.0
- symfony/dotenv: ^7|^8
- symfony/var-dumper: ^7|^8
Suggests
- symfony/var-dumper: Needed by examples/client-test.php (dump())
Provides
None
Conflicts
None
Replaces
None
README
Client PHP pour l’API JSON REST Cronicle.
Il encapsule les appels HTTP via CurlHandler, hydrate des DTOs typés, et expose un schéma OpenAPI aligné sur ces DTOs.
Package Composer : ngsoft/cronicle-tasks-client
Prérequis
- PHP ≥ 8.2
- Extensions :
curl,json,mbstring - Composer
- Une instance Cronicle joignable + une clé API
Installation
Via Composer :
composer require ngsoft/cronicle-tasks-client
Développement local (clone du dépôt) :
composer install cp .env.example .env
Configuration
Variables d’environnement (fichier .env / .env.dev, voir .env.example) :
| Variable | Description |
|---|---|
CRONICLE_BASE_URL |
URL de base du serveur Cronicle (ex. http://127.0.0.1:3012) |
CRONICLE_API_KEY |
Clé API (32 caractères hex) |
Exemple :
CRONICLE_BASE_URL=https://cronicle.example.com:3012 CRONICLE_API_KEY=your_api_key_here
Le bootstrap charge l’env via lib/init.php → load_env().
L’autoload Composer charge déjà lib/functions.php (helpers + CurlHandler).
Utilisation rapide
Avec l’autoload Composer (recommandé dans une app) :
require_once __DIR__ . '/vendor/autoload.php'; use NGSOFT\Cronicle\Client; use NGSOFT\Cronicle\Exception\CronicleException; // Option A — variables d'environnement déjà chargées $client = Client::fromEnv(); // Option B — explicite $client = new Client('https://cronicle.example.com:3012', 'your_api_key'); try { $schedule = $client->getSchedule(0, 50); foreach ($schedule->rows as $event) { echo $event->id . ' — ' . $event->title . PHP_EOL; } $state = $client->getMasterState(); echo 'Scheduler: ' . ($state->state->isEnabled() ? 'on' : 'off') . PHP_EOL; } catch (CronicleException $e) { echo 'API error [' . $e->getApiCode() . ']: ' . $e->getMessage() . PHP_EOL; }
Dans ce dépôt (bootstrap dotenv inclus) :
require_once __DIR__ . '/lib/init.php'; load_env(); $client = Client::fromEnv();
Méthodes du client
| Méthode PHP | Endpoint Cronicle | Réponse DTO |
|---|---|---|
getSchedule(?offset, ?limit) |
get_schedule |
ScheduleResponse |
getEvent(?id, ?title) |
get_event |
EventResponse |
createEvent(array|Event) |
create_event |
CreateEventResponse |
updateEvent(array|Event, ?resetCursor, ?abortJobs) |
update_event |
ApiResponse |
deleteEvent(id) |
delete_event |
ApiResponse |
getEventHistory(id, ?offset, ?limit) |
get_event_history |
HistoryResponse |
getHistory(?offset, ?limit) |
get_history |
HistoryResponse |
runEvent(?id, ?title, overrides) |
run_event |
RunEventResponse |
getJobStatus(id) |
get_job_status |
JobStatusResponse |
getActiveJobs() |
get_active_jobs |
ActiveJobsResponse |
updateJob(id, fields) |
update_job |
ApiResponse |
abortJob(id) |
abort_job |
ApiResponse |
getMasterState() |
get_master_state |
MasterStateResponse |
updateMasterState(enabled) |
update_master_state |
ApiResponse |
Toutes les URLs sont de la forme {baseUrl}/api/app/{action}/v1.
L’auth est envoyée via le header X-API-Key.
En cas d’erreur HTTP ou de code ≠ 0 dans la réponse JSON, une CronicleException est levée.
DTOs
Namespace NGSOFT\Cronicle\Dto :
| Classe | Rôle |
|---|---|
Event |
Objet événement (schedule) |
EventTiming |
Timing type cron (years, months, days, …) |
Job |
Job actif ou terminé (étend Event) |
ResourceStats |
Stats CPU / mémoire (min, max, total, count, current) |
ListMeta |
Métadonnées de pagination (length, …) |
MasterState |
État du scheduler (enabled) |
Responses (NGSOFT\Cronicle\Dto\Response) :
ApiResponse— enveloppe standard (code,description)ScheduleResponse,EventResponse,CreateEventResponseHistoryResponse,RunEventResponse,JobStatusResponseActiveJobsResponse,MasterStateResponse
Hydratation / sérialisation :
$event = Event::fromArray($payload); $array = $event->toArray(); // omet les null par défaut
Structure du projet
cronicle-client/
├── src/Cronicle/
│ ├── Client.php
│ ├── Exception/CronicleException.php
│ └── Dto/… # domain + Response
├── lib/
│ ├── init.php # bootstrap + dotenv
│ └── libs-no-sql-php82.php # CurlHandler, helpers
├── examples/
│ └── client-test.php # smoke test (dump des réponses)
├── openapi.yaml # schéma OpenAPI 3.1
├── composer.json
└── .env / .env.dev
OpenAPI
Le fichier openapi.yaml décrit les 14 endpoints et les schémas alignés sur les DTOs PHP.
Utile pour Swagger UI, Postman, génération de clients, etc.
Référence officielle : Cronicle API Reference.
Exemple de test
Script de smoke test en lecture seule (affiche les DTOs via dump()) :
php examples/client-test.php
Nécessite CRONICLE_BASE_URL et CRONICLE_API_KEY configurés, et symfony/var-dumper (dev).
Qualité de code
composer cs:fix
# ou
vendor/bin/php-cs-fixer fix src
Publication Packagist
- Pousser le dépôt sur GitHub (
ngsoft/cronicle-client) - Tagger une version semver :
git tag v1.0.0 && git push --tags - Soumettre le dépôt sur Packagist (ou activer l’auto-update GitHub)
- Installer ailleurs avec :
composer require ngsoft/cronicle-tasks-client
Licence / références
- Licence : MIT
- Cronicle : jhuckaby/Cronicle
- API docs : docs/APIReference.md