Skip to content

Home

Jump to bottom
Rudolf Klusal edited this page Apr 30, 2026 · 2 revisions

PHP Gallery – Wiki

Welcome to the official wiki for the PHP Gallery project.

This project is a lightweight, filesystem-driven photo gallery system built in pure PHP, designed to keep data simple, portable, and under your control.

Overview

PHP Gallery is built around a simple but powerful idea:

The filesystem is the source of truth. The database is only an index and metadata layer.

This means:

  • Your images and galleries exist as real folders and files
  • No lock-in to database-only storage
  • Easy backups, migrations, and manual edits
  • Predictable structure

Core Concepts

1. Filesystem-first architecture

  • Galleries are represented as folders
  • Images are stored directly inside those folders
  • Optional metadata is stored alongside (e.g. gallery.json)

The application scans and synchronizes these into the database.

2. Database as index layer

The database is used for:

  • Fast lookups
  • Permissions and access control
  • Metadata (titles, descriptions, ratings)
  • Relationships (parent / child galleries)

It is not required for the actual image storage.

3. Nested gallery structure

Supports hierarchical galleries:

galleries/ ├── Travel/ │ ├── Iceland/ │ │ ├── img1.jpg │ │ └── img2.jpg │ └── Italy/ └── Aviation/

  • Unlimited nesting depth
  • Automatic detection of sub-galleries
  • Recursive navigation

4. Admin-controlled synchronization

New folders are not auto-imported silently.

Instead:

  • Admin explicitly scans for new galleries
  • Chooses what to include
  • Avoids performance overhead and unintended indexing

5. Image handling

  • Automatic discovery of images
  • Thumbnail generation
  • Clean linking structure
  • Direct file-based storage

Features

Gallery Management

  • Create galleries via filesystem or admin panel
  • Detect new folders
  • Rename and reorganize
  • Move items between galleries

Image Features

  • Thumbnails
  • Metadata support (description, comments)
  • Rating system (optional)
  • Download gallery as ZIP

Navigation

  • Tree-based gallery structure
  • Nested browsing
  • Breadcrumb navigation

SEO Optimization

  • Clean URLs (if enabled)
  • Indexable gallery pages
  • Image-level pages
  • Structured metadata support

Permissions

  • Admin vs public access
  • Gallery-level visibility
  • Controlled editing

Architecture Overview

[ Filesystem ] │ ▼ [ Scanner / Sync Layer ] │ ▼ [ Database (index + metadata) ] │ ▼ [ Controllers / Services ] │ ▼ [ Public UI / Admin UI ]

Typical Workflow

Adding a new gallery

  1. Create a folder in /galleries
  2. Upload images
  3. Open admin panel
  4. Run "Scan for new galleries"
  5. Confirm import

Editing metadata

  • Use admin UI
  • Stored in database (and optionally JSON)
  • Does not affect original files

Downloading a gallery

  • Select gallery
  • Click download
  • System generates ZIP dynamically

Installation (High-level)

  1. Clone repository
  2. Set up PHP environment
  3. Configure database
  4. Run installer (install.php)
  5. Set write permissions for thumbnails, cache, uploads

Requirements

  • PHP 8.x recommended
  • MySQL / MariaDB
  • GD or Imagick
  • ZipArchive

Design Principles

  • Simplicity over abstraction
  • Filesystem as truth
  • Minimal dependencies
  • Manual control instead of automation
  • Readable PHP over framework complexity

Contributing

Contributions are welcome.

Author

Rudolf Klusal https://github.com/klusik

Clone this wiki locally