# Development README

This document is a developer-focused map of the repository, with emphasis on the custom `AudiencePlayer` plugin.

## 1) Repository shape

This is a full WordPress project, not just a plugin package.

- WordPress root: `src/`
- Custom plugin (main development target): `src/wp-content/plugins/audienceplayer/`
- Custom theme also present: `src/wp-content/themes/fitathome/`
- Many third-party plugins are checked into the repo (WooCommerce ecosystem, Stripe, Mailchimp, etc.)

Top-level project files used for local tooling:

- `package.json`
- `gulpfile.js`
- `gulp/`
- `build/`

## 2) AudiencePlayer plugin map

Main plugin path:

- `src/wp-content/plugins/audienceplayer/`

Key files:

- Plugin entrypoint: `src/wp-content/plugins/audienceplayer/audienceplayer.php`
- Main class: `src/wp-content/plugins/audienceplayer/src/AudiencePlayer/AudiencePlayerWordpressPlugin/AudiencePlayerWordpressPlugin.php`
- Constants/config: `src/wp-content/plugins/audienceplayer/src/AudiencePlayer/AudiencePlayerWordpressPlugin/Config/Constants.php`
- Internal autoloader: `src/wp-content/plugins/audienceplayer/src/AudiencePlayer/AudiencePlayerWordpressPlugin/AutoLoader.php`

Main module organization:

- Core logic traits:
  - `Resources/BootstrapTrait.php`
  - `Resources/UserSyncTrait.php`
  - `Resources/AdminSetupTrait.php`
  - `Resources/ShortCodeTrait.php`
  - `Resources/IntegrationWooCommerceTrait.php`
  - `Resources/AjaxTrait.php`
  - `Resources/Helper.php`
- Frontend rendering:
  - `templates/` (PHP template fragments for shortcode output + core HTML/JS includes)
  - `static/` (admin assets, embed-player assets, docs/help HTML)
- Build/deploy:
  - `gulpfile.js`
  - `gulp/build.js`
  - `gulp/deploy.js`
  - `gulp/conf.js`

## 3) Runtime architecture (how the plugin boots)

High-level startup sequence:

1. WordPress loads `audienceplayer.php`.
2. Admin Page Framework is loaded from `admin-page-framework/`.
3. Composer autoload is loaded from `vendor/autoload.php` (if present).
4. Plugin autoloader is loaded (`AutoLoader.php`).
5. `AudiencePlayerWordpressPlugin::init()` creates singleton + API client setup + project config + default translations.
6. `registerWordpressActions()` wires all hooks/actions/shortcodes.

The plugin follows a “single core class + traits” composition pattern.

## 4) Key behavior entry points

### Hook registration

Most WordPress integration hooks are centralized in:

- `src/wp-content/plugins/audienceplayer/src/AudiencePlayer/AudiencePlayerWordpressPlugin/Resources/BootstrapTrait.php`

This includes:

- activation/setup hooks
- admin assets/hooks
- AJAX endpoints (auth + no-auth variants)
- auth/registration/profile/password synchronization flow
- template/url rewrite integration points

### Shortcodes

Shortcodes are registered in:

- `src/wp-content/plugins/audienceplayer/src/AudiencePlayer/AudiencePlayerWordpressPlugin/Resources/ShortCodeTrait.php`

Main shortcodes:

- `audienceplayer_article_carousel`
- `audienceplayer_article_grid`
- `audienceplayer_play_article_button`
- `audienceplayer_embed_article`
- `audienceplayer_article_detail`
- `audienceplayer_purchase_product_button`
- `audienceplayer_purchase_subscription_button`
- `audienceplayer_purchase_subscriptions`
- `audienceplayer_user_account`
- `audienceplayer_device_pairing`

### WooCommerce integration

Woo/subscription hooks are wired in:

- `src/wp-content/plugins/audienceplayer/src/AudiencePlayer/AudiencePlayerWordpressPlugin/Resources/IntegrationWooCommerceTrait.php`

## 5) Build, test, deploy

Run these from plugin directory unless noted:

- Plugin path: `src/wp-content/plugins/audienceplayer/`

### JavaScript/build scripts

- Build plugin dist: `npm run build`
- Update embed-player dependency artifacts: `npm run update:deps`
- Deploy to AP target envs: `npm run deploy:<target>` (example: `deploy:prod`)
- Deploy to WordPress upstream/SVN working copy: `npm run deploy-wordpress:prod`

Build pipeline details:

- `build-dist` copies source, rewrites version fields in `readme.txt`, `audienceplayer.php`, `Constants.php`, and POT files.
- Composer dependencies are built in dist as part of gulp pipeline.
- Zip package is created in `build/`.

### PHP/static analysis

- Composer config: `src/wp-content/plugins/audienceplayer/composer.json`
- Test script: `composer run-script test` (runs PHPStan **and** PHPUnit in sequence)
- PHPStan config: `src/wp-content/plugins/audienceplayer/phpstan.neon`

### Unit tests

- Config: `src/wp-content/plugins/audienceplayer/phpunit.xml`
- Bootstrap: `src/wp-content/plugins/audienceplayer/tests/bootstrap.php`
- Test files: `src/wp-content/plugins/audienceplayer/tests/unit/`

Current coverage:

| Test file | Class under test | Notes |
|---|---|---|
| `tests/unit/AutoLoaderTest.php` | `AutoLoader` | Namespace resolution, spl_autoload wiring |
| `tests/unit/Resources/DebugTraitTest.php` | `DebugTrait` | Stack push / fetch / clear |
| `tests/unit/Resources/HelperTest.php` | `Helper` | String, array, validation, formatting helpers |

Run only unit tests:

```
$ composer run-script test:phpunit
```

The bootstrap stubs the minimal WordPress functions required by `Helper` (`add_query_arg`, `home_url`, `admin_url`, `wp_get_referer`, `wp_doing_ajax`, `wp_unslash`, `get_locale`). No WordPress installation is needed to run the suite.

### CI

- GitHub Actions workflow: `src/wp-content/plugins/audienceplayer/.github/workflows/php.yml`
- Runs on `master` pushes/PRs.
- Validates composer + installs deps + runs `composer run-script test` (PHPStan + PHPUnit).
- PHP version: `7.3`. Required extensions: `ext-curl`, `ext-intl`, `ext-json`.

## 6) Practical “where to edit for X”

- Add or change shortcode behavior:
  - `Resources/ShortCodeTrait.php`
  - corresponding `templates/audienceplayer-shortcode-*.php`
- Change plugin settings/admin panels:
  - `Resources/AdminSetupTrait.php`
  - `static/html/admin_*.html`
- Change API call handling:
  - `Resources/AjaxTrait.php`
  - helper methods in `Resources/Helper.php`
- Change auth/user sync behavior:
  - `Resources/UserSyncTrait.php`
  - hook wiring in `Resources/BootstrapTrait.php`
- Change Woo entitlement/order handling:
  - `Resources/IntegrationWooCommerceTrait.php`
- Change frontend/global scripts/styles:
  - `templates/js/`, `templates/css/`
  - `static/audienceplayer-embed-player/`

## 7) Current engineering impression

Strengths:

- Clear plugin boundary within a larger WordPress project.
- Feature coverage is broad (auth sync, shortcode rendering, WooCommerce integration, admin tooling).
- Build/deploy pipeline is explicit and operational.
- Static analysis (PHPStan) + unit tests (PHPUnit) both run in CI.
- Unit test bootstrap stubs WordPress functions, so the suite runs standalone without a WP install.

Risks / maintenance costs:

- Core behavior is concentrated in very large trait files (`BootstrapTrait`, `UserSyncTrait`).
- Legacy artifacts are checked in under plugin path (`node_modules`, `.svn`, `build/dist`, nested `.git`), which increases repo noise and onboarding friction.
- Hook-heavy logic makes regressions likely without targeted integration tests; current unit test coverage is limited to pure-logic helpers.

## 8) Suggested working conventions for this repo

- Treat `src/wp-content/plugins/audienceplayer/` as the authoritative custom plugin source.
- Avoid editing generated output in `build/dist/` directly.
- Prefer edits in trait + template source files, then rebuild.
- When touching auth/sync/woocommerce flows, test both logged-in and logged-out paths.
- Run the full test suite (`composer run-script test`) before merge for any PHP changes — this covers both PHPStan and PHPUnit in one step.