Search by

adachsoft / task-json-file

Arkadiusz Adach

JSON file implementation of adachsoft/task-contracts

Package info

gitlab.com/a.adach/task-json-file

Issues

pkg:composer/adachsoft/task-json-file

Statistics

Installs: 80

Dependents: 0

Suggesters: 0

Stars: 0

v0.3.0 2026-11-16 05:50 UTC

This package is auto-updated.

Last update: 2026-11-16 04:52:52 UTC


README

A JSON file implementation of the adachsoft/task-contracts repository interfaces.

Features

  • Persist tasks, comments, and attachment metadata in JSON files.
  • Store attachment content as separate files with atomic replacement.
  • Read workflow and task type definitions from a shared JSON file.
  • Add, update, delete, and find tasks and comments by identifier.
  • Search tasks with filters, sorting, and pagination.
  • Allocate the next task, comment, or attachment identity.
  • Build task trees and manage task dependencies.
  • Count children, comments, and attachments for multiple tasks.
  • Protect read-modify-write operations with exclusive file locking.
  • Detect concurrent task and comment updates with optimistic version checks.

Installation

composer require adachsoft/task-json-file

Usage

<?php

declare(strict_types=1);

use AdachSoft\TaskJsonFile\Repository\JsonTaskRepository;

$repository = new JsonTaskRepository(__DIR__ . '/var/tasks.json');

$task = $repository->findById('task1');
$rootTasks = $repository->findByParentId(null);

The task repository implements AdachSoft\TaskContracts\Interface\TaskRepositoryInterface. Use add() for inserts and save() for compare-and-swap updates; persisted entities are versioned starting at version 1.

Use AdachSoft\TaskJsonFile\Repository\JsonCommentRepository to persist and query comments associated with tasks. Task and comment mutations are performed while holding an exclusive lock on their JSON files.

Repository configuration

Each file-backed repository receives its storage path in its constructor. For example, JsonAttachmentRepository takes a JSON metadata file path, while JsonAttachmentContentStorage takes a directory in which it creates one content file per attachment identifier.

Workflow and task type definitions share one JSON file. Pass a JsonDefinitionFileLoader for that file to both repositories:

use AdachSoft\TaskJsonFile\Definition\JsonDefinitionFileLoader;
use AdachSoft\TaskJsonFile\Repository\JsonTaskTypeDefinitionRepository;
use AdachSoft\TaskJsonFile\Repository\JsonWorkflowDefinitionRepository;

$loader = new JsonDefinitionFileLoader(__DIR__ . '/var/definitions.json');
$workflowDefinitions = new JsonWorkflowDefinitionRepository($loader);
$taskTypeDefinitions = new JsonTaskTypeDefinitionRepository($loader);

When the definition file does not exist, the repositories use the built-in default workflow and task type. A present file must contain the following keys: workflows, task_types, and default_task_type. Workflow entries contain id, name, initial, statuses, and transitions; status entries contain id, name, and category. A transition's from value may be null, and its condition is optional.

Example definition file:

{
  "workflows": [
    {
      "id": "bug",
      "name": "Bug",
      "initial": "reported",
      "statuses": [
        {"id": "reported", "name": "Reported", "category": "TODO"},
        {"id": "confirmed", "name": "Confirmed", "category": "TODO"},
        {"id": "fixing", "name": "In progress", "category": "IN_PROGRESS"},
        {"id": "review", "name": "In review", "category": "IN_PROGRESS"},
        {"id": "closed", "name": "Closed", "category": "DONE"},
        {"id": "rejected", "name": "Rejected", "category": "CANCELLED"}
      ],
      "transitions": [
        {"from": "reported", "to": "confirmed"},
        {"from": "reported", "to": "rejected"},
        {"from": "confirmed", "to": "fixing"},
        {"from": "fixing", "to": "review", "condition": "checklist.all_done"},
        {"from": "review", "to": "fixing"},
        {"from": "review", "to": "closed", "condition": "actor.role == 'supervisor'"}
      ]
    }
  ],
  "task_types": [
    {"id": "bug", "name": "Bug", "workflow": "bug"}
  ],
  "default_task_type": "bug"
}

Migrating task files from 2.x

Existing 2.x task files can be read without a separate migration step. The mapper preserves the stored status as a status identifier in the default workflow and supplies the 3.0 defaults for fields that were not present: task type task, no author, empty attributes, and an empty checklist. When the repository persists those tasks, it writes the current 3.0 representation. An absent definition file continues to provide the default workflow and task type.

See docs/examples/ for complete usage examples.

Identity counters

Each repository JSON file stores identity high-water marks under meta: last_task_number for tasks, and last_comment_number and last_attachment_number keyed by task ID. Adds update these counters in the same locked transaction as the record. nextIdentity() uses the greater of the stored counter and existing records, so deleting a record never makes its identifier available again. Legacy files without meta remain readable and acquire identity metadata when written.

Requirements

  • PHP 8.3 or newer
  • adachsoft/task-contracts

License

This project is released under the MIT License.