adachsoft / task-api-repository
HTTP implementation of the adachsoft/task-contracts repositories backed by adachsoft/task-api.
Requires
- php: ^8.3
- adachsoft/task-contracts: ^3.0
- guzzlehttp/guzzle: ^7.9
Requires (Dev)
- adachsoft/php-code-style: ^0.7.1
- adachsoft/task-functional-tests: ^3.0
- friendsofphp/php-cs-fixer: ^3.89
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^13.4
- rector/rector: ^2.8
- symplify/phpstan-rules: ^14.9
- vlucas/phpdotenv: ^5.6
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 06:00:38 UTC
README
HTTP implementation of the adachsoft/task-contracts repositories backed by adachsoft/task-api.
Installation
composer require adachsoft/task-api-repository
The service must expose the /api/v1/repository endpoints. The 3.0 repositories target task-api 3.0.
Usage
use AdachSoft\TaskApiRepository\Factory\TaskApiRepositoryFactory;
$taskRepository = TaskApiRepositoryFactory::createTaskRepository(
'https://tasks.example.com',
$apiKey,
);
The API key is sent using the X-API-KEY header. Configuration is validated before any request is made.
3.0
Task-api 3.0 repository access is provided through these factories:
createTaskRepository()createCommentRepository()createAttachmentRepository()createAttachmentContentStorage()createWorkflowDefinitionRepository()createTaskTypeDefinitionRepository()
Each factory accepts the API base URL, API key, and an optional timeout in seconds. The API key's account must have the access.repository permission on the task-api 3.0 server.
Retry behavior
The HTTP client retries transient responses automatically:
- HTTP
429responses are retried for every method. This handles reverse-proxylimit_reqresponses that are rejected before the Task API backend processes the request. - HTTP
502,503, and504responses are retried only forGET,PUT, andDELETErequests.
The default policy allows six total attempts. The client honors a numeric Retry-After header up to 30 seconds; otherwise it uses exponential backoff starting at 0.5 seconds and capped at 30 seconds. Non-JSON HTTP errors include the status, reason phrase, and up to 200 characters of the response body. Recognized API error envelopes keep their existing exception mapping.
Pass a RetryPolicy as the final optional argument to any repository factory to customize attempts and delays:
use AdachSoft\TaskApiRepository\Factory\TaskApiRepositoryFactory;
use AdachSoft\TaskApiRepository\RetryPolicy;
$retryPolicy = new RetryPolicy(maxAttempts: 4, baseDelaySeconds: 1.0, maxDelaySeconds: 20.0);
$taskRepository = TaskApiRepositoryFactory::createTaskRepository(
'https://tasks.example.com',
$apiKey,
10.0,
$retryPolicy,
);
Error mapping
| API reason | Exception |
|---|---|
task_not_found | TaskNotFoundException |
comment_not_found | CommentNotFoundException |
dependency_not_found | DependencyNotFoundException |
dependency_already_exists | DependencyAlreadyExistsException |
task_already_exists | TaskAlreadyExistsException |
comment_already_exists | CommentAlreadyExistsException |
concurrent_modification | ConcurrentModificationException |
invalid_task_data | InvalidTaskDataException |
contract_violation | InvalidArgumentException |
Unknown API errors and malformed responses are reported as TaskApiRepositoryException.
Optimistic locking
Repository updates use the DTO version field. A ConcurrentModificationException means that another client changed the record; read the record again before retrying an update.
Tests
The test suite runs with:
vendor/bin/phpunit tests
The controlled Docker E2E suite clones adachsoft/task-api at version v0.6.1, installs its dependencies, resets the API storage before each contract test, and starts its Docker Compose test stack automatically:
composer test:e2e-docker
The Docker E2E suite requires Git, Composer, Docker Engine, Docker Compose v2, network access to GitLab, and an available host port 8081. Missing prerequisites or an unavailable API fail the suite; no manual checkout or external API credentials are required.