Installation

Install and activate the GSM Middleware plugin.

System Requirements

Server Requirements

• PHP: 8.2 or higher (tested up to 8.4)
• WordPress: 6.0 or higher
• MySQL: 5.7 or higher (8.0+ recommended)
• Web Server: Apache 2.4+ or Nginx 1.18+

PHP Extensions

Required:

• mysqli or pdo_mysql
• curl
• json
• mbstring
• openssl
• zip

Optional (recommended):

• opcache (for performance)
• igbinary (for caching)
• ssh2 (for BazaarVoice SFTP feed sync)

PHP Configuration

Recommended php.ini settings:

memory_limit = 512M
max_execution_time = 300
post_max_size = 20M
upload_max_filesize = 20M
max_input_vars = 5000

Composer

Required for dependency management:

• Composer 2.0 or higher
• Accessible via command line

Install Composer:

# Download
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

# Install
php composer-setup.php --install-dir=/usr/local/bin --filename=composer

# Verify
composer --version

Installation Methods

Method 1: Git Clone (Recommended for Development)

1. Navigate to plugins directory:

cd /path/to/wordpress/wp-content/plugins

2. Clone repository:

git clone https://github.com/your-org/gsm-middleware.git

3. Install dependencies:

cd gsm-middleware
composer install --no-dev

Development Dependencies

For development (testing, static analysis, coding standards), install with dev dependencies:

composer install

This installs additional tools:

• PHPUnit 11.5 — Test framework
• Yoast PHPUnit Polyfills 3.x — WordPress testing compatibility
• PHPStan — Static analysis (level 8)
• PHPCS — WordPress Coding Standards checks
• szepeviktor/phpstan-wordpress — WordPress type stubs for PHPStan

See Testing and CI/CD for usage details.

4. Set permissions:

chmod 755 gsm-middleware
chmod 644 gsm-middleware/*

5. Activate in WordPress:
   • Go to WordPress Admin → Plugins
   • Find "GSM Middleware"
   • Click "Activate"

Method 2: Upload ZIP (Recommended for Production)

1. Download release ZIP:

   • Download from releases page
   • File: gsm-middleware-v1.0.0.zip

2. Upload via WordPress:

   • Go to WordPress Admin → Plugins → Add New
   • Click "Upload Plugin"
   • Choose ZIP file
   • Click "Install Now"
   • Click "Activate Plugin"

3. Or upload via FTP:

   • Extract ZIP file locally
   • Upload gsm-middleware folder to /wp-content/plugins/
   • Go to WordPress Admin → Plugins
   • Activate "GSM Middleware"

Method 3: Composer (Recommended for Managed WordPress)

1. Add to composer.json:

{
  "require": {
    "your-org/gsm-middleware": "^1.0"
  },
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/your-org/gsm-middleware.git"
    }
  ]
}

2. Install:

composer install

3. Activate:

wp plugin activate gsm-middleware

Post-Installation

Verify Installation

1. Check plugin is active:

wp plugin list | grep gsm-middleware

Expected output:

gsm-middleware     active   1.0.0

2. Check admin menu:

   • Go to WordPress Admin
   • Look for "GSM Middleware" in sidebar
   • Should see dashboard icon (networking/nodes)

3. Check database tables:

wp db query "SHOW TABLES LIKE 'rm_%'"

Expected output (if using WordPress database):

rm_sites
rm_order
rm_address
rm_lineitems
rm_items
rm_kits
rm_error_orders
rm_order_import_errors
rm_db_environments
rm_api_connections

Initial Configuration

1. Go to Control Panel:

   • WordPress Admin → GSM Middleware

2. You'll see setup wizard (first time only):

   • Welcome screen
   • Database configuration
   • API connections
   • First site setup

3. Or manually configure:

   • Database Environment
   • API Connections
   • Global Settings

Troubleshooting Installation

Composer Errors

Error: "composer: command not found"

Solution:

# Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Error: "Your requirements could not be resolved"

Solution:

# Update Composer
composer self-update

# Clear cache
composer clear-cache

# Try again
composer install --no-dev

PHP Version Error

Error: "Plugin requires PHP 8.2 or higher"

Solution:

1. Check current PHP version:

php -v

2. Upgrade PHP (Ubuntu/Debian):

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install php8.2 php8.2-mysql php8.2-curl php8.2-mbstring

3. Update Apache/Nginx to use new PHP version

Permission Errors

Error: "Permission denied"

Solution:

# Fix permissions
sudo chown -R www-data:www-data /path/to/wordpress/wp-content/plugins/gsm-middleware
sudo chmod -R 755 /path/to/wordpress/wp-content/plugins/gsm-middleware

Missing PHP Extensions

Error: "Required extension 'curl' is not loaded"

Solution:

# Install missing extensions (Ubuntu/Debian)
sudo apt install php8.2-curl php8.2-mbstring php8.2-mysql

# Restart web server
sudo systemctl restart apache2
# or
sudo systemctl restart nginx php8.2-fpm

Database Connection Error

Error: "Could not connect to database"

Check:

1. MySQL is running:

sudo systemctl status mysql

2. WordPress can connect:

wp db check

3. Credentials in wp-config.php are correct

Plugin Activation Error

Error: "Plugin could not be activated"

Check:

1. PHP error log:

tail -f /var/log/php-fpm/error.log

2. WordPress debug log:

tail -f /var/log/wordpress/debug.log

3. Common causes:
   • Syntax errors (wrong PHP version)
   • Missing dependencies (run composer install)
   • Memory limit exceeded
   • File permission issues

Upgrading

From Previous Version

Backup first!

# Backup database
wp db export backup.sql

# Backup plugin files
cp -r /path/to/wp-content/plugins/gsm-middleware /backup/gsm-middleware-old

Upgrade:

Method 1: Git

cd /path/to/wp-content/plugins/gsm-middleware
git pull origin main
composer install --no-dev
wp plugin deactivate gsm-middleware
wp plugin activate gsm-middleware

Method 2: WordPress Admin

1. Go to WordPress Admin → Plugins
2. Check for updates
3. Click "Update Now" for GSM Middleware
4. Wait for completion

Method 3: Manual

1. Deactivate plugin
2. Delete old plugin folder
3. Upload new version
4. Activate plugin

Run database migrations (if any):

wp gsm-middleware db migrate

Version Compatibility

Plugin Version	WordPress	PHP	MySQL
1.0.x	6.0+	8.2+	5.7+
0.9.x	5.9+	8.1+	5.7+

Uninstalling

Automatic Uninstall (via WordPress)

Version Added: 1.18.25

The plugin includes an uninstall.php handler that runs automatically when you delete the plugin through WordPress admin or WP-CLI. It performs:

• Removes all plugin options and transients
• Removes custom capabilities from all roles
• Drops WordPress-side plugin tables (gsm_db_environments, gsm_api_connections)
• Clears remaining scheduled cron events

warning

The external Tasks DB tables (rm_*) are intentionally NOT dropped during uninstall — they require manual DBA management since they may be on a separate database server.

Clean Uninstall (including external DB)

⚠️ Warning: This will delete all plugin data!

1. Backup data:

wp db export gsm-middleware-backup.sql --tables=rm_*

2. Deactivate plugin:

wp plugin deactivate gsm-middleware

3. Delete plugin (triggers uninstall.php):

wp plugin delete gsm-middleware

4. Manually delete external database tables (if desired):

wp db query "DROP TABLE IF EXISTS rm_sites, rm_order, rm_address, rm_lineitems, rm_items, rm_kits, rm_error_orders, rm_order_import_errors, rm_queue, rm_webhook_log, rm_chargebacks, rm_api_keys, rm_report_configs, rm_item_reviews, rm_item_schema_markup, rm_carrier_mapping, rm_payarc_dispute_linkages, shipments, shipments_extra, shipments_line_item, rm_promotions;"

Keep Data Uninstall

To uninstall but keep data:

1. Deactivate plugin only
2. Don't delete tables
3. Can reactivate later

Next Steps

• Configuration - Configure the plugin
• First Site Setup - Add your first site
• Cron Setup - Set up scheduled tasks