Files

Michael Schiemer 5050c7d73a docs: consolidate documentation into organized structure

- Move 12 markdown files from root to docs/ subdirectories
- Organize documentation by category:
  • docs/troubleshooting/ (1 file)  - Technical troubleshooting guides
  • docs/deployment/      (4 files) - Deployment and security documentation
  • docs/guides/          (3 files) - Feature-specific guides
  • docs/planning/        (4 files) - Planning and improvement proposals

Root directory cleanup:
- Reduced from 16 to 4 markdown files in root
- Only essential project files remain:
  • CLAUDE.md (AI instructions)
  • README.md (Main project readme)
  • CLEANUP_PLAN.md (Current cleanup plan)
  • SRC_STRUCTURE_IMPROVEMENTS.md (Structure improvements)

This improves:
✅ Documentation discoverability
✅ Logical organization by purpose
✅ Clean root directory
✅ Better maintainability

2025-10-05 11:05:04 +02:00

3.8 KiB

Raw Blame History

Bild-Upload-System

Dieses Dokument beschreibt das Bild-Upload-System des Frameworks.

Funktionen

Strukturierte Ordnerhierarchie basierend auf Datum und ID
Automatische Erstellung mehrerer Bildvarianten (Größen)
Unterstützung für mehrere Dateiformate (JPG, WebP, AVIF)
Duplikat-Erkennung über SHA256-Hash
Sicherheitsvalidierung von Dateitypen und -größen
Performance-Optimierung durch moderne Bildformate

Ordnerstruktur

Die Bilder werden in folgendem Muster gespeichert:

/uploads
└─ /YYYY (Jahr)
   └─ /MM (Monat)
      └─ /DD (Tag)
         └─ /XXX (ID Teil 1)
            └─ /XXX (ID Teil 2)
               └─ /XXX (ID Teil 3)
                  └─ original.jpg
                  └─ thumbnail.jpg
                  └─ thumbnail.webp
                  └─ thumbnail.avif
                  └─ small.jpg
                  └─ small.webp
                  └─ small.avif
                  └─ medium.jpg
                  └─ medium.webp
                  └─ medium.avif
                  └─ large.jpg
                  └─ large.webp
                  └─ large.avif

Bildvarianten

Folgende Bildvarianten werden automatisch erstellt:

thumbnail: 150x150px, quadratisch zugeschnitten
small: 400x400px, proportional skaliert
medium: 800x800px, proportional skaliert
large: 1200x1200px, proportional skaliert

Dateiformate

Jede Variante wird in folgenden Formaten gespeichert:

JPG: Für universelle Kompatibilität
WebP: Für moderne Browser mit besserer Kompression
AVIF: Für neueste Browser mit bester Kompression (falls PHP-Unterstützung vorhanden)

Datenbank-Schema

Das System verwendet zwei Tabellen:

`images`

id: Primärschlüssel
filename: Generierter Dateiname
original_filename: Originaler Upload-Dateiname
mime_type: MIME-Typ des Bildes
file_size: Dateigröße in Bytes
width: Bildbreite in Pixeln
height: Bildhöhe in Pixeln
hash: SHA256-Hash für Duplikat-Erkennung
upload_path: Relativer Pfad zum Bild
created_at: Erstellungszeitpunkt
updated_at: Letzter Aktualisierungszeitpunkt

`image_variants`

id: Primärschlüssel
image_id: Fremdschlüssel zur images-Tabelle
variant: Name der Variante (thumbnail, small, medium, large)
format: Dateiformat (jpg, webp, avif)
width: Bildbreite in Pixeln
height: Bildhöhe in Pixeln
file_size: Dateigröße in Bytes
filename: Name der Variantendatei
created_at: Erstellungszeitpunkt

Verwendung

Bild hochladen

// In einem Controller
public function upload(Request $request)
{
    $file = $request->files->get('image');
    $image = $this->imageService->uploadImage($file);

    // URL zu einer Bildvariante erhalten
    $thumbnailUrl = $this->imageService->getImageUrl($image, 'thumbnail', 'webp');
    $mediumUrl = $this->imageService->getImageUrl($image, 'medium', 'jpg');
}

Bild anzeigen

<!-- Optimale Bildauswahl mit picture-Element -->
<picture>
    <source srcset="/media/uploads/2025/06/26/001/234/567/1234567/medium.avif" type="image/avif">
    <source srcset="/media/uploads/2025/06/26/001/234/567/1234567/medium.webp" type="image/webp">
    <img src="/media/uploads/2025/06/26/001/234/567/1234567/medium.jpg" alt="Beschreibung">
</picture>

Technische Details

Bildverarbeitung

Die Bildverarbeitung erfolgt mit der GD-Bibliothek. Für die Verwendung von AVIF ist PHP 8.1+ mit AVIF-Unterstützung erforderlich.

Performance

Bilder werden mit Cache-Headers ausgeliefert, die eine lange Browser-Cache-Dauer ermöglichen, um Bandbreite zu sparen und die Ladezeit zu verbessern.

Sicherheit

Alle Uploads werden validiert, um sicherzustellen, dass nur erlaubte Bildtypen verarbeitet werden. Es werden sichere, eindeutige Dateinamen generiert, um Konflikte zu vermeiden.

3.8 KiB Raw Blame History