fourth-wall-embed-wp/CLAUDE.md

CLAUDE.md

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

Overview

This is a WordPress plugin that embeds Fourthwall store products into WordPress sites via shortcodes. The plugin fetches product data from Fourthwall stores using cURL, parses HTML to extract product information, and displays them with custom CSS styling.

Core Architecture

File Structure

• fw-store-embed.php - Main plugin entry point that loads libraries and registers CSS
• libs/settings.php - Admin settings page, cache management, and WordPress options API integration
• libs/shortcode.php - Core functionality for fetching, parsing, and displaying products
• libs/self-update.php - Auto-update system that checks Gitea releases API
• css/fw-store-embed.css - Styling for product tiles and admin interface

Key Components

HTTP Request Layer (fwembed_make_request in shortcode.php):

• Centralized cURL-based HTTP client with browser-like headers to avoid 403 blocks
• 1-hour transient caching using WordPress transients (cache key: fwembed_{md5(url)})
• SSL verification configurable via admin settings
• Cookie handling via /tmp/cookies.txt for session persistence

HTML Parsing (shortcode.php):

• Uses DOMDocument/DOMXPath to extract product data from Fourthwall HTML
• Looks for div[data-testid="product"] elements
• Extracts product tiles, images, descriptions, titles, and prices via CSS class selectors
• loadHTML5() wrapper ensures proper HTML5 parsing

Shortcodes:

• [fourthwall] - Displays all store products
• [fourthwall_single url="..." show_description="true"] - Single product display
• [fourthwall_random count="5" urls="..." store_url="..."] - Random product selection

Auto-Update System (self-update.php):

• Hooks into WordPress plugin update transients (site_transient_update_plugins)
• Fetches latest release from https://repo.anhonesthost.net/api/v1/repos/wp-plugins/fourth-wall-embed-wp/releases/latest
• Provides changelog via plugins_api filter
• Version placeholder {auto_update_value_on_deploy} is replaced during CI/CD build

Settings Storage

WordPress options API key: fourthwall_settings_name

• fourth_url - Default Fourthwall store URL
• ssl_verify - Boolean for SSL certificate verification

Development Commands

Testing the Plugin Locally

1. Symlink or copy to WordPress plugins directory:

   ln -s $(pwd) /path/to/wordpress/wp-content/plugins/fourth-wall-embed-wp
   

2. Activate in WordPress admin at: Plugins > Installed Plugins

3. Configure at: Settings > Fourthwall Store Embed

Cache Management

Clear transient cache from admin UI or manually:

DELETE FROM wp_options WHERE option_name LIKE '_transient_fwembed_%';
DELETE FROM wp_options WHERE option_name LIKE '_transient_timeout_fwembed_%';

CI/CD Pipeline

Gitea Actions Workflows

.gitea/workflows/release.yml - Runs on push to main:

1. Generates version tag from date/time: YYYY.MM.DD-HHMM
2. Creates release notes from commits since last tag
3. Updates version placeholder in fw-store-embed.php
4. Creates ZIP archive with plugin folder structure: fourthwall-store-embed/
5. Creates GitHub-style release with ZIP attachment

.gitea/workflows/update-version.yml - Version update automation

Release Process

Releases are automatic on merge/push to main. The ZIP file structure must match WordPress conventions:

fourthwall-store-embed.zip
└── fourthwall-store-embed/
    ├── fw-store-embed.php
    ├── libs/
    ├── css/
    └── README.md

Important Implementation Notes

DOMDocument HTML Parsing

• Always use libxml_use_internal_errors(true) to suppress HTML5 parsing warnings
• Clear errors with libxml_clear_errors() after parsing
• Set $dom->documentURI for proper relative URL resolution

Caching Strategy

• All HTTP requests are cached for 1 hour (3600 seconds)
• Cache is stored in WordPress transients, not direct database access
• Error responses (non-200 status) are NOT cached
• Cache keys use md5($url) to handle special characters

Security Considerations

• All user input sanitized via esc_attr(), esc_html(), htmlspecialchars()
• Nonce verification for cache clearing: wp_verify_nonce()
• Capability checks: current_user_can('manage_options')
• SSL verification enabled by default (disable only for local dev)

Version Management

• Main plugin file contains placeholder: Version: {auto_update_value_on_deploy}
• CI/CD replaces this during build with actual version
• Update checker compares version strings exactly (not semantic versioning)

WordPress Compatibility

• Requires: WordPress 6.0+, PHP 7.4+
• Tested up to: WordPress 6.8
• Required PHP extensions: cURL, libxml, DOM