Photo7 Platform
Professional Photography Portfolio + Fine-Art Print Shop
A complete, production-ready platform for photographers to showcase their work and sell museum-quality prints worldwide. Built with performance, SEO, and user experience as core priorities.
Personas & Goals
- Visitor / Customer: Browse albums and photos, explore tags and search, add comments, purchase fine-art prints with worldwide shipping and PayPal checkout.
- Admin / Photographer: Curate albums and photos, extract and edit metadata, generate AI descriptions, manage menus and settings, moderate comments, fulfill orders, and monitor performance.
Public Experience
- Home: Hero slideshow of highlighted photos plus an album grid with client-side filtering by title, location, date, and description.
- Albums: Hierarchical, human-readable URLs; header shows title, location, and date; AI-ready descriptions; responsive masonry gallery with admin controls; approved comments and submission form; visibility toggle via
is_active.
- Smart Masonry Layout:New Intelligent gallery algorithm that handles panoramic photos gracefully. Extra-wide images span 2-3 columns, layout minimizes gaps, and responsive breakpoints ensure optimal display on all devices.
- Photos: Large display with caption, metadata cards (camera/exposure, dimensions, date taken, GPS with Google Maps link, IPTC/XMP highlights), keyword tags, approved comments, and Buy Print modal with size/price selection.
- Theme Switching:New Seamless light/dark mode toggle with cookie persistence. Works across localhost and production environments with environment-aware cookie settings for HTTPS compatibility.
- Original Resolution Display:New Photos now display at original resolution instead of 1600px long side, maintaining image quality while converting to optimized WebP format.
- Smart Image Preloading:New Next and previous photos preload automatically in both normal and fullscreen viewing modes for instant navigation transitions.
- Fullscreen Viewer:New Immersive distraction-free viewing with pure black background. Toggle with Space key, expand button, or double-click. Photo scales to fit screen while preserving aspect ratio.
- Photo Navigation:New Keyboard arrows, mouse wheel scrolling, and touch swipe gestures for seamless browsing. Fullscreen state persists across photos via sessionStorage.
- AJAX Fullscreen Navigation:New Navigate between photos in fullscreen mode without page reload. URL updates via History API, images preload for instant transitions, and main page syncs when exiting fullscreen.
- Tags: Searchable tag cloud and tag detail pages showing all matching photos across albums.
- Search: Full-text search across photos, albums, and keywords with grouped results; robots
noindex to avoid indexing results pages.
- Search Page Ads:New Google AdSense banner displayed on search results pages, positioned before search results for optimal visibility.
- Static pages: About (with external profile links), Contact form, and Return Policy; consistent layout throughout.
- Notification Bar:New Site-wide announcement banner with customizable message, background and text colors for promotions and important notices.
- Seasonal Effects:New Animated particles (snowflakes, cherry blossoms, fireflies, leaves) overlay the site based on current season or admin selection. Configurable intensity with accessibility support.
- Error handling: Smart 404 extracts path terms and redirects to search to keep users on relevant content.
Performance & CachingNew
- File-Based HTML Cache: Complete HTML pages cached on disk for anonymous visitors, bypassing PHP/database entirely on cache hits.
- Configurable TTL: Admin-controlled cache lifetime (default 1 hour) with automatic expiration and refresh.
- Smart Invalidation: Automatic cache clearing when albums, photos, comments, or settings change. Surgical invalidation targets only affected pages.
- Theme-Aware Caching:New Cache keys include theme preference to prevent theme switching delays. Automatic cache clearing when users toggle between light/dark modes.
- Real-Time Statistics: Admin dashboard shows cached page count, total cache size, and oldest entry. One-click purge all functionality.
- On-demand WebP variants: Thumb/preview generators create optimized WebP files on first request, respecting portrait/panorama sizing.
- Lazy evaluation: Expensive operations deferred until needed; database queries minimized.
- View counters: Album and photo views tracked efficiently with batched updates.
Visitor AnalyticsNew
- Accurate Visitor Tracking:Fixed Resolved critical bug causing 16x visitor count inflation from duplicate tracking calls. IP addresses hashed for unique visitor counting without storing identifiable information. Comprehensive bot detection filters out crawlers and automated traffic.
- Page Type Classification: Visits categorized by page type (home, album, photo, search, tag) for granular insights into user behavior.
- Visit Debouncing: Same visitor/page combinations within 30 minutes counted as single visit to avoid inflating metrics from refreshes.
- Site Activity Chart: Interactive bar chart showing daily visitors, comments, and orders for the last 14 days using Chart.js.
- Geographic Analytics: Visitor country detection via IP geolocation (ip-api.com). Dashboard displays country breakdown with emoji flags, country names, and visit counts for the last 30 days.
- Interactive World Map: jsVectorMap-powered choropleth visualization of visitor geography. Color intensity scales from violet (fewer) to accent color (more) with hover tooltips showing country and visit count. Scroll zoom and drag navigation supported.
- Traffic Source Tracking:New HTTP referrer capture automatically logs which external sites send visitors. Dashboard shows top 15 referrers with domain name, visit count, and category (Search, Social, Website).
- Smart Referrer Icons:New Recognized referrers display branded icons (Google, Bing, Facebook, Twitter, Instagram, LinkedIn, Pinterest, Reddit, YouTube, etc.) with appropriate color coding by category.
- Traffic Sources Tile:New Dashboard stat tile showing count of unique referrer domains, linking directly to the detailed traffic sources panel.
- Session-Cached Geolocation: Country lookups cached in session to minimize API calls. Private/local IPs skipped automatically.
- Statistics Overview: Summary cards displaying today's, weekly, and monthly visitor counts with unique visitor breakdowns.
- Analytics Settings Tab: Dedicated admin settings section to enable/disable tracking and configure data retention period (7-3650 days).
- Automatic Cleanup: Old records purged based on retention setting. Manual cleanup button (red danger styling) for immediate space recovery.
- Admin Exclusion: Logged-in admin visits not counted to keep metrics focused on real visitor traffic.
Seasonal EffectsNew
- Festive Visual Effects: Animated particles overlay the site for seasonal ambiance. Four distinct effects available: Winter snowflakes, Spring cherry blossoms, Summer fireflies, and Autumn falling leaves.
- Auto-Detection: Season automatically detected based on current date using Northern Hemisphere calendar (Dec-Feb: Winter, Mar-May: Spring, Jun-Aug: Summer, Sep-Nov: Autumn).
- Manual Override: Admin can force a specific season regardless of date for special occasions or regional preferences.
- Intensity Control: Three levels (Low, Medium, High) controlling particle density from subtle accent to festive celebration.
- Live Preview: Settings page includes interactive preview panel showing selected effect before enabling site-wide.
- Season Calendar: Visual reference showing date ranges for each season with emoji indicators.
- Performance Optimized: CSS-only animations with will-change hints for smooth 60fps rendering. Particles use pointer-events: none to avoid interfering with clicks.
- Accessibility Compliant: Respects
prefers-reduced-motion media query to disable effects for users who prefer less motion.
- Admin Excluded: Effects only display on public pages, keeping admin interface distraction-free.
Commerce & Orders
- Photo SKUs:New Unique SKU identifier for every photo (
ALB{id}-PH{id} format), auto-generated on upload, displayed in admin interface for inventory tracking.
- Cart & checkout: Session cart with quantities, subtotal, shipping estimate, and checkout form; header cart badge updated via AJAX.
- Print sizing: Configurable sizes (cm) with prices and sort order; only active sizes exposed to buyers.
- Shipping zones: Country-aware pricing and delivery estimates; worldwide fallback.
- Payments: PayPal order creation and capture (sandbox/live) with storage of order/capture IDs; graceful error handling.
- Promo codes: Percentage discounts with expiration dates, validated at checkout.
- Orders: Unique order numbers, status lifecycle (pending → paid → processing → shipped → completed / cancelled / refunded), timestamps, customer and shipping details, line items with chosen size and pricing.
- Return Policy:New Professional return policy page (defective products only, 14-day reporting) with link included in order confirmation emails.
- Notifications: HTML email to admin on new orders; customer confirmation email with order details and return policy link.
Discovery, Metadata & SEO
- Dynamic Page Titles:New All pages feature contextual, SEO-optimized titles incorporating site name, photographer name, and relevant content descriptors.
- Unified Email Branding:New All system emails (contact form, comment notifications, order confirmations) use consistent subject lines with site name from settings.
- Rich metadata: EXIF/IPTC/XMP extracted on upload; stored as JSON for reuse; camera/exposure, GPS (with DMS + map link), IPTC location/credits surfaced on photo pages.
- Smart Content Filtering:New Automatic removal of promotional text from photo descriptions during upload and metadata reprocessing. Handles variations including HTML links and multi-line content.
- Keyword system: Keywords extracted from metadata and normalized to slugs; keyword counts maintained in DB; tag pages and tag cloud drive discovery.
- SEO foundations: Centralized meta builder with per-page overrides; OpenGraph/Twitter tags; canonical URLs; sitemap covering home, static pages, active albums/photos, and tags.
- Hierarchical URLs: Country/region/city/year/month path segments for albums and photos; legacy routes preserved with redirects.
- Smart 404 → search: Missing URLs extract letter tokens and redirect to
/search to recover traffic.
- Google Ads Integration:New Horizontal graphical banner ads on album pages with responsive design for mobile compatibility. Full
ads.txt support for Google AdSense monetization.
Admin Console
- Dashboard: Stats for albums, photos, comments (approved/pending), orders, and cache; quick links with accent-colored icons.
- Tabbed Settings:New Reorganized into 9 tabs (General, Appearance, Content, Social, Shop, Performance, API, Analytics, Effects) with AJAX save and toast notifications.
- Albums: Sortable/filterable table; edit view with metadata fields; tools to scan upload folders, set covers, extract EXIF/GPS, delete photos, regenerate keywords, and AI-generate descriptions.
- Smart Album Sorting:New Fixed default sort order display on album listing pages. "Oldest First" correctly shows oldest albums first, matching user expectations.
- AJAX Album Save:New Album edits save without page reload with toast notification feedback.
- Photos: Edit view with preview, filename, public URL, SKU display, title/description/slug editing, metadata reset.
- Photos List:New Dedicated admin page with paginated table of all photos. Instant AJAX search across titles, albums, and SKUs. Sortable columns, direct links to photo pages and edit views.
- Comments: Pending and recent approved tables with bulk actions; target badges link to public pages.
- Menu: Manage header/footer items with labels, URLs, sort order, and visibility.
- Orders: List with filters and colored status badges; detail page shows items, customer/shipping info, PayPal IDs, totals, status updates, and order deletion.
- Cache Dashboard Tile:New Real-time cache statistics with page count, size, and visual status indicator.
Comments & Safety
- Public comments: Supported on albums and photos with name/email (email optional) and validation; displayed only when approved.
- Moderation: Admin list with pending and recently approved tabs; single and bulk approve/delete; context links back to album/photo.
- Comment Seeding:New CLI tool for generating realistic test comments with international names, multiple languages, name-target uniqueness, and per-name comment limits.
- Notifications: Admin email when new comment is submitted and pending review.
- Spam protection: Contact form uses honeypot, CSRF token, and minimum submit time; spam attempts logged.
- Content safety: Captions sanitized to allow only safe HTML; comment bodies stored for moderation.
Media Handling
- Uploads: Per-album directories under
public/uploads/{album_id}; mass upload UI; EXIF read on ingest.
- On-demand WebP variants: Thumb/preview generators create optimized WebP files on first request, respecting portrait/panorama sizing; auto-fallback to originals if GD/WebP unavailable.
- Enhanced Image Optimization:New Combined optimization and quality preview panels in admin settings. Side-by-side quality and file size display (e.g., "80% Quality (~34 KB)") for better compression decision making.
- Metadata refresh: Admin tools to re-extract metadata, keywords, and GPS; "Reset from file" restores title/description/slug from IPTC/XMP/EXIF.
- Slugging: Hierarchical slugs with uniqueness checks; regeneration helpers if left blank.
- SKU Management:New Automatic SKU generation for all photos with unique constraint enforcement.
Architecture & Technology
- Stack: PHP 8+ with MariaDB/MySQL; custom lightweight MVC with
Router, controller classes, and template views.
- Routing: Named parameter patterns compiled to regex; 404 handler renders template and smart redirects.
- Configuration: Settings loaded from DB with config fallbacks; accent color and theme propagated via CSS variables.
- Services: Cart (session), ImageVariants (WebP), MetadataExtractor (ExifTool + PHP fallbacks), AIService (ChatGPT), SlugGenerator, SpamProtection, UrlBuilder, EmailTemplate, PageCache, PageVisits, SeasonalEffects.
- Caching Layer:New File-based PageCache service with intelligent invalidation, TTL management, and admin controls.
- Emails: HTML email rendering helper; logging to
storage/mail.log when sending fails or debug mode is on.
- Storage & logs: Storage directory for mail/spam logs and page cache; uploads stored under
public/uploads with generated variants.
- Docker support: Development environment with containerized database.
Data Model Snapshot
- Albums: title, slug, description, country/region/city, year/month, cover photo, active flag, views; has many photos and comments.
- Photos: album link, SKU, filename/filepath, title/description, dimensions, taken_at, camera make/model, GPS, EXIF JSON, metadata JSON, slug, views; keywords, comments, purchasable prints.
- Keywords: keyword, slug, photo_count; many-to-many with photos.
- Comments: target (album/photo), author name/email, content, approved flag, timestamps.
- Settings: key/value store with types (string, text, number, boolean, color, select) for identity, branding, SEO, social, API keys, shop settings, promo codes, cache configuration.
- Print sizes: name, dimensions, price, active flag, sort order.
- Shipping zones: name, countries list, price, delivery days, sort order.
- Cart (session): photo_id, print_size_id, quantity, promo.
- Orders: order number, status, customer details, shipping country/zone, subtotal/shipping/total, currency, PayPal IDs, notes, timestamps; related order items.
- Page Cache:New File-based cache entries with URL hashing, TTL tracking, and metadata.
- Page Visits:New Analytics records with page type, page ID, timestamp, visitor hash, country code, and referrer domain for tracking, charting, geographic insights, and traffic source analysis.
- Menus: Admin-managed navigation entries for header/footer.
Integrations & Automation
- OpenAI: Generate album descriptions from album and photo metadata when an API key is configured.
- PayPal: Checkout flow for creating and capturing orders (sandbox/live), with detailed error messages surfaced to the UI.
- Google Maps: GPS coordinates converted to human-readable form with interactive map links on photo pages.
- Google AdSense:New ads.txt support for monetization.
- Email delivery: mail() with HTML templates; automatic logging fallback keeps audit of outbound messages.
- External Profiles:New Integration links for NomadMania (travel), JetLovers (flights), Strava (sports), Colnect (stamps), and custom project showcases.
- Chart.js:New Lightweight charting library for rendering interactive visitor analytics graphs on the admin dashboard.
- jsVectorMap:New Interactive SVG world map library for visualizing visitor geography with custom color schemes and tooltips.
- IP Geolocation:New Integration with ip-api.com for free, API-key-free country detection. 2-second timeout prevents page slowdowns; results cached in session.
Developer Experience
- CLI Tools:New Command-line scripts for database migrations, SKU backfilling, and comment seeding with extensive options (--count, --type, --approve, --dry-run, --batch, --seed).
- Toast Notifications: Modern notification system for user feedback with success, error, and warning states.
- AJAX Operations:New Settings save and cache purge work without page reloads; maintains current UI state.
- Modular CSS: Component-scoped styles with CSS custom properties for theming.
- Responsive Design: Mobile-first approach with breakpoints for tablet and desktop.
Safety, UX & Performance Summary
- Spam & abuse: Contact form defenses (honeypot, CSRF, timing); admin-only actions require session; comments moderated before publishing.
- Sanitization: Captions allow only safe HTML; outgoing links get
rel="noopener noreferrer nofollow" for safety.
- Performance: Page caching for anonymous users; on-demand WebP thumbnails; album/photo views cached in DB counters; client-side table sorting/filtering in admin.
- Accessibility & UX: Responsive layout with blurred header, hamburger navigation on mobile, consistent iconography (Font Awesome), accent-color theming, toast notifications.
Photo7 Platform • Last updated: January 2026 • Recent: Fixed 16x visitor count inflation, theme switching, image optimization, Google Ads
GitHub