# Neue Tasks schreiben

Struktur

Alle Tasks erben von App\Tasks\AbstractTask und müssen die Methode run() implementieren:

<?php
namespace App\Tasks;

class MeinNeuerTask extends AbstractTask
{
    protected string $parameter1 = '';
    
    public function setParameter1(string $value): self
    {
        $this->parameter1 = $value;
        return $this;
    }
    
    protected function run(?array $params = null)
    {
        // Deine Logik hier
        $this->createLog('Task gestartet', 'info');
        
        // Beispiel: Phorge API aufrufen
        $result = $this->callPhorgeApi('maniphest.search', [
            'constraints[statuses][0]' => 'open'
        ]);
        
        return $result;
    }
}

Wichtige Methoden aus AbstractTask

Methode	Beschreibung
$this->db	PDO DBManager Instanz
$this->logger	LogManager Instanz
$this->config	Geladene Konfiguration
$this->fingerprint	Eindeutige Task-ID
$this->jobID	Job ID (falls gesetzt)
callPhorgeApi($method, $params)	API-Call gegen Phorge
createLog($msg, $severity, $data, $channel, $phorgeId, $jobId)	Logeintrag erstellen
execute(?array $params = null)	Von außen aufrufen! Nicht run() direkt

Fluent API Pattern

Setter sollten immer $this zurückgeben:

public function setTitle(string $title): self
{
    $this->title = $title;
    return $this;
}

Das ermöglicht Method Chaining:

$task = (new MeinTask())
    ->setParameter1('Wert1')
    ->setParameter2('Wert2')
    ->setParameter3('Wert3');

$result = $task->execute();

Fehlerbehandlung

Exceptions werden nicht abgefangen. Sie bubbleln hoch zu execute() und landen dort im Logging:

protected function run()
{
    if ($this->parameter1 === '') {
        throw new \InvalidArgumentException('parameter1 ist erforderlich');
    }
    
    // ...
}

Dry-Run unterstützen

Viele Tasks sollten einen Dry-Run-Modus haben:

protected function run(?array $params = null)
{
    $dryRun = $params['dry_run'] ?? false;
    
    $payload = $this->buildPayload();
    
    if ($dryRun) {
        $this->createLog('Dry Run: würde ausführen', 'info', $payload);
        return $payload;
    }
    
    // Echten Call ausführen
    return $this->callPhorgeApi('...', $payload);
}

Logging nutzen

Jeden wichtigen Schritt loggen:

$this->createLog('Maniphest-Suche gestartet', 'info');

// ...

$this->createLog(
    'Task T123 gefunden',
    'info',
    $taskData,
    'app',
    'T123'  // phorge_id
);

Beispiel: ManiphestSearchTask

Schaue dir die existierenden Tasks an:

• src/Tasks/ManiphestCreateTask.php
• src/Tasks/ManiphestSearchTask.php

Sie zeigen das empfohlene Pattern.

---

TransactionsBuilder (neues Pattern für Create/Edit)

Für Schreiboperationen (maniphest.edit) sollte statt manueller Arrays der neue TransactionsBuilder verwendet werden. Er liefert eine saubere Liste von Transactions im Format ['type' => ..., 'value' => ...].

Kurzes Beispiel (Create):

use App\Tasks\ManiphestCreateTask;
use App\Tasks\TransactionsBuilder;

$builder = (new TransactionsBuilder())
    ->addTitle('Neues Ticket')
    ->addDescription('Beschreibung des Tickets')
    ->addProjects(['PHID-PROJ-abc123']);

$payload = ['transactions' => $builder->build()];

$task = new ManiphestCreateTask();
$task->setTitle('...')
     ->setDescription('...');

// Übergabe an die API (in ManiphestCreateTask intern bereits umgesetzt)
$result = $task->run(false); // false = kein Dry-Run

Parent/Subtask: Wenn ein Task als Subtask eines anderen angelegt werden soll, verwende addParent($parentPHID):

$builder->addParent('PHID-TASK-xxxx');

Die Builder-Methoden prüfen PHID-Formate und erlaubte Transaction-Typen.

Siehe auch: Übersicht, API-Integration, Schema-Refresh