Dokumentation für das CringePHP Boilerplate

Übersicht

Das CringePHP Boilerplate verzichtet bewusst auf das klassische MVC-Pattern und setzt stattdessen auf das Structured View Pattern (SV-Pattern). Dieses eigens für CringePHP entwickelte Pattern ist eine Mischung aus dem Template View Pattern und einer minimalistischen Anwendung des Front Controller Patterns. Es ist speziell darauf ausgelegt, ohne zusätzliche Controller- und Model-Logik auszukommen und ermöglicht so eine schnelle und unkomplizierte Entwicklung.

CringePHP nutzt einen zentralen Dispatcher, der basierend auf der URL spezifische Views lädt und anzeigt, während Helper-Funktionen als leichtgewichtige Unterstützung dienen. Dieser Ansatz ist ideal für kleinere Projekte wie statische Seiten, Micropages oder Single-Page-Anwendungen, die ohne komplexe Strukturen auskommen und einen direkten, effizienten Workflow ermöglichen.

Für wen ist dieses Boilerplate geeignet?

Das CringePHP Boilerplate richtet sich an Entwickler, die eine schnelle und unkomplizierte Grundlage für moderne Webprojekte benötigen. Es eignet sich besonders für kleinere oder mittlere Projekte, bei denen einfache und effiziente Lösungen im Vordergrund stehen – ideal für alle, die mit minimalem Aufwand eine funktionsfähige und performante Website erstellen möchten.

Besonders wertvoll ist CringePHP für Einsteiger und Umsteiger, die ihre Fähigkeiten schnell auf ein höheres Niveau bringen möchten. Es vermittelt zahlreiche bewährte Methoden, elegante Lösungen und fortgeschrittene Techniken, die oft erst mit viel Erfahrung entdeckt werden. Dadurch wird nicht nur die praktische Anwendung vereinfacht, sondern auch ein tiefgreifendes Verständnis für moderne Webentwicklung gefördert.

Installation und Setup

1. Entpacken: Entpacke das Boilerplate in das gewünschte Projektverzeichnis und setze /public als Webroot, um eine sichere Verzeichnisstruktur zu gewährleisten.
2. Plugins: Bootstrap, FontAwesome und jQuery sind vorinstalliert und liegen sauber getrennt im Verzeichnis /public/plugins/. Diese klare Struktur sorgt für bessere Übersicht, wodurch ein modularer Aufbau ermöglicht wird.
3. DSGVO-Option (beta): Eine DSGVO-Option kann aktiviert werden, die jedoch individuell angepasst werden muss (z.B. Cookie-Banner, Opt-in). Die Option ist im Ordner /public/plugins/gdpr_v0.9.8/ verfügbar.
4. Kontaktformular und Impressum: Dummy-Texte für Impressum/Datenschutz und ein Kontaktformular sind bereits integriert. Diese Platzhaltertexte sollten durch eigene Inhalte ersetzt werden.

Mechaniken und Nutzung

• Routing:

  • Routen werden in der Datei /app/routes.php definiert.
  • Einfache und flexible URL-Verwaltung: URLs können ohne Dateiendungen (z. B. .html) verwendet werden. Beispielsweise kann eine Route /gallery auf die Datei /app/views/pages/gallery.phtml verweisen.
  • Beispiele für Routen:

  'home' => '/', // Verweist auf /app/views/pages/home.phtml
  'item' => '/item/{id}', // in der View verwendbar als $this->id
  'user_section' => '/user/{username}/settings/{section}', // in der View verwendbar als $this->username & $this->section
  'my_hidden_script' => '/blume.jpg' // Lädt /app/views/pages/my_hidden_script.phtml bei Aufruf von /blume.jpg (kein echtes Bild)

  • In der View kann die Methode $this->url() verwendet werden, um URLs zu generieren:

  $this->url('my_hidden_script'); // Gibt /blume.jpg zurück
  $this->url('item', ['id' => 12]); // Gibt /item/12 zurück
  $this->url('user_section', ['username' => 'John Doe', 'section' => 'privacy']); // Gibt /user/John%20Doe/settings/privacy zurück

• API-Zugriffe:

  • API-Dateien werden im Ordner /app/api erstellt und funktionieren ohne eine definierte Route. Jede .php-Datei im Ordner /app/api ist direkt über /api/[DATEINAME] aufrufbar, ohne dass eine zusätzliche Konfiguration erforderlich ist.
  • Beispiel: Die Datei /app/api/cart.php verarbeitet Artikel im Warenkorb und ist direkt über die URL /api/cart erreichbar. Sie gibt automatisch JSON-Antworten zurück und benötigt keine zusätzliche Route.

• Ansichten (Views):

  • Die Ansichtendateien befinden sich im Ordner /app/views/pages.
  • Die Datei /app/views/templates/layout.phtml stellt das Grundgerüst der Seite bereit und lädt die einzelnen Views dynamisch, was für ein komfortables und strukturiertes Layout sorgt.

• Dateien-Versionierung zur Cache-Umgehung:

  • Um sicherzustellen, dass aktualisierte Dateien wie CSS oder JavaScript nach Änderungen korrekt geladen werden, wird ein sogenannter Cache-Buster eingesetzt. Dies geschieht automatisch mithilfe der asset()-Funktion.

  • Beispiel in einer View:

    <link rel="stylesheet" href="<?php echo asset('css/style.css'); ?>">
    <script src="<?php echo asset('js/core.js'); ?>"></script>

  • Der Parameter ?v={WERT} wird automatisch hinzugefügt. Der Wert basiert auf dem Dateizeitstempel (Last-Modified), sodass der Browser die Datei als „neu“ erkennt, wenn sich diese ändert.

  • Diese Methode ist vollständig automatisiert und sorgt dafür, dass Änderungen an Dateien ohne zusätzliche manuelle Schritte korrekt erkannt werden.

• Progressive Web App (PWA):

  • CringePHP bringt von Haus aus alle Voraussetzungen mit, um die Webseite als PWA auf Android-Geräten zu installieren.
  • Der "App installieren"-Button erscheint unten im Footer, wenn die Webseite über ein gültiges HTTPS (SSL-Zertifikat) verfügt. Der Button und das zugehörige JavaScript befinden sich in der layout.phtml.
  • Nach dem Installationsprozess verhält sich die Webseite wie eine native App, mit eigenem Icon und unabhängigem Fenster.

• Umgebungsvariablen:

  • Das Framework unterstützt `.env`-Dateien, um sensible Daten wie Datenbankzugang oder API-Schlüssel zu speichern.

  • Beispiel für eine `.env`-Datei:

    DEBUG=true
    DB_HOST=localhost
    DB_USER=root
    DB_PASS=secret
    MAIL_HOST=smtp.example.com

  • Variablen aus der `.env`-Datei sind mit $_ENV['VARIABLENAME'] zugänglich.

• Fehlerbehandlung:

  • Das Framework bietet integrierte Fehlerbehandlungsmechanismen:
  • Im Entwicklungsmodus (DEBUG=true):
    • Alle Fehler werden im Browser angezeigt.
    • Ungefangene Ausnahmen werden mit Stack-Traces ausgegeben.
  • Im Produktionsmodus (DEBUG=false):
    • Alle Fehler werden in Logdateien im Verzeichnis /logs/ gespeichert.
    • Standardmäßige Logdateien:
      • php-error.log für allgemeine PHP-Fehler.
      • errors.log für benutzerdefinierte Fehler.
      • exceptions.log für ungefangene Ausnahmen.

• Partials:

  • Die Methode $this->partial() erlaubt das Laden wiederverwendbarer Template-Dateien innerhalb von Views.

  • Beispiel:

    <?php echo $this->partial('navigation', ['active' => 'home']); ?>

  • Partials befinden sich standardmäßig im Verzeichnis /app/views/partials.

• Base URL:

  • Die Funktion base_url() liefert die Basis-URL der Webseite, einschließlich Protokoll und Domain.

  • Beispiel:

    <?php echo base_url(); ?> // Gibt https://example.com zurück

• Google reCAPTCHA v3:

  • CringePHP hat Google reCAPTCHA v3 bereits nativ integriert, um das Kontaktformular vor Spam und Missbrauch zu schützen.
  • Die Funktion ist direkt einsatzbereit, sobald die Zugangsdaten (Site Key und Secret Key) in der Datei /core/config.php eingetragen werden.
  • Nach der Einrichtung schützt reCAPTCHA v3 das Formular automatisch, ohne dass zusätzliche Schritte erforderlich sind.

• 404-Seite: Eine benutzerdefinierte 404-Fehlerseite ist bereits eingerichtet und sofort einsatzbereit. Bei ungültigen URLs wird automatisch die Datei /app/views/templates/404.phtml geladen.

• Helper-Funktionen:

  • Zusätzliche Helper-Funktionen können in /app/helpers.php abgelegt werden. Diese stehen dann im gesamten Projekt zur Verfügung und tragen zur Übersichtlichkeit und Wiederverwendbarkeit des Codes bei.
  • Beispiel: Eine einfache Datumsformatierungsfunktion könnte in den Helpers definiert sein und in einer View wie folgt verwendet werden:

  // In /app/helpers.php
  function formatDate($date) {
      return date("F j, Y", strtotime($date));
  }
  
  // In einer View (z. B. /app/views/pages/example.phtml)
  <?php echo formatDate("2023-01-01"); // Gibt "January 1, 2023" aus ?>

Leichtgewichtiger Ansatz: Kein Controller, kein Model

Um das CringePHP Boilerplate schlank und leichtgewichtig zu halten, wird auf den Einsatz von Controllern und Modellen verzichtet. PHP-Code kann direkt in den View-Dateien integriert werden, was eine schnelle und unkomplizierte Umsetzung ermöglicht.

Falls umfangreichere Server-Logik erforderlich ist, empfiehlt es sich, diese über die API-Funktionalität im Verzeichnis /app/api bereitzustellen. Dieser Ansatz ermöglicht eine saubere Trennung und bleibt dennoch leichtgewichtig.

Übersetzungen

• Die aktuelle Sprache ist in $this->lang gespeichert (z. B. 'de' oder 'en').
• Übersetzungen stehen sowohl für PHP als auch für JavaScript zur Verfügung, sodass mehrsprachige Inhalte leicht umgesetzt werden können.
• Unterstützte Sprachen können in der Datei /core/config.php ergänzt werden, wo auch die Standard-Sprache festgelegt wird.
• Die Sprachdateien befinden sich im Verzeichnis /language/.

<?php echo $this->translations['welcome_message']; ?>

const translations = <?php echo json_encode($this->translations); ?>;
const currentLang = '<?php echo $this->lang; ?>';
console.log(translations['welcome_message']);

Navigation mit aktiver Link-Erkennung

• Eine Navigationsleiste mit aktiver Link-Erkennung kann in CringePHP einfach erstellt werden, indem die aktuelle Route in $this->action abgefragt wird.
• Durch die dynamische Zuweisung der Klasse active kann die aktuell ausgewählte Seite in der Navigation hervorgehoben werden.

<nav>
    <ul>
        <li><a href="<?php echo $this->url('home'); ?>" class="<?php if ($this->action === 'home') echo 'active'; ?>"><?php echo $this->translations['home']; ?></a></li>
        <li><a href="<?php echo $this->url('about'); ?>" class="<?php if ($this->action === 'about') echo 'active'; ?>"><?php echo $this->translations['about']; ?></a></li>
        <li><a href="<?php echo $this->url('contact'); ?>" class="<?php if ($this->action === 'contact') echo 'active'; ?>"><?php echo $this->translations['contact']; ?></a></li>
    </ul>
</nav>

• Platzieren Sie diesen Code in der layout.phtml-Datei, um die Navigation auf allen Seiten der Webseite einheitlich anzuzeigen.

Struktur und Dateien

• Ordnerstruktur:
  • /public: Webroot, enthält alle öffentlichen Dateien, die direkt zugänglich sind, einschließlich CSS, JavaScript und Medien.
  • /app/views: Enthält alle View-Dateien, die für die Darstellung der Inhalte verantwortlich sind. Die Views sind in /pages (für Seiten), /templates (für Layouts und spezielle Templates wie die 404-Seite) und /partials (für wiederverwendbare Komponenten wie Navigation oder Header) unterteilt.
  • /app/routes.php: Definiert alle Routen der Webseite. Jede Route verweist auf eine spezifische View-Datei und kann Parameter enthalten.
  • /app/helpers.php: Beinhaltet projektweite Hilfsfunktionen, die in allen Views genutzt werden können.
  • /core: Beinhaltet systemkritische Dateien, wie config.php für die Konfiguration und Dispatcher.php, der das Routing und die View-Logik verwaltet.
  • /language: Enthält Sprachdateien für mehrsprachige Inhalte. Jede Sprache hat eine eigene Datei, in der alle Übersetzungen definiert sind.
• Layouts und Templates: layout.phtml befindet sich im Verzeichnis /app/views/templates und definiert das Grundgerüst der Seite. Es lädt die spezifischen Views dynamisch und sorgt so für ein einheitliches Layout auf der gesamten Webseite.
• Design und Funktionalität: /public/css/theme.css und /public/css/style.css sowie /public/js/core.js sind in separate Dateien und Verzeichnisse aufgeteilt. theme.css verwaltet die spezifischen Theme-bezogenen Styles, während style.css allgemeines Styling umfasst. core.js stellt die funktionalen JavaScript-Funktionen bereit.