Enhance project documentation with updated architecture, PostgreSQL integration, and local development setup. Refine admin panel and GitHub Actions details. Remove Firebase configuration from .env.example and clarify database fallback mechanisms.
This commit is contained in:
@@ -13,12 +13,12 @@ The project is architected to remain extremely lightweight and fast, intentional
|
||||
- `index.php`: The atmospheric landing page showcasing featured recipe selections, introducing the brand, and housing the **Sleek Swipe Discovery Carousel**.
|
||||
- `recipe.php`: The immersive recipe detail page, featuring floating macro-nutrition widgets, interactive ingredients lists, and the fullscreen **Step-by-Step Cooking Mode**.
|
||||
- `admin.php`: A custom, lightweight CMS/admin dashboard allowing full CRUD capabilities over the recipe database, dynamic ingredient line parsing, cooking timers, and video URL associations.
|
||||
- `login.php` & `register.php`: Fully responsive, glassmorphic auth portals powered by Firebase.
|
||||
- `login.php`: Local profile page for dietary goals and saved favorites (browser storage).
|
||||
- **Support & Layouts**:
|
||||
- `partials/`: Contains modular templates (`head.php`, `header.php`, `footer.php`) to maintain a clean DRY structure.
|
||||
- `helpers.php`: Core PHP utilities containing data formatting helpers and the data access layer for the flat-file database.
|
||||
- `config.php`: Environment-independent configuration loader which reads runtime secrets from `.env`.
|
||||
- `api/`: Lightweight, stateless backend endpoints supporting AJAX operations (e.g., newsletter subscriptions, bookmarks, recommendation queries).
|
||||
- `assets/fc-local.js`: Browser-side storage for favorites and dietary goals.
|
||||
- `data/`: Houses `recipes.json`, our flat-file recipe database.
|
||||
|
||||
---
|
||||
@@ -36,13 +36,9 @@ FlixCooks uses a modern, carefully curated vanilla tech-stack focused on lightni
|
||||
|
||||
### ⚙️ Backend & Data
|
||||
- **Engine**: Vanilla PHP.
|
||||
- **Database**: Flat-file JSON database (`data/recipes.json`), allowing lightning-quick load times and simple structural schemas without heavy overhead.
|
||||
- **Database**: PostgreSQL (production/staging) with automatic seed from `data/recipes.json`. Without `DATABASE_URL`, the app falls back to the JSON file.
|
||||
- **Environment**: Custom `.env` variable parser integrated into PHP bootstrap.
|
||||
|
||||
### 🔒 Integrations & Cloud Services
|
||||
- **Firebase Authentication**: Client and server-side synchronized user sessions for profile management.
|
||||
- **Firebase Firestore**: Real-time database managing newsletter subscribers and user bookmarks/favorites lists.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Local Development Setup
|
||||
@@ -51,7 +47,8 @@ Follow these simple steps to spin up the local development environment.
|
||||
|
||||
### Prerequisites
|
||||
Make sure you have the following installed on your local machine:
|
||||
- **PHP** (v7.4 or higher recommended)
|
||||
- **PHP** (8.x recommended) with the **pgsql** extension (`php-pgsql` on Linux/WSL)
|
||||
- **Docker** (for local Postgres via `docker-compose.dev.yml`)
|
||||
- A modern web browser
|
||||
|
||||
### 1. Set Up Environment Variables
|
||||
@@ -59,14 +56,59 @@ Make sure you have the following installed on your local machine:
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
2. Open `.env` and fill in your actual **Firebase project settings** (API keys, project identifier, authentication domain, etc.):
|
||||
```env
|
||||
FIREBASE_API_KEY="AIzaSyYourApiKeyHere"
|
||||
FIREBASE_AUTH_DOMAIN="flixcooks-your-project-id.firebaseapp.com"
|
||||
...
|
||||
```
|
||||
2. Open `.env` and optionally set **local Postgres** (see [Local Postgres (Docker)](#local-postgres-docker) below).
|
||||
|
||||
### 2. Start the Development Server
|
||||
### 2. Local Postgres (Docker)
|
||||
|
||||
Für DB-Integration auf einem Dev-Branch – getrennt von Production.
|
||||
|
||||
```bash
|
||||
# Container starten
|
||||
docker compose -f docker-compose.dev.yml up -d
|
||||
|
||||
# Warten bis healthy (einmalig prüfen)
|
||||
docker compose -f docker-compose.dev.yml ps
|
||||
```
|
||||
|
||||
In `.env` (Werte passen zu `docker-compose.dev.yml`):
|
||||
|
||||
```env
|
||||
DATABASE_URL="postgresql://flixcooks:flixcooks_dev@127.0.0.1:5432/flixcooks_dev"
|
||||
```
|
||||
|
||||
**PHP-Extension (WSL/Ubuntu, einmalig):**
|
||||
|
||||
```bash
|
||||
sudo apt install php-pgsql
|
||||
# oder passend zur Version: sudo apt install php8.5-pgsql
|
||||
```
|
||||
|
||||
**Datenbank-Shell (zum Lernen / Inspizieren):**
|
||||
|
||||
```bash
|
||||
docker exec -it flixcooks-postgres-dev psql -U flixcooks -d flixcooks_dev
|
||||
```
|
||||
|
||||
Nützliche SQL-Befehle in `psql`:
|
||||
|
||||
```sql
|
||||
\dt -- alle Tabellen
|
||||
\d recipes -- Spalten der Tabelle recipes
|
||||
SELECT slug, created_at FROM recipes;
|
||||
SELECT slug, data->>'title' AS title FROM recipes, jsonb_to_record(data) AS x(title text); -- optional
|
||||
\q -- beenden
|
||||
```
|
||||
|
||||
**DB komplett leeren und neu seeden** (lädt wieder aus `data/recipes.json` beim nächsten Seitenaufruf):
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml down -v
|
||||
docker compose -f docker-compose.dev.yml up -d
|
||||
```
|
||||
|
||||
Details zum Schema und Ablauf: Abschnitt unten in dieser README und `helpers.php` → `init_db()`.
|
||||
|
||||
### 3. Start the Development Server
|
||||
|
||||
#### Option A: PHP Built-in Web Server (Recommended & Easiest)
|
||||
You do not need to install complex local servers like Apache or Nginx. Simply run the following command in the root folder of the project:
|
||||
@@ -78,7 +120,7 @@ Then, open your browser and navigate to:
|
||||
http://localhost:8000
|
||||
```
|
||||
|
||||
#### Option B: Local Apache Environments (XAMPP / MAMP / WAMP)
|
||||
#### Option B: Local Apache (XAMPP / MAMP / WAMP)
|
||||
If you prefer running a full local stack:
|
||||
1. Move or link the project directory inside your local server's document root (e.g., `htdocs` or `www`).
|
||||
2. Ensure URL rewriting is enabled (the included `.htaccess` file handles caching and custom redirections).
|
||||
@@ -86,6 +128,32 @@ If you prefer running a full local stack:
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ Postgres in diesem Projekt (Kurzüberblick)
|
||||
|
||||
FlixCooks nutzt **eine Tabelle** – kein klassisches „eine Spalte pro Rezeptfeld“-Schema:
|
||||
|
||||
| Spalte | Typ | Bedeutung |
|
||||
|-------------|------------|-----------|
|
||||
| `slug` | `VARCHAR` | Eindeutige ID des Rezepts (URL: `/recipe.php?slug=...`) |
|
||||
| `data` | `JSONB` | **Gesamtes** Rezept als JSON (Titel, Zutaten, Schritte, i18n, …) |
|
||||
| `created_at`| `TIMESTAMP`| Erstellzeit |
|
||||
| `updated_at`| `TIMESTAMP`| Letzte Änderung (wird beim Update gesetzt) |
|
||||
|
||||
**Warum JSONB?** Das Rezept ist in PHP/JSON ohnehin ein Objekt. Statt 20+ SQL-Spalten zu pflegen, speichert ihr ein Dokument pro Zeile. PostgreSQL kann in `JSONB` trotzdem indexieren und abfragen (`data->>'title'`), wenn ihr später filtern wollt.
|
||||
|
||||
**Ablauf beim ersten Aufruf mit leerer DB:**
|
||||
|
||||
1. `config.php` liest `DATABASE_URL` → PDO-Verbindung.
|
||||
2. `init_db()` in `helpers.php` erstellt `recipes`, falls nicht vorhanden.
|
||||
3. Ist die Tabelle leer → Import aus `data/recipes.json`.
|
||||
4. `load_recipes()` liest alle Zeilen, dekodiert `data` zurück zu PHP-Arrays.
|
||||
|
||||
**Admin speichern:** `save_recipes()` schreibt nach Postgres **und** aktualisiert `data/recipes.json` als Backup.
|
||||
|
||||
Für **Staging/Production** setzt du `DATABASE_URL` in der jeweiligen Hosting-Umgebung – nie Production-Daten in der lokalen Dev-DB mischen.
|
||||
|
||||
---
|
||||
|
||||
## 📈 Development Tracking & Progress
|
||||
All current development tasks, features, and roadmaps are actively tracked and updated in the project’s [.agents/TODO.md](file:///.agents/TODO.md) file.
|
||||
Architectural learnings, conventions, and configuration updates are maintained in the central knowledge base: [.agents/brain.md](file:///.agents/brain.md).
|
||||
|
||||
Reference in New Issue
Block a user