6 Coding-Guidelines

blaerf edited this page 2025-11-29 13:59:46 +01:00

Unescape Escape

Table of Contents

• PHP Coding Guidelines
• 1. Allgemeine Grundsätze
• 2. Projektstruktur
• 3. Dateien & Encoding
• 4. Namespaces & Autoloading
• 5. Namenskonventionen
• Klassen
• Interfaces
• Methoden & Funktionen
• Variablen / Eigenschaften
• Konstanten
• 6. Formatierung & Einrückung
• 7. Typen & strikte Typisierung
• 8. Arrays & Strings
• Arrays
• Strings
• 9. Objektorientierung
• Sichtbarkeit
• Konstruktor-Injection
• 10. Fehlerbehandlung & Exceptions
• 11. Kommentare & PHPDoc
• PHPDoc
• 12. Sicherheit
• Eingaben validieren
• SQL Injection vermeiden
• XSS verhindern
• Passwörter
• CSRF-Token
• 13. Git-Workflow
• 14. Code-Review-Regeln
• 15. Beispiel-Code
• 16. Weiterentwicklung

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

PHP Coding Guidelines

Diese Coding-Guidelines gelten für alle PHP-Projekte der Anwendungsentwickler-Klasse.
Ziel ist ein einheitlicher, gut lesbarer und wartbarer Code-Stil, damit alle im Team effizient zusammenarbeiten können.

---

1. Allgemeine Grundsätze

• Wir verwenden PHP 8.x.
• Wir schreiben möglichst typsicheren Code (Parameter- und Rückgabetypen).
• Lesbarkeit steht über Cleverness.
• Duplizierten Code vermeiden („Don't Repeat Yourself“).

---

2. Projektstruktur

Dieses Projekt verwendet eine klare Trennung von Webroot (public/) und Anwendungslogik (app/). Die vollständige Struktur ist hier dokumentiert: Projektstruktur und Best Practices

Regeln:

• Öffentlich zugängliche Dateien nur in public/.
• Alle Klassen in app/.
• Keine Konfigurationswerte hart im Code.

---

3. Dateien & Encoding

• .php Endung.
• UTF-8 ohne BOM.
• Datei beginnt mit <?php und ohne schließendes ?>.

---

4. Namespaces & Autoloading

• PSR-4 Autoloading.
• Namespace spiegelt Ordnerstruktur wider.

Beispiel:

<?php

declare(strict_types=1);

namespace App\Services\Ldap;

class LdapDirectoryService
{
    // LDAP-Operationen (Benutzersuche, Gruppensuche, etc.)
}

---

5. Namenskonventionen

Klassen

• PascalCase
  UserController, InvoiceService

Interfaces

• PascalCase + Interface
UserRepositoryInterface

Methoden & Funktionen

• camelCase
  getUserById()

Variablen / Eigenschaften

• camelCase
  $userName

Konstanten

• UPPER_SNAKE_CASE
  MAX_LOGIN_ATTEMPTS

---

6. Formatierung & Einrückung

• 4 Leerzeichen.
• Zeilenlänge max. 120 Zeichen.
• Öffnende Klammer in derselben Zeile.

Beispiel:

if ($condition) {
    // ...
} else {
    // ...
}

---

7. Typen & strikte Typisierung

• Am Anfang der Datei:

declare(strict_types=1);

• Parameter- und Rückgabetypen nutzen.

Beispiel:

public function findUserById(int $id): ?User
{
}

• Nullable Typen:

?string

---

8. Arrays & Strings

Arrays

Kurzsyntax:

$items = [
    'apple',
    'banana',
];

Strings

• '...' ohne Variablen
• "..." mit Variablen

---

9. Objektorientierung

Sichtbarkeit

• Standard: private
• Nur wenn nötig protected oder public.

Beispiel:

class User
{
    private string $name;

    public function getName(): string
    {
        return $this->name;
    }
}

Konstruktor-Injection

public function __construct(
    private InvoiceRepositoryInterface $repo
) {}

---

10. Fehlerbehandlung & Exceptions

• Keine die(), exit(), var_dump() im Produktivcode.
• Exceptions statt Abbrüche.

Beispiel:

throw new UserNotFoundException("User not found");

---

11. Kommentare & PHPDoc

• Kommentare erklären warum, nicht was.

Schlecht:

// increment i
$i = $i + 1;

PHPDoc

• Jeder public Controller und jeder public Service bekommt einen PHPDoc-Klassenkommentar.
• Öffentliche Methoden erhalten immer einen PHPDoc-Block mit:
  • kurzer Beschreibung (1–3 Sätze),
  • @param für alle Parameter,
  • @return für den Rückgabewert.
• Methoden, die AD-Objekte verändern oder Skripte anstoßen, müssen einen Hinweis auf Seiteneffekte enthalten (z. B. „legt AD-Benutzer an“, „führt PowerShell-Skript aus“).

/**
 * Berechnet die Gesamtsumme einer Rechnung.
 */
public function calculateTotal(Invoice $invoice): float
{
}

---

12. Sicherheit

Eingaben validieren

$email = filter_input(INPUT_POST, 'email', FILTER_VALIDATE_EMAIL);

SQL Injection vermeiden

$stmt = $pdo->prepare('SELECT * FROM users WHERE email = :email');
$stmt->execute(['email' => $email]);

XSS verhindern

<?= htmlspecialchars($userName, ENT_QUOTES, 'UTF-8') ?>

Passwörter

password_hash($pw, PASSWORD_DEFAULT);
password_verify($pw, $hash);

CSRF-Token

<input type="hidden" name="csrf_token" value="<?= $_SESSION['csrf_token'] ?>">

---

13. Git-Workflow

• Häufige, kleine Commits.
• Commit-Messages im Imperativ:
  • Add login form
  • Fix session timeout
• Echte Konfigurationsdateien (z. B. config.php) und alle Daten im Ordner storage/ werden grundsätzlich nicht versioniert. Details stehen unter: Projektstruktur und Best Practices

---

14. Code-Review-Regeln

• Review vor jedem Merge.
• Kritik ist sachlich.
• Reviewer geben konkrete Vorschläge.

---

15. Beispiel-Code

<?php

declare(strict_types=1);

namespace SchoolApp\User;

use PDO;

class UserRepository implements UserRepositoryInterface
{
    public function __construct(private PDO $connection)
    {
    }

    public function findByEmail(string $email): ?User
    {
        $sql = 'SELECT id, name, email FROM users WHERE email = :email';

        $stmt = $this->connection->prepare($sql);
        $stmt->execute(['email' => $email]);

        $data = $stmt->fetch(PDO::FETCH_ASSOC);

        if ($data === false) {
            return null;
        }

        return new User(
            (int) $data['id'],
            (string) $data['name'],
            (string) $data['email']
        );
    }
}

---

16. Weiterentwicklung

• Guidelines sind lebendig.
• Änderungen im Team besprechen.
• Aktualisierungen per Pull-Request.

---