Skip to main content

Development Setup

Complete guide to setting up a local development environment for the Muddy WordPress + BigCommerce site.

Prerequisites​

Required Software​

SoftwareVersionPurpose
PHP8.1+Server-side language
MySQL/MariaDB5.7+ / 10.3+Database
Node.js20.x LTSBuild tooling
npm10.x+Package management
Composer2.xPHP dependency management
GitLatestVersion control
  • Local Development Environment: Laravel Herd, Local by Flywheel, XAMPP, or MAMP
  • Code Editor: Visual Studio Code with PHP extensions
  • Database Client: TablePlus, Sequel Pro, or phpMyAdmin
  • API Testing: Postman or Insomnia
  • Terminal: PowerShell (Windows), Terminal/iTerm2 (macOS), or integrated terminal in VS Code

Local Environment Setup​

Laravel Herd provides a zero-configuration local PHP development environment.

Installation:

  1. Download from https://herd.laravel.com
  2. Install and launch Herd
  3. Configure PHP version to 8.1+
  4. Set document root directory

Create Site:

# Link site directory
herd link muddy-local

# Open in browser: http://muddy-local.test

Option 2: Local by Flywheel​

Installation:

  1. Download from https://localwp.com

  2. Create new site:

    • Site Name: muddy-local
    • PHP Version: 8.1+
    • Web Server: nginx
    • Database: MySQL 5.7+

  3. Start site and note credentials

Option 3: Docker (Advanced)​

# docker-compose.yml
version: '3.8'

services:
  wordpress:
    image: wordpress:6.6-php8.1-apache
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: muddy
      WORDPRESS_DB_PASSWORD: muddy_local
      WORDPRESS_DB_NAME: muddy_local
    volumes:
      - ./wp-content:/var/www/html/wp-content
      - ./uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
    depends_on:
      - db

  db:
    image: mysql:5.7
    environment:
      MYSQL_DATABASE: muddy_local
      MYSQL_USER: muddy
      MYSQL_PASSWORD: muddy_local
      MYSQL_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - db_data:/var/lib/mysql

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db
      PMA_USER: muddy
      PMA_PASSWORD: muddy_local
    depends_on:
      - db

volumes:
  db_data:

Start environment:

docker-compose up -d

Database Setup​

Import Production Database​

Export from production:

# SSH into production server
ssh [email protected]

# Export database
wp db export muddy-production.sql --add-drop-table

Import to local:

# Copy database file to local
scp [email protected]:~/muddy-production.sql ./

# Import database
wp db import muddy-production.sql

# Search and replace URLs
wp search-replace 'https://gomuddy.com' 'http://muddy-local.test' --all-tables

# Update home and site URLs
wp option update home 'http://muddy-local.test'
wp option update siteurl 'http://muddy-local.test'

# Clear caches
wp cache flush
wp transient delete --all

Create Fresh Database​

# Create database
wp db create

# Install WordPress
wp core install \
  --url=http://muddy-local.test \
  --title="Muddy Local" \
  --admin_user=admin \
  --admin_password=admin \
  [email protected]

# Import sample data (optional)
wp plugin install wordpress-importer --activate
wp import sample-data.xml --authors=create

WordPress Configuration​

wp-config.php Setup​

<?php
/**
 * Local development configuration for Muddy
 */

// Database
define( 'DB_NAME', 'muddy_local' );
define( 'DB_USER', 'muddy' );
define( 'DB_PASSWORD', 'muddy_local' );
define( 'DB_HOST', 'localhost' );
define( 'DB_CHARSET', 'utf8mb4' );
define( 'DB_COLLATE', '' );

// Authentication keys (use https://api.wordpress.org/secret-key/1.1/salt/)
define( 'AUTH_KEY',         'put your unique phrase here' );
define( 'SECURE_AUTH_KEY',  'put your unique phrase here' );
define( 'LOGGED_IN_KEY',    'put your unique phrase here' );
define( 'NONCE_KEY',        'put your unique phrase here' );
define( 'AUTH_SALT',        'put your unique phrase here' );
define( 'SECURE_AUTH_SALT', 'put your unique phrase here' );
define( 'LOGGED_IN_SALT',   'put your unique phrase here' );
define( 'NONCE_SALT',       'put your unique phrase here' );

// Database table prefix
$table_prefix = 'wp_';

// Debugging (enable for local development)
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

// BigCommerce credentials (use test store for local development)
define( 'BIGCOMMERCE_CLIENT_ID', 'your_test_client_id' );
define( 'BIGCOMMERCE_CLIENT_SECRET', 'your_test_client_secret' );
define( 'BIGCOMMERCE_ACCESS_TOKEN', 'your_test_access_token' );
define( 'BIGCOMMERCE_CHANNEL_ID', 123456 );

// Klaviyo credentials (use test account)
define( 'KLAVIYO_API_KEY', 'pk_test_xxxxxxxxxxxxx' );
define( 'KLAVIYO_COMPANY_ID', 'XTXbL5' );

// Algolia credentials (use development index)
define( 'ALGOLIA_APP_ID', 'XXXXXXXX' );
define( 'ALGOLIA_SEARCH_KEY', 'xxxxxxxxxxxxx' );
define( 'ALGOLIA_ADMIN_KEY', 'xxxxxxxxxxxxx' );

// Disable external HTTP requests (optional, speeds up local dev)
// define( 'WP_HTTP_BLOCK_EXTERNAL', true );
// define( 'WP_ACCESSIBLE_HOSTS', 'api.bigcommerce.com,a.klaviyo.com' );

// Memory limits
define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );

// Absolute path to WordPress directory
if ( ! defined( 'ABSPATH' ) ) {
    define( 'ABSPATH', __DIR__ . '/' );
}

// Load WordPress
require_once ABSPATH . 'wp-settings.php';

Local Environment Constants​

// wp-content/mu-plugins/local-environment.php

<?php
/**
 * Local development environment configuration
 */

// Disable external services in local development
add_filter( 'pre_http_request', function( $preempt, $args, $url ) {
    // Allow specific services
    $allowed_hosts = [
        'api.bigcommerce.com',
        'a.klaviyo.com',
        'api.algolia.io'
    ];
    
    $host = parse_url( $url, PHP_URL_HOST );
    
    if ( in_array( $host, $allowed_hosts, true ) ) {
        return $preempt;
    }
    
    // Block other external requests
    return new WP_Error( 'http_request_blocked', 'External HTTP requests are disabled in local development.' );
}, 10, 3 );

// Use local asset URLs
add_filter( 'stylesheet_directory_uri', function( $uri ) {
    return str_replace( 'https://gomuddy.com', 'http://muddy-local.test', $uri );
} );

// Disable email sending (log instead)
add_filter( 'wp_mail', function( $args ) {
    error_log( 'Email would be sent to: ' . $args['to'] );
    error_log( 'Subject: ' . $args['subject'] );
    return false; // Prevent actual sending
} );

Plugin Installation​

Install Required Plugins​

# BigCommerce for WordPress (Suma Fork)
wp plugin install /path/to/bigcommerce-suma-v5.0.7.10.zip --activate

# Elementor & Elementor Pro
wp plugin install elementor --activate
wp plugin install /path/to/elementor-pro.zip --activate

# Suma Plugins
wp plugin install /path/to/suma-patches-v1.5.21.zip --activate
wp plugin install /path/to/suma-dealer-locator-v3.0.2.zip --activate
wp plugin install /path/to/suma-analytics-v1.3.4.zip --activate
wp plugin install /path/to/suma-bazaarvoice-integrator-v1.1.4.zip --activate
wp plugin install /path/to/back-in-stock-notifications-v1.2.4.zip --activate
wp plugin install /path/to/gift-certificate-creator-v1.0.0.zip --activate
wp plugin install /path/to/narvar-middleware-v1.2.7.zip --activate

# Search & Filtering
wp plugin install facetwp --activate
wp plugin install wp-search-with-algolia --activate

# Development Tools
wp plugin install query-monitor --activate
wp plugin install debug-bar --activate

Configure Plugins​

# FacetWP license
wp option update facetwp_license 'your_license_key'

# Algolia settings
wp option update algolia_application_id 'XXXXXXXX'
wp option update algolia_search_api_key 'xxxxxxxxxxxxx'
wp option update algolia_api_key 'xxxxxxxxxxxxx'

Theme Setup​

Install Suma Elementor Theme​

# Copy theme files
cp -r /path/to/suma-elementor wp-content/themes/

# Activate theme
wp theme activate suma-elementor

# Install theme dependencies
cd wp-content/themes/suma-elementor
composer install --no-dev
npm install

Build Theme Assets​

# Development build with watch
npm run dev

# Or watch mode for live reload
npm run watch

# Production build
npm run production

Configure Theme Settings​

Navigate to Appearance → Customize and configure:

  • Site Identity: Logo, site title, tagline
  • Colors: Primary, secondary, accent colors
  • Typography: Heading and body fonts
  • Header: Layout, menu, cart icon
  • Footer: Columns, social links, copyright
  • Shop: Product grid columns, pagination

BigCommerce Setup​

Create Test Store​

  1. Sign up for BigCommerce trial at https://www.bigcommerce.com
  2. Configure store settings
  3. Import sample products
  4. Create API credentials

Connect to WordPress​

# Run connection wizard
wp bigcommerce connect

Or manually configure in WordPress admin:

Navigate to BigCommerce → Settings and enter API credentials.

Import Products​

# Import all products
wp bigcommerce import products --all

# Import specific categories
wp bigcommerce import products --category=12,34

# Monitor import progress
wp bigcommerce queue status

Development Workflow​

Daily Workflow​

# Pull latest changes
git pull origin develop

# Update dependencies
composer install
npm install

# Start development server with watch
npm run watch

# (Optional) Sync database from staging
wp db export backup-$(date +%Y%m%d).sql
wp db import staging-latest.sql
wp search-replace 'https://staging.gomuddy.com' 'http://muddy-local.test' --all-tables

Making Changes​

PHP Changes​

# Edit PHP files in your code editor
# Changes are reflected immediately (no build required)

# Check for PHP errors
wp eval 'error_log( "Test error logging" );'
tail -f wp-content/debug.log

CSS/JS Changes​

# Keep watch mode running
npm run watch

# Changes auto-compile and browser auto-reloads (if BrowserSync configured)

Template Changes​

# Edit theme template files
# Refresh browser to see changes

# Clear WordPress cache
wp cache flush

Git Workflow​

# Create feature branch
git checkout -b feature/new-product-widget

# Make changes and commit
git add .
git commit -m "Add new product carousel widget"

# Push to remote
git push origin feature/new-product-widget

# Create pull request on GitHub

Testing​

Unit Testing (PHPUnit)​

# Install testing dependencies
composer require --dev phpunit/phpunit
composer require --dev wp-cli/wp-cli-tests

# Run tests
./vendor/bin/phpunit

JavaScript Testing (Jest)​

# Install Jest
npm install --save-dev jest @testing-library/jest-dom

# Run tests
npm test

Browser Testing​

Manual Testing Checklist:

  • Homepage loads correctly
  • Product pages display properly
  • Add to cart functionality works
  • Cart page updates correctly
  • Checkout redirects to BigCommerce
  • Search returns results
  • Filters work correctly
  • Dealer locator displays map
  • Forms submit successfully
  • Responsive design on mobile

Automated Browser Testing (Playwright):

# Install Playwright
npm install --save-dev @playwright/test

# Run tests
npx playwright test

Debugging​

Enable Debug Mode​

Already enabled in wp-config.php for local development:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

View Debug Logs​

# Watch debug log in real-time
tail -f wp-content/debug.log

# View last 50 lines
tail -n 50 wp-content/debug.log

Query Monitor Plugin​

Navigate to Admin Bar → Query Monitor to view:

  • Database queries
  • HTTP requests
  • Hooks and actions
  • Template files loaded
  • PHP errors
  • Performance metrics

Browser DevTools​

JavaScript Console:

// Check if scripts are loaded
console.log(window.jQuery);
console.log(window.Alpine);
console.log(window.MuddyCart);

// Test cart functionality
MuddyCart.addToCart(12345, 67890, 1);

// Check dataLayer
console.log(window.dataLayer);

Xdebug (Advanced)​

Install Xdebug:

# macOS with Homebrew
pecl install xdebug

# Enable in php.ini
zend_extension="xdebug.so"
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

Configure VS Code:

// .vscode/launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

Performance Optimization​

Disable Unnecessary Plugins in Development​

# Disable caching plugins
wp plugin deactivate wp-rocket
wp plugin deactivate w3-total-cache

# Disable performance plugins that interfere with debugging
wp plugin deactivate autoptimize

Enable Query Monitor​

wp plugin activate query-monitor

Optimize Database​

# Optimize all tables
wp db optimize

# Clean up revisions
wp post delete $(wp post list --post_type='revision' --format=ids) --force

# Clean up transients
wp transient delete --all

Deployment​

Deploy to Staging​

# Build production assets
npm run production

# Export database
wp db export muddy-staging.sql

# Deploy via SFTP or Git
# (Specific deployment process depends on hosting setup)

Deploy to Production​

# Build production assets
npm run production

# Run tests
npm test
./vendor/bin/phpunit

# Create release tag
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

# Deploy via CI/CD pipeline or manual process

Troubleshooting​

Common Issues​

White Screen of Death:

# Check error logs
tail -f wp-content/debug.log

# Enable WP_DEBUG_DISPLAY temporarily
# Edit wp-config.php: define( 'WP_DEBUG_DISPLAY', true );

Database Connection Error:

# Test database connection
wp db check

# Verify credentials in wp-config.php

Assets Not Loading:

# Rebuild assets
npm run production

# Clear browser cache
# Check asset URLs in browser DevTools Network tab

BigCommerce Sync Issues:

# Check webhook status
wp bigcommerce webhooks list

# Re-register webhooks
wp bigcommerce webhooks register

# Clear import queue
wp bigcommerce queue clear

Plugin Conflicts:

# Disable all plugins
wp plugin deactivate --all

# Activate plugins one by one
wp plugin activate plugin-name

# Identify conflicting plugin

Additional Resources​

Documentation​

Support​

  • Rhino Group Internal Wiki: (internal link)
  • Slack Channel: #muddy-development
  • Issue Tracker: GitHub Issues

Code Standards​

# Install code quality tools
composer require --dev squizlabs/php_codesniffer
composer require --dev wp-coding-standards/wpcs

# Run PHP_CodeSniffer
./vendor/bin/phpcs --standard=WordPress wp-content/themes/suma-elementor

# Run ESLint
npm run lint