presto-player
Last commit date
dist
3 months ago
img
9 months ago
inc
3 months ago
languages
3 months ago
src
4 months ago
templates
6 months ago
vendor
3 months ago
CLAUDE.md
4 months ago
LICENSE
5 years ago
index.php
4 years ago
package.json
9 months ago
presto-player.php
3 months ago
readme.txt
3 months ago
CLAUDE.md
280 lines
| 1 | # CLAUDE.md |
| 2 | |
| 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | |
| 5 | ## Project Overview |
| 6 | |
| 7 | Presto Player is a WordPress video player plugin (v4.1.0) that provides video capabilities for WordPress websites with support for multiple sources (YouTube, Vimeo, self-hosted HTML5, HLS streams, Bunny.net). It features a modern architecture combining PHP backend with React frontend, built specifically for WordPress Block Editor (Gutenberg) with extensive LMS and page builder integrations. |
| 8 | |
| 9 | **Requirements:** PHP 7.3+, WordPress 5.6+ |
| 10 | |
| 11 | ## Development Commands |
| 12 | |
| 13 | ### Initial Setup |
| 14 | ```bash |
| 15 | # Install dependencies |
| 16 | yarn && composer install |
| 17 | |
| 18 | # Bootstrap workspace packages (first-time setup) |
| 19 | yarn bootstrap |
| 20 | |
| 21 | # Start development mode (includes composer install + watch) |
| 22 | yarn dev |
| 23 | ``` |
| 24 | |
| 25 | ### Build Commands |
| 26 | ```bash |
| 27 | # Development build and watch |
| 28 | yarn start # Watch mode with wp-scripts |
| 29 | yarn start:workspace # Watch all workspace packages |
| 30 | |
| 31 | # Production build |
| 32 | yarn build # Build main plugin |
| 33 | yarn build:workspace # Build all workspace packages |
| 34 | |
| 35 | # Release build (full production) |
| 36 | yarn plugin:release # Complete release: deps, i18n, build, zip |
| 37 | ``` |
| 38 | |
| 39 | ### Testing |
| 40 | |
| 41 | **PHP Tests** (requires wp-env running): |
| 42 | ```bash |
| 43 | yarn test:php # Run all PHPUnit tests |
| 44 | yarn test:php:failing # Run only tests marked @group failing |
| 45 | composer test # Direct PHPUnit run (alternative) |
| 46 | ``` |
| 47 | |
| 48 | **JavaScript Tests**: |
| 49 | ```bash |
| 50 | yarn test:unit # Jest unit tests |
| 51 | ``` |
| 52 | |
| 53 | **E2E Tests** (requires wp-env running): |
| 54 | ```bash |
| 55 | yarn test:e2e # WordPress E2E scripts |
| 56 | yarn test:e2e:playwright # Playwright tests |
| 57 | yarn test:e2e:playwright:ui # Playwright UI mode |
| 58 | yarn test:e2e:playwright:debug # Playwright debug mode |
| 59 | yarn test:e2e:playwright:trace # Playwright with tracing |
| 60 | ``` |
| 61 | |
| 62 | ### WordPress Environment |
| 63 | ```bash |
| 64 | # Start/stop local WordPress environment (wp-env) |
| 65 | wp-env start # Start WordPress at :3333 (tests at :4333) |
| 66 | wp-env stop # Stop environment |
| 67 | ``` |
| 68 | |
| 69 | ### Linting & Formatting |
| 70 | ```bash |
| 71 | yarn lint:js # ESLint |
| 72 | yarn lint:css # Stylelint |
| 73 | yarn format # Prettier format |
| 74 | |
| 75 | composer lint # PHPCS (PHP_CodeSniffer) |
| 76 | composer format # PHPCBF (PHP auto-fix) |
| 77 | ``` |
| 78 | |
| 79 | ### Translation |
| 80 | ```bash |
| 81 | yarn makepot # Generate .pot file from src/, inc/, templates/ |
| 82 | ``` |
| 83 | |
| 84 | ## Architecture Overview |
| 85 | |
| 86 | ### PHP Backend Architecture |
| 87 | |
| 88 | **Entry Point:** `presto-player.php` → `Factory` → `Controller` → Component registration |
| 89 | |
| 90 | **Dependency Injection Container:** |
| 91 | - Uses **DICE** DI container for loose coupling |
| 92 | - Configured via `inc/Factory.php` and `inc/config/app.php` |
| 93 | - Components implement `Service` interface with `register()` method |
| 94 | - Singleton services (Settings, BunnyCDN, Scripts) marked as `'shared' => true` |
| 95 | |
| 96 | **Key Architectural Layers:** |
| 97 | ``` |
| 98 | presto-player.php (entry) |
| 99 | ↓ |
| 100 | Factory::getRules() - DI configuration |
| 101 | ↓ |
| 102 | Controller::run() - Registers all components |
| 103 | ↓ |
| 104 | Components (each calls register() method): |
| 105 | - Blocks (10 block types) |
| 106 | - Services (23+ services including Scripts, Settings, Menu, Shortcodes) |
| 107 | - Integrations (11 integrations: LearnDash, Elementor, Divi, etc.) |
| 108 | - Database (migrations, models) |
| 109 | - API (REST controllers) |
| 110 | ``` |
| 111 | |
| 112 | **Component Discovery:** |
| 113 | - All components listed in `inc/config/app.php` under `components` array |
| 114 | - Pro components added via `presto_player_pro_components` filter |
| 115 | - Factory creates instances with dependencies via DICE container |
| 116 | - Controller loops through components and calls `register()` |
| 117 | |
| 118 | **Namespace:** `PrestoPlayer\` (PSR-4 autoloaded to `inc/`) |
| 119 | |
| 120 | **Database:** |
| 121 | - Custom tables managed in `inc/Database/` |
| 122 | - Tables: videos, presets, audio_presets, email_collection, visits, webhooks |
| 123 | - Models in `inc/Models/` provide ORM-like interface |
| 124 | - Migrations handled via `inc/Services/Migrations.php` |
| 125 | |
| 126 | ### Frontend (JavaScript/React) |
| 127 | |
| 128 | **Build System:** |
| 129 | - Yarn 3.3.0 workspaces (monorepo) |
| 130 | - WordPress Scripts (Webpack, Babel) |
| 131 | - Emotion CSS-in-JS for styling |
| 132 | - React 17.0.2 |
| 133 | |
| 134 | **Directory Structure:** |
| 135 | ``` |
| 136 | src/ |
| 137 | ├── admin/ # WordPress admin React interfaces |
| 138 | ├── player/ # Player components |
| 139 | ├── router/ # Page routing |
| 140 | ├── hooks/ # React hooks |
| 141 | ├── shared/ # Shared utilities |
| 142 | ├── elementor/ # Elementor integration UI |
| 143 | └── libraries/ # Custom libraries |
| 144 | |
| 145 | dist/ # Compiled assets (auto-generated) |
| 146 | ``` |
| 147 | |
| 148 | **Key Patterns:** |
| 149 | - Block-first design (Gutenberg blocks in `inc/Blocks/`) |
| 150 | - REST API for admin interfaces (`inc/Services/API/`) |
| 151 | - Dynamic loading for performance (scripts loaded conditionally) |
| 152 | |
| 153 | ### Block Development |
| 154 | |
| 155 | **Block Registration:** |
| 156 | 1. Create block class in `inc/Blocks/` extending base block class |
| 157 | 2. Add to `inc/config/app.php` components array |
| 158 | 3. Implement `register()` method to register with WordPress |
| 159 | 4. Block attributes defined in block class |
| 160 | 5. React component in `src/` for editor interface |
| 161 | |
| 162 | **Block Types:** |
| 163 | - Video blocks: SelfHostedBlock, YouTubeBlock, VimeoBlock |
| 164 | - Reusable: ReusableVideoBlock, MediaHubBlock |
| 165 | - Audio: AudioBlock |
| 166 | - Popup: PopupBlock, PopupTriggerBlock, PopupMediaBlock |
| 167 | |
| 168 | ### Integrations |
| 169 | |
| 170 | **LMS Integrations** (`inc/Integrations/`): |
| 171 | - LearnDash (video progression) |
| 172 | - TutorLMS |
| 173 | - LifterLMS |
| 174 | |
| 175 | **Page Builders:** |
| 176 | - Elementor (custom widgets) |
| 177 | - Beaver Builder (custom modules) |
| 178 | - Divi (custom modules) |
| 179 | - Kadence |
| 180 | |
| 181 | Each integration is a component that registers when its parent plugin is active. |
| 182 | |
| 183 | ## Code Patterns & Conventions |
| 184 | |
| 185 | ### PHP Patterns |
| 186 | - **PSR-4 Autoloading**: All classes under `PrestoPlayer\` namespace |
| 187 | - **Service Pattern**: Components implement `Service` interface |
| 188 | - **Singleton Pattern**: Core instance via `Core::set_instance()` |
| 189 | - **Factory Pattern**: DI container configuration in Factory class |
| 190 | - **Hook System**: WordPress hooks (`add_action`, `add_filter`) |
| 191 | |
| 192 | ### JavaScript Patterns |
| 193 | - **React Components**: Functional components with hooks |
| 194 | - **CSS-in-JS**: Emotion for styling |
| 195 | - **WordPress Data**: `@wordpress/data` for state management |
| 196 | - **i18n**: WordPress i18n functions for translations |
| 197 | |
| 198 | ### Namespacing |
| 199 | - PHP classes are namespaced: `PrestoPlayer\Services\Settings` |
| 200 | - Imposter plugin isolates vendor dependencies under `PrestoPlayer\` namespace |
| 201 | |
| 202 | ## Testing Strategy |
| 203 | |
| 204 | **Test Locations:** |
| 205 | - PHP Unit: `tests/unit/` |
| 206 | - PHP Feature: `tests/feature/` |
| 207 | - JS Unit: `src/**/test/*.spec.js` |
| 208 | - E2E: `tests-e2e/**/*.spec.{js,ts}` |
| 209 | |
| 210 | **Testing Environment:** |
| 211 | - PHP tests run in wp-env WordPress CLI environment |
| 212 | - Requires WordPress test suite |
| 213 | - E2E tests require wp-env running (ports 3333/4333) |
| 214 | |
| 215 | **Test Configuration:** |
| 216 | - PHPUnit: `phpunit.xml.dist` |
| 217 | - Jest: `jest.config.unit.js` |
| 218 | - E2E (Jest): `jest.config.e2e.js` |
| 219 | - Playwright: `playwright.config.js` (if exists) |
| 220 | |
| 221 | ## Key Files Reference |
| 222 | |
| 223 | | Path | Purpose | |
| 224 | |------|---------| |
| 225 | | `presto-player.php` | Main plugin file (entry point) | |
| 226 | | `inc/Controller.php` | Component registration controller | |
| 227 | | `inc/Factory.php` | DI container factory and rules | |
| 228 | | `inc/config/app.php` | Component configuration array | |
| 229 | | `inc/Core.php` | Singleton core instance holder | |
| 230 | | `inc/Services/Scripts.php` | Script/style enqueueing | |
| 231 | | `inc/Services/Settings.php` | Global settings management | |
| 232 | | `inc/Services/Shortcodes.php` | Shortcode implementation | |
| 233 | | `inc/Models/` | Database models | |
| 234 | | `inc/Database/` | Table schemas and migrations | |
| 235 | | `package.json` | Root workspace config | |
| 236 | | `@presto-player/presto-player/package.json` | Workspace package config | |
| 237 | | `composer.json` | PHP dependencies and autoload | |
| 238 | |
| 239 | ## Important Notes |
| 240 | |
| 241 | ### WordPress Environment (.wp-env.json) |
| 242 | - Development: `http://localhost:3333` |
| 243 | - Test environment: `http://localhost:4333` |
| 244 | - Loads both presto-player (free) and presto-player-pro plugins |
| 245 | |
| 246 | ### Vendor Dependencies |
| 247 | - **DICE**: Dependency injection container |
| 248 | - **Imposter**: Namespace isolation for dependencies (critical for avoiding conflicts) |
| 249 | - Always run `composer install` after pulling changes |
| 250 | |
| 251 | ### Translation Workflow |
| 252 | - Strings use WordPress i18n: `__()`, `_e()`, `esc_html__()` etc. |
| 253 | - Text domain: `presto-player` |
| 254 | - POT file: `languages/presto-player.pot` |
| 255 | - Generated from `src/`, `inc/`, and `templates/` |
| 256 | |
| 257 | ### Pro Version Integration |
| 258 | - Pro plugin adds components via `presto_player_pro_components` filter |
| 259 | - Pro check: `Plugin::isPro()` method |
| 260 | - Settings constructor accepts `$isPro` parameter |
| 261 | - Pro features conditionally registered based on pro plugin activation |
| 262 | |
| 263 | ### Workspace Structure |
| 264 | - Yarn workspaces used (Yarn 3+) |
| 265 | - Workspace packages in `@presto-player/presto-player/packages/*` |
| 266 | - Bootstrap command builds workspace dependencies |
| 267 | - Workspace commands run across all packages |
| 268 | |
| 269 | ### Release Process |
| 270 | ```bash |
| 271 | yarn plugin:release |
| 272 | ``` |
| 273 | This command: |
| 274 | 1. Installs all dependencies |
| 275 | 2. Generates translation files |
| 276 | 3. Reinstalls composer without dev dependencies |
| 277 | 4. Builds all workspace packages |
| 278 | 5. Creates plugin zip |
| 279 | 6. Extracts zip for distribution |
| 280 |