wp-digital-download/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

WordPress Digital Download Plugin

This is a comprehensive WordPress plugin for creating a digital download marketplace. The plugin allows creators to sell digital products with PayPal integration, secure file protection, and watermarking capabilities.

Development Commands

Testing

• Tests are configured for https://streamers.channel (live site)
• Use Browser MCP to test the site.
• Admin credentials are in the section: WordPress Admin Access

Architecture Overview

Plugin Structure

The plugin follows WordPress standards with a singleton main class WP_Digital_Download that orchestrates all components:

Main Plugin File: wp-digital-download.php

• Defines plugin constants and initializes the main class
• Handles dependency loading and hook initialization
• Manages script/style enqueuing with cache busting
• Integrates FontAwesome CDN for frontend icons (copy buttons, etc.)

Core Components

Product Management (includes/class-wpdd-post-types.php, includes/class-wpdd-metaboxes.php)

• Custom post type wpdd_product for digital products
• Rich metadata system for pricing, files, download limits
• Creator attribution and sales tracking
• Default download limit set to 0 (unlimited) for new products
• Proper handling of unlimited vs limited download configurations

Payment Processing (includes/class-wpdd-paypal.php)

• PayPal API integration (sandbox/live modes)
• Order processing and webhook handling
• Support for both paid and free products

File Security (includes/class-wpdd-file-protection.php, includes/class-wpdd-download-handler.php)

• Secure file storage outside web root
• Token-based download authentication
• Time-limited and usage-limited downloads
• Download tracking and logging
• Software license files stored locally in wp-content/uploads/wpdd-packages/
• Filename sanitization for downloads (spaces→dashes, dots→underscores, proper extensions)

User Management (includes/class-wpdd-roles.php, includes/class-wpdd-customer.php)

• Custom roles: Digital Customer, Digital Creator
• Customer purchase history and account management
• Guest checkout support

Frontend Display (includes/class-wpdd-shortcodes.php)

• Shortcodes: [wpdd_shop], [wpdd_checkout], [wpdd_customer_purchases], etc.
• Product grids, filtering, and pagination
• Responsive design support
• Enhanced license key display with FontAwesome copy icons
• Improved customer purchases table layout with full-width license key rows

Admin Interface (admin/class-wpdd-admin.php, admin/class-wpdd-settings.php)

• Admin dashboard for orders and sales management
• Plugin settings and PayPal configuration
• Product editing interface

Additional Features

• Watermarking (includes/class-wpdd-watermark.php): Dynamic image/PDF watermarks
• AJAX handlers (includes/class-wpdd-ajax.php): Frontend interactions
• Installation routines (includes/class-wpdd-install.php): Database setup and pages

Database Schema

• wp_wpdd_orders - Purchase records
• wp_wpdd_downloads - Download tracking
• wp_wpdd_download_links - Secure download tokens
• Product metadata stored in wp_postmeta

Key Shortcodes

• [wpdd_shop] - Main product storefront with filtering/sorting
• [wpdd_customer_purchases] - Customer purchase history (login required)
• [wpdd_checkout] - Payment processing form
• [wpdd_thank_you] - Order confirmation page
• [wpdd_product id="123"] - Single product display

Recent Improvements and Bug Fixes

Download Limits Fix (includes/class-wpdd-metaboxes.php)

• Issue: Products set to unlimited downloads were incorrectly showing limits instead of unlimited
• Fix: Changed default download limit from 5 to 0 (unlimited) in metabox configuration
• Impact: New products now default to unlimited downloads as intended

License Key Display Enhancement (includes/class-wpdd-shortcodes.php, assets/css/frontend.css)

• Improvement: Restructured customer purchases table for better license key presentation
• Changes:
  • Moved license keys from separate column to full-width spanning row
  • Added FontAwesome copy icon for easy license key copying
  • Implemented responsive CSS styling for license key display
• New CSS Classes: .wpdd-license-row, .wpdd-license-cell, .wpdd-license-key, .wpdd-copy-icon

Software License Download Filename Sanitization

• Files Modified: includes/class-wpdd-download-handler.php, includes/class-wpdd-api.php
• Issue: Software license downloads had improper filenames with spaces and special characters
• Solution: Implemented comprehensive filename sanitization:
  • Spaces converted to dashes
  • Dots converted to underscores (except file extension)
  • Proper .zip extension enforcement
  • Version extraction from package paths
• Example: "Test Plugin v2.2.0" becomes "Test-Plugin-v2-2-0.zip"
• Coverage: Both regular download handler and API download paths

Technical Architecture Discovery

• Software License Storage: Local storage in wp-content/uploads/wpdd-packages/ (not external API)
• Download Flow: Token → process_download_by_token() → process_download() → deliver_file()
• Dual Path Coverage: Sanitization applied to both standard downloads and API update downloads

Development Notes

File Loading Pattern

All classes are loaded conditionally with existence checks and error logging. Admin classes are only loaded in admin context.

Security Considerations

• CSRF protection via nonces on all forms
• Input sanitization and validation
• Capability checks for admin functions
• Secure file delivery system
• XSS prevention in user inputs

Frontend Assets

• Cache busting using file modification times
• Separate CSS/JS for admin and frontend
• jQuery dependencies for interactive features
• Localized AJAX endpoints with nonces
• FontAwesome CDN integration for UI icons

Filename Sanitization Patterns

For software license downloads, the plugin implements standardized filename sanitization:

// Pattern: Convert spaces to dashes, dots to underscores (except file extension)
$sanitized = str_replace([' ', '.'], ['-', '_'], $base_name) . '.zip';
// Example: "Test Plugin v2.2.0" → "Test-Plugin-v2-2-0.zip"

Applied in both class-wpdd-download-handler.php and class-wpdd-api.php for comprehensive coverage.

Remote Deployment

SFTP Access:

• Host: shadowdao@whp01.cloud-hosting.io
• Remote path: /streamers.channel/public_html/wp-content/plugins/wp-digital-download/
• Use SFTP commands like: sftp shadowdao@whp01.cloud-hosting.io

WordPress Admin Access:

• Site URL: https://streamers.channel
• Username: playwright
• Password: %Pzx*H1F(U79q6lQXsU)Ofxl

Important Patterns

Error Handling

Extensive error logging throughout with descriptive messages for missing classes/files.

If you find a bug or error, you should fix it in the code, deploy the changes, and test again. You should continue the process until the issue is fixed. Once you fix the issue, continue testing.

Hook System

Uses WordPress actions/filters:

• wpdd_order_completed - Post-purchase processing
• wpdd_download_started - Pre-download hooks
• wpdd_customer_registered - New customer events

Search Integration

Plugin automatically includes wpdd_product post type in WordPress search results via pre_get_posts filter.

Website Current Status

• The site is currently hooked up to PayPal Sandbox
• The website has some test products

PayPal Sandbox Configuration

Admin Credentials (for plugin settings):

• Mode: Sandbox
• Client ID: AW4tXomdLDd9tpZP6I3PsTDaDPTy5XYm1kwEu66uBUeRBFHtARweFrOAq_M9IXqYAYnBvC_YKK_n5tMI
• Secret Key: EOjAvXKP7wDiF_WLFRRx8Z7ccKM7ML7LpmRNSUVxzVL4wrJGq9sfDkHQAOkYEttEz0Wx_jnfPBtuFXiX

Test Customer Credentials (for making purchases):

• Email: sb-a7cpw45634739@personal.example.com
• Password: 3[I$ppb?

Payment Holding System

• Default holding period: 15 days (configurable to 0 for immediate)
• Status flow: pending → available → paid
• Automated cron job processes earnings hourly
• Admin Order Manager available for cancellations/refunds
• IMPORTANT: Use Use a persistent context when using Playwright or Save and reuse authentication state when doing testing