monorepo/native/wordpress

🔌 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:

# 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:

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

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:

   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:

   # 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:

// 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:

# Check coding standards
task lint

# Auto-fix issues
task lint:fix

Testing

# 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:

# 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:

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
• WordPress Coding Standards
• Plugin API Reference
• WordPress.org Plugin Guidelines

Contributing

Found a bug? Want a feature to improve the WordPress plugins? Please create an issue.

License

This application is licensed under the GNU Affero General Public License v3.0. See LICENSE for more information.