monorepo/native/wordpress/README.md

# 🔌 WordPress Native Applications

This directory contains native WordPress applications (plugins and themes) for the Maple Open Technologies ecosystem.

## 🗂️ Directory Structure

```
native/wordpress/
└── maplepress-plugin/    # MaplePress cloud services plugin
```

## 🚀 MaplePress Plugin

The MaplePress plugin connects your WordPress site to the MaplePress cloud platform, providing cloud-powered services that offload computationally intensive tasks to remote infrastructure. Currently features advanced search capabilities, with more services coming soon (uploads, metrics, analytics, etc.).

### Features

- **Cloud-powered search** - Offsite search processing with advanced indexing
- **Automatic content indexing** - Your content is automatically synced
- **Real-time synchronization** - Changes are reflected immediately
- **API key authentication** - Secure connection to MaplePress backend
- **WordPress admin settings** - Easy configuration and monitoring
- **Extensible platform** - Ready for additional cloud services as they become available

### Development Workflow

#### Local Development with Docker

The plugin is automatically mounted into the local WordPress container for development:

```bash
# Start infrastructure (from cloud/infrastructure/development)
cd ../../cloud/infrastructure/development
task dev:start

# WordPress will be available at http://localhost:8081
# Plugin is auto-mounted at /wp-content/plugins/maplepress-plugin
```

#### First Time Setup

Configure the plugin for local development:

```bash
cd maplepress-plugin

# Set up local development environment
task dev:setup

# This will:
# 1. Create wp-config.local.php with API URL = http://localhost:8000
# 2. Inject loader into WordPress wp-config.php
# 3. Pre-configure API URL for local development

# Now activate the plugin in WordPress:
# - Go to http://localhost:8081/wp-admin/plugins.php
# - Activate "MaplePress" plugin
# - Go to Settings → MaplePress
# - API URL will be pre-filled with http://localhost:8000
# - Enter your API key and save
```

**Why this approach?**
- Production plugin distributed via WordPress.org has **empty API URL** (users must configure)
- Local development needs **http://localhost:8000** pre-configured for convenience
- Can't use `.env` files (not part of plugin distribution)
- Solution: Local-only config file (`wp-config.local.php`) that is git-ignored and excluded from builds

#### Plugin Development Commands

```bash
cd maplepress-plugin

# Set up local development (first time)
task dev:setup

# Reset to production configuration (removes local dev settings)
task dev:reset

# Sync plugin to WordPress container (manual sync)
task sync

# Watch for changes and auto-sync
task watch

# View WordPress debug logs
task logs

# Open shell in WordPress container
task shell

# Run PHP CodeSniffer
task lint

# Auto-fix coding standards issues
task lint:fix

# Run tests
task test

# Build distribution ZIP
task build

# Clean build artifacts
task clean

# Install Composer dependencies
task install
```

### Initial Setup

1. **Start WordPress:**
   ```bash
   cd cloud/infrastructure/development
   task dev:start
   ```

2. **Complete WordPress Installation:**
   - Visit http://localhost:8081
   - Complete the WordPress setup wizard
   - Create admin account

3. **Activate Plugin:**
   - Go to Plugins → Installed Plugins
   - Activate "MaplePress"

4. **Configure Plugin:**
   - Go to Settings → MaplePress
   - Enter API URL: `http://maplepress-backend:8000` (or your backend URL)
   - Enter your API key from the MaplePress dashboard
   - Enable MaplePress and save settings

### Plugin Structure

```
maplepress-plugin/
├── maplepress-plugin.php         # Main plugin file
├── readme.txt                    # WordPress.org readme
├── composer.json                 # PHP dependencies
├── Taskfile.yml                  # Development tasks
├── includes/                     # Core plugin logic
│   ├── class-maplepress.php           # Main plugin class
│   ├── class-maplepress-loader.php    # Hook loader
│   ├── class-maplepress-activator.php # Activation logic
│   ├── class-maplepress-deactivator.php # Deactivation logic
│   ├── class-maplepress-admin.php     # Admin functionality
│   ├── class-maplepress-public.php    # Public functionality
│   ├── class-maplepress-api-client.php # API client
│   └── admin-settings-display.php     # Settings page template
├── assets/                       # Frontend assets
│   ├── css/
│   │   ├── maplepress-admin.css
│   │   └── maplepress-public.css
│   └── js/
│       ├── maplepress-admin.js
│       └── maplepress-public.js
├── languages/                    # Translation files
└── tests/                        # PHPUnit tests
```

### Publishing to WordPress.org

1. **Prepare for Release:**
   ```bash
   # Update version in:
   # - maplepress-plugin.php (header and constant)
   # - readme.txt (Stable tag)

   # Build distribution package
   task build
   ```

2. **Create Release:**
   - Distribution ZIP will be in `dist/maplepress-plugin.zip`
   - Test the ZIP in a fresh WordPress installation

3. **Submit to WordPress.org:**
   - Create account at https://wordpress.org/plugins/developers/
   - Submit plugin for review
   - Follow WordPress plugin guidelines

### API Integration

The plugin communicates with the MaplePress backend using the API client:

```php
// Example: Verify API connection
$api_client = new MaplePress_API_Client( $api_url, $api_key );
$status = $api_client->verify_connection();

// Example: Index a post
$api_client->index_post( $post_id );

// Example: Search
$results = $api_client->search( 'search query' );
```

### WordPress Coding Standards

The plugin follows WordPress Coding Standards:

```bash
# Check coding standards
task lint

# Auto-fix issues
task lint:fix
```

### Testing

```bash
# Run PHPUnit tests
task test

# Test in local WordPress
# 1. Make changes to plugin code
# 2. Refresh WordPress admin to see changes
# 3. Check debug logs: task logs
```

### Debugging

WordPress debug mode is enabled in the development environment:

```bash
# View debug logs
task logs

# Or directly:
docker exec -it mapleopentech-wordpress-dev tail -f /var/www/html/wp-content/debug.log
```

### Environment Variables

The plugin uses WordPress options for configuration:

- `maplepress_settings['api_url']` - MaplePress backend URL
- `maplepress_settings['api_key']` - Site API key
- `maplepress_settings['site_id']` - Site ID (auto-populated)
- `maplepress_settings['enabled']` - Enable/disable plugin

### Docker Volume Mount

The plugin is mounted as a read-only volume in docker-compose.dev.yml:

```yaml
volumes:
  - ../../native/wordpress/maplepress-plugin:/var/www/html/wp-content/plugins/maplepress-plugin:ro
```

This allows live editing without rebuilding the container.

## ➕ Adding New WordPress Plugins

To add additional WordPress plugins to the monorepo:

1. Create new directory: `native/wordpress/new-plugin-name/`
2. Follow WordPress plugin structure
3. Add Taskfile.yml for development workflow
4. Mount in docker-compose.dev.yml if needed for local development
5. Update this README

## 📚 Resources

- [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/)
- [Plugin API Reference](https://developer.wordpress.org/reference/)
- [WordPress.org Plugin Guidelines](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/)

## Contributing

Found a bug? Want a feature to improve the WordPress plugins? Please create an [issue](https://codeberg.org/mapleopentech/monorepo/issues/new).

## License

This application is licensed under the [**GNU Affero General Public License v3.0**](https://opensource.org/license/agpl-v3). See [LICENSE](../../LICENSE) for more information.