phpMyCellar

A lightweight, self-hosted fine wine cellar management notebook, tasting notes journal, and interactive cellar menu built with modern PHP and MariaDB.

---

Overview

phpMyCellar is designed for wine enthusiasts, collectors, and sommeliers who want full ownership over their wine collection data and tasting impressions. Unlike closed commercial platforms, phpMyCellar provides a private or public-facing digital cellar notebook with zero tracking, external telemetry, or cloud subscriptions.

What phpMyCellar Is:

• A Personal Cellar Manager: Track individual bottles, bottle formats, storage locations, purchase costs, merchant orders, and delivery statuses.
• A Detailed Tasting Journal: Record tasting notes with support for multiple rating scales (20-point scale, 100-point scale, and optional WSET SAT criteria), blind tastings, and high-resolution photography.
• An Interactive Wine Menu (Carte des vins): Generate an elegant, shareable wine menu for family, dinner guests, and tasting groups showing what is ready to drink.
• A Wine Blog & Story Publishing System: Write long-form tasting horizontal/vertical reports, winery visits, and vintage overviews.
• Privacy-First & Self-Hosted: Run on any standard PHP hosting provider, VPS, or container environment with full data ownership.

What phpMyCellar Is Not:

• An e-commerce marketplace or POS point-of-sale terminal.
• A commercial wine rating aggregator or barcode-scraping mobile application.

---

Key Features

Category	Highlights
Cellar Management	• Track producers, wine masters, appellations, vineyards, and vintages. • Multiple bottle formats (375ml half-bottles, 750ml, 1500ml magnums, and large formats). • Storage location bin tracking (e.g. Rack A1, Shelf 3). • Purchase order management with delivery receipts and PDF invoice uploads.
Tasting Notes	• Detailed sensory evaluations with drinking window forecasting. • Configurable rating scales: 20-point scale and 100-point scale with optional WSET SAT assessment. • Blind tasting mode allowing notes to be drafted before revealing the wine. • Automatic SEO metadata, OpenGraph tags, and JSON-LD structured data.
Interactive Menu	• Live Carte des vins highlighting ready-to-drink wines for guests. • Filter by colour, style, vintage, grape variety, and producer. • Sortable by producer, vintage, or wine style with visual colour badges.
Stories & Articles	• Integrated WYSIWYG editor with captioned image insertion. • In-depth vintage report overviews dynamically aggregated from tasting history. • Public commenting system with email subscription notifications.
Security & RBAC	• Granular Role-Based Access Control (Public, Reader, Contributor, Admin). • Granular user privilege overrides. • Synchronizer CSRF tokens on all state-changing actions. • Hardened uploads/ directory with script execution restrictions.
Customisation	• Dynamic branding: Site name, tagline, base URL, currency symbol, and owner details. • Real-time theme accent colour customisation. • Database-managed static pages (Welcome, Impressum, Privacy Policy, Rating Scale guide).

---

Technology Stack

• Backend: PHP 7.4+ (PHP 8.1 / 8.2+ recommended) with native mysqli prepared statements.
• Database: MariaDB 10.4+ / MySQL 8.0+ (utf8mb4 character set).
• Frontend: Semantic HTML5, Vanilla JavaScript, and responsive CSS (zero bulky frontend build pipelines).
• Architecture: Lightweight MVC-inspired structure with standalone server portability.

---

Quick Start Installation

Option 1: Web Setup Wizard (Standard Hosting / VPS)

1. Upload Files: Upload the phpMyCellar codebase to your web server document root (e.g. /var/www/html or public_html).
2. Server Configuration:
   • For Apache, copy .htaccess.example to .htaccess.
   • For Nginx, configure your server block using nginx.conf.example.
3. Set Permissions: Ensure the web server has write permissions to:
   • Root directory . (for .env creation)
   • install/ (for installed.lock creation)
   • uploads/, uploads/invoices/, and uploads/img/
4. Launch Wizard: Navigate to http://your-domain.com/ in your web browser. The setup wizard will guide you through:
   • System requirement & extension checks.
   • Database connection testing and automatic schema/seed execution.
   • Super-administrator (user_id = 1) account creation.
   • Initial site branding and currency configuration.
5. Done! The wizard writes your .env configuration and locks the installer.

---

Option 2: Docker Compose (Local Development & Container Deployments)

1. Clone the Repository:

   git clone https://github.com/dmueller-dev/phpMyCellar.git
   cd phpMyCellar

2. Start the Stack:

   docker compose up -d --build

3. Complete Installation: Open your browser at http://localhost:8080/install/ to complete the web wizard.

---

Directory Structure

phpMyCellar/
├── backend/               # Administrative management interfaces
├── includes/              # Shared helper functions, styles, scripts, and init
│   ├── functions.php      # Business logic, SEO schema, and database helpers
│   ├── header.php         # Global HTML header, navigation, and theme loader
│   ├── footer.php         # Global footer
│   ├── init.php           # Database initialization and privilege middleware
│   ├── styles.css         # Responsive typography and layout stylesheets
│   └── wysiwyg.js         # Rich-text editor integration
├── install/               # Installation wizard & database migration scripts
│   ├── index.php          # Interactive setup wizard
│   ├── schema.sql         # Database table definitions
│   └── seed.sql           # Lookup tables, default privileges, and static content
├── manual/                # Comprehensive User & Administrator Manual
├── uploads/               # User upload directories (hardened with .htaccess)
│   ├── img/               # Wine bottle photos and blog post imagery
│   └── invoices/          # Order invoice PDFs and merchant receipts
├── Dockerfile             # Production-ready PHP 8.2 Apache container
├── docker-compose.yml     # Local orchestration stack with MariaDB
├── .env.example           # Environment template
├── .htaccess.example      # Apache server configuration template
├── nginx.conf.example     # Nginx server block configuration template
└── SECURITY.md            # Security policy and vulnerability disclosure

---

Documentation & Manual

Full user guides and administrator manuals are available in the manual/ directory:

• 01. Welcome & Core Philosophy
• 02. Getting Started & Installation
• 03. Wine Cellar & Order Management
• 04. Tasting Notes, Ratings & Blind Tastings
• 05. Stories, Articles & Image Publishing
• 06. User Accounts, Roles & Privileges
• 07. Site Customisation & Static Pages
• 08. Maintenance, Backups & Security

---

Contributing

We welcome contributions of all kinds! Please read our Contributing Guidelines and Code of Conduct before submitting pull requests or opening issues.

---

Security

Please review SECURITY.md for information regarding supported versions and responsible vulnerability disclosure.

---

Licence

This project is licensed under the terms of the MIT Licence. See the LICENSE file for details.