# Projektbasis fuer neue Projekte Dieses Dokument kombiniert die Erklaerung des allgemeinen Projektaufbaus mit einer konkreten Startstruktur fuer neue Projekte. Ziel ist, dass neue Projekte dieselbe technische Basis verwenden und dieselben Regeln fuer Routing, Verzeichnisse, Module, Assets und Konfiguration einhalten. ## Grundprinzip Das Projekt basiert auf einer schlanken PHP-Struktur mit: - einem zentralen Web-Einstiegspunkt in `public/index.php` - einem zentralen Bootstrap in `config/fileload.php` - globalen Seiten unter `partials/landingpages/` - globalem Layout unter `partials/structure/` - optionalen Fachmodulen unter `modules/` - globalen Assets unter `public/assets/` - einer Deployment-gesteuerten Config-Aufteilung mit `config/staging/` und `config/prod/` ## Verbindliche Startstruktur fuer neue Projekte Die folgende Struktur soll als Basis fuer neue Projekte verwendet werden. Sie beruecksichtigt ausdruecklich auch die Basisverzeichnisse aus `.gitlab-ci.yml`. ```text / |-- .gitlab-ci.yml |-- GENERAL.md |-- api/ | `-- .gitkeep |-- config/ | |-- .gitkeep | |-- base_db.php | |-- config.php | |-- fileload.php | |-- prod/ | | |-- .gitkeep | | |-- db_settings_basic.php | | |-- domaindata.php | | `-- settings.php | `-- staging/ | |-- .gitkeep | |-- db_settings_basic.php | |-- domaindata.php | `-- settings.php |-- data/ | `-- .gitkeep |-- debug/ | `-- .gitkeep |-- modules/ | `-- .gitkeep |-- partials/ | |-- landingpages/ | | |-- .gitkeep | | `-- index.php | `-- structure/ | |-- .gitkeep | |-- layout_end.php | `-- layout_start.php |-- public/ | |-- .gitkeep | |-- .htaccess | |-- index.php | `-- assets/ | |-- css/ | | |-- .gitkeep | | `-- app.css | |-- images/ | | `-- .gitkeep | `-- js/ | |-- .gitkeep | `-- app.js |-- src/ | |-- .gitkeep | |-- App/ | | |-- .gitkeep | | |-- App.php | | |-- Assets.php | | |-- Config.php | | |-- Database.php | | |-- ModuleManager.php | | `-- functions.php | `-- Repository/ | `-- .gitkeep `-- tools/ `-- .gitkeep ``` ## Pflichtordner Diese Ordner muessen als Basis immer vorhanden sein, weil sie entweder vom Projektaufbau oder vom Deployment vorausgesetzt werden: - `api/` - `config/` - `data/` - `debug/` - `modules/` - `partials/` - `public/` - `src/` - `tools/` Diese Liste entspricht der Deploy-Basis aus `.gitlab-ci.yml` plus den notwendigen Unterordnern fuer die Anwendung. ## Regel fuer leere Ordner Wenn ein notwendiger Ordner anfangs noch keine echten Dateien enthaelt, muss er eine leere Datei mit dem Namen `.gitkeep` enthalten. Das gilt insbesondere fuer: - `api/` - `data/` - `debug/` - `modules/` - `tools/` - `public/assets/images/` - `src/Repository/` - weitere leere Unterordner, die im Template bereits vorgesehen sind Damit bleiben die Verzeichnisse versionierbar und werden beim Kopieren und Deployment nicht versehentlich ausgelassen. ## Rollen der wichtigsten Verzeichnisse ### `public/` `public/` ist der Webroot. Hier liegen: - `index.php` als zentraler Router - globale Assets unter `public/assets/` - Webserver-Dateien wie `.htaccess` ### `src/` `src/` enthaelt den PHP-Kern der Anwendung. - `src/App/` fuer App-Klassen, Bootstrap-nahe Logik, Config, Assets, Datenbank, Request, Session und Modulverwaltung - `src/Repository/` fuer Datenzugriffslogik ### `partials/` `partials/` enthaelt globale Templates. - `partials/landingpages/` fuer globale, direkt routbare Seiten - `partials/structure/` fuer das globale Layout ### `modules/` `modules/` enthaelt fachlich getrennte Erweiterungen. Jedes Modul bleibt in seinem eigenen Ordner und kapselt Seiten, Assets, Partials und optionale Bootstrap-Logik. ### `api/` `api/` ist fuer API-Funktionen vorgesehen, falls das Projekt eigene API-Endpunkte anbieten soll. Wenn ein Projekt keine API bereitstellt, kann der Ordner leer bleiben, soll aber als Teil der Basisstruktur dennoch vorhanden sein. ### `config/` `config/` enthaelt den Bootstrap der Konfiguration sowie die umgebungsspezifischen Quellverzeichnisse `staging` und `prod`. ### `tools/` `tools/` ist fuer CLI-Skripte, Worker und Hilfsprogramme vorgesehen. ## Routing- und Renderstruktur ### `public/index.php` `public/index.php` ist der einzige Web-Einstiegspunkt und uebernimmt: - Laden von `config/fileload.php` - Normalisierung des Request-Pfads - Pruefung optionaler Authentifizierung oder Schutzregeln - Routing auf globale Seiten unter `partials/landingpages/` - Routing auf Modulseiten unter `modules//pages/` - 404-Behandlung - Rendern des Inhalts innerhalb des globalen Layouts ### Globale Seiten Globale Seiten liegen unter `partials/landingpages/`. Das Routing ist dateibasiert, also ohne externen Framework-Router. Beispiele: - `/` -> `partials/landingpages/index.php` - `/users` -> `partials/landingpages/users/index.php` ### Layout Die globale HTML-Struktur liegt unter `partials/structure/`. - `layout_start.php` oeffnet das Seitenlayout - `layout_end.php` schliesst es ### Module Modulrouten folgen dem Schema: ```text /module/ /module// ``` Diese Routen verweisen auf Dateien unter: ```text modules//pages/ ``` ## Modulstruktur fuer neue Projekte Wenn ein neues Projekt Module verwendet, sollte jedes Modul nach demselben Muster aufgebaut sein: ```text modules// |-- assets/ | `-- .gitkeep |-- pages/ | |-- .gitkeep | `-- index.php |-- partials/ | `-- .gitkeep |-- bootstrap.php `-- module.json ``` Regeln: - modulspezifisches CSS und JavaScript bleibt unter `modules//assets/` - globale Assets gehoeren nicht in Modulordner - Modulcode gehoert nicht nach `public/assets/` - Seiten eines Moduls liegen unter `pages/` - wiederverwendbare Modul-Templates liegen unter `partials/` ## Asset-Struktur ### Globale Assets Projektweite Dateien liegen unter: - `public/assets/css/` - `public/assets/js/` - `public/assets/images/` ### Modul-Assets Modulbezogene Dateien liegen unter: - `modules//assets/` Neue Projekte sollen diese Trennung konsequent beibehalten. ## Config-Aufteilung mit `staging` und `prod` Dieser Teil ist fuer neue Projekte verpflichtend. ### Quellverzeichnisse im Repository Im Repository liegen die umgebungsspezifischen Config-Quellen unter: ```text config/staging/ config/prod/ ``` Darin liegen typischerweise: - `domaindata.php` - `settings.php` - `db_settings_basic.php` ### Laufzeitlogik Die Anwendung selbst laedt zur Laufzeit nicht direkt aus `config/staging/` oder `config/prod/`, sondern aus dem Root von `config/`, also z. B.: - `config/settings.php` - `config/domaindata.php` - `config/db_settings_basic.php` `config/fileload.php` erwartet genau diese Root-Dateien. ### Deployment-Regel Beim Deployment wird die passende Umgebung in das aktive `config/`-Root kopiert: 1. allgemeine Root-Dateien aus `config/` werden bereitgestellt 2. je nach Branch wird die Umgebungsvariante darueberkopiert 3. `develop` verwendet `config/staging/` 4. `main` verwendet `config/prod/` 5. im Zielsystem gelten die kopierten Dateien danach so, als waeren sie direkt normale Root-Configs Neue Projekte muessen exakt dieses Prinzip uebernehmen. ## Domain-Pflicht fuer neue Projekterstellungen Neue Projekte duerfen nur erstellt werden, wenn beide Domains vorliegen: - Live-Domain - Staging-Domain Diese Domains muessen in den umgebungsspezifischen Config-Dateien verwendet und automatisch eingetragen werden, insbesondere in: - `config/prod/domaindata.php` - `config/prod/settings.php` - `config/staging/domaindata.php` - `config/staging/settings.php` - `.gitlab-ci.yml`, falls dort Domainreferenzen oder Umgebungs-URLs hinterlegt sind ## Verbindliche Erstellungsregel Wenn bei der Aufgabenstellung fuer ein neues Projekt keine Domains angegeben werden, muss vor der Projekterstellung explizit nach beiden Werten gefragt werden. Die Erstellung ist in diesem Fall zu blockieren. Sie darf erst fortgesetzt werden, wenn beide Angaben vorhanden sind: 1. Live-Domain 2. Staging-Domain Fehlt mindestens eine der beiden Angaben, muss die Erstellung unterbunden werden mit einem klaren Hinweis, dass die Domains fehlen. ## Reset-Regel fuer neue Projekterstellungen Vor der eigentlichen Erstellung eines neuen Projekts muessen alle bestehenden Dateien und Ordner im Repository entfernt werden, mit genau einer Ausnahme: - `.gitlab-ci.yml` Die bestehende `.gitlab-ci.yml` bleibt erhalten, weil sie die Deploy-Basis vorgibt. Sie muss jedoch im Zuge der neuen Projekterstellung geprueft und angepasst werden, wenn darin Domainreferenzen, Umgebungs-URLs oder projektspezifische Zielpfade enthalten sind. Fuer neue Projekterstellungen gilt deshalb verbindlich: 1. vorhandene Projektdateien und Projektordner loeschen 2. `.gitlab-ci.yml` behalten 3. `.gitlab-ci.yml` auf alte Domain- oder Projektreferenzen pruefen 4. vorhandene Domainreferenzen in `.gitlab-ci.yml` auf die neue Live- und Staging-Domain anpassen 5. danach erst die neue Basisstruktur und die neuen Basisdateien erstellen ## Mindestinhalt der Config-Dateien Die folgenden Dateien koennen als Basis aus diesem Projekttyp uebernommen werden und muessen pro neuem Projekt angepasst werden: - `config/fileload.php` - `config/config.php` - `config/base_db.php` - `config/prod/domaindata.php` - `config/prod/settings.php` - `config/staging/domaindata.php` - `config/staging/settings.php` Dabei gilt: - die allgemeine Config-Logik kann uebernommen werden - domainspezifische Werte muessen pro Projekt ersetzt werden - staging und prod muessen immer unterschiedliche Zielwerte bekommen, sofern nicht ausdruecklich anders gefordert ## Basisdateien fuer neue Projekte Neben der Ordnerstruktur werden fuer neue Projekte auch Basisdateien benoetigt, insbesondere im Config-Bereich. Die konkreten Inhalte sind in einer separaten Datei beschrieben: - `BASE_FILES.md` Diese Datei ist dafuer gedacht, nach dem Anlegen eines neuen GitLab-Projekts zusammen mit `GENERAL.md` in das neue Repository kopiert zu werden, damit die Erstellung der Grundstruktur und der Konfigurationsdateien direkt auf einer klaren Vorlage basiert. ## Kurzfassung fuer neue Projekte Neue Projekte auf dieser Basis verwenden: - einen zentralen Router in `public/index.php` - einen zentralen Bootstrap in `config/fileload.php` - globale Seiten in `partials/landingpages/` - globale Layout-Dateien in `partials/structure/` - optionale Module in `modules/` - globale Assets in `public/assets/` - modulspezifische Assets in `modules//assets/` - eine Deploy-gesteuerte Config mit `config/staging/` und `config/prod/` Leere Pflichtordner erhalten immer `.gitkeep`. Eine neue Projekterstellung ist nur zulaessig, wenn sowohl Live- als auch Staging-Domain vorab angegeben wurden.