# Konventionen & Coding Style

Namespace & Dateien

• Alle Klassen müssen im App\-Namespace liegen
• PSR-4 Autoloading: App\Foo\Bar → src/Foo/Bar.php
• Beispiel:
  • Datei: src/Tasks/MyNewTask.php
  • Klasse: namespace App\Tasks; class MyNewTask { }

Code-Stil

Deutsch in Code & Commits

• Code-Kommentare: Deutsch
• Commit-Messages: Deutsch
• Variablen & Funktionen: Englisch (zum Schutz vor Copy-Paste-Fehler und zur Konsistenz mit Phorge-APIs)

Beispiel:

// Fingerprint für Phorge erzeugen (Deutsch)
protected function generateFingerprint(): string
{
    // timestamp aus Unix-Zeit umwandeln (Deutsch)
    $stamp = base_convert(time(), 10, 36);
    // ...
}

Kommentare

• Mehrzeilige Docblocks für öffentliche Methoden
• Inline-Kommentare nur für komplizierte Logik
• Deutsche Erklärungen, englische Parameternamen

/**
 * Führt einen API-Call gegen Phorge aus.
 *
 * @param string $method API-Methode (z.B. "maniphest.search")
 * @param array  $params Parameter
 * @return array Ergebnis
 * @throws \Exception bei Fehlern
 */
public function callPhorgeApi(string $method, array $params)
{
    // Token einsetzen
    $params['api.token'] = $this->config['api_token'];
    
    // ...
}

Exception-Handling

Wirfe immer aussagekräftige Exceptions:

// ❌ Schlecht
if (!$file) throw new \Exception('error');

// ✅ Gut
if (!file_exists($file)) {
    throw new \RuntimeException("Config-Datei nicht gefunden: $file");
}

Task-Struktur (Template)

<?php
namespace App\Tasks;

/**
 * Beschreibung des Tasks.
 *
 * @package App\Tasks
 */
class MeinTask extends AbstractTask
{
    protected string $title = '';
    protected string $description = '';
    
    public function setTitle(string $title): self
    {
        $this->title = $title;
        return $this;
    }
    
    public function setDescription(string $description): self
    {
        $this->description = $description;
        return $this;
    }
    
    /**
     * Führt den Task aus.
     *
     * @param ?array $params Optionale Parameter
     * @return mixed Ergebnis
     * @throws \Exception bei Fehlern
     */
    protected function run(?array $params = null)
    {
        // Validierung
        if ($this->title === '') {
            throw new \InvalidArgumentException('Title ist erforderlich');
        }
        
        // Logik
        $this->createLog('Task gestartet', 'info');
        
        // Rückgabe
        return ['success' => true];
    }
}

Sicherheit

SQL-Injection verhindern

Immer Prepared Statements nutzen:

// ❌ Gefährlich
$sql = "SELECT * FROM users WHERE id = $userId";

// ✅ Sicher
$sql = "SELECT * FROM users WHERE id = :id";
$result = $this->db->fetch($sql, [':id' => $userId]);

Abhängigkeiten minimieren

Neue Dependencies nicht hinzufügen. Wenn nötig, diskutieren!

Token & Secrets

• Niemals in Code hardcodieren
• Immer über config.php laden
• config.php ist git-ignoriert

Logging-Best-Practice

• Fehler: severity = 'error' oder 'critical'
• Wichtige Meilensteine: severity = 'info'
• Debug-Details: severity = 'debug'
• Warnungen: severity = 'warning'

Beispiel:

$this->createLog(
    'Maniphest-Task T' . $taskId . ' erstellt',
    'info',
    ['task_id' => $taskId, 'owner' => $owner],
    'app',
    'T' . $taskId  // phorge_id
);

---

Siehe auch: Tasks, API-Integration