Development Setup

Overview

This guide covers setting up a local development environment for the Walkers Game Ear WordPress site, including BigCommerce integration, custom plugins, and build tools.

Prerequisites

Required Software

Software	Minimum Version	Purpose
PHP	7.4	WordPress core requirement
MySQL	5.6 / MariaDB 10.1	Database
Node.js	16.x	Asset compilation
npm	8.x	Package management
Composer	2.x	PHP dependency management
Git	2.x	Version control

Recommended Tools

Laravel Herd or Local by Flywheel — Local WordPress environment
Sequel Pro or TablePlus — Database management
VS Code — Code editor
WP-CLI — WordPress command-line tool

Local Environment Setup

Option 1: Laravel Herd (Recommended)

Herd is a fast, native PHP development environment for macOS and Windows.

Install Herd: Download from herd.laravel.com

Park directory:

cd Z:\Herd  # or your projects folder
herd park

Create site:

mkdir walkers
cd walkers
herd link walkershearingprotection

Install WordPress:

wp core download
wp config create --dbname=wp_walkers --dbuser=root --dbpass= --dbhost=127.0.0.1
wp core install --url=walkershearingprotection.test --title="Walkers" --admin_user=admin --admin_password=admin [email protected]

Option 2: Local by Flywheel

Install Local: Download from localwp.com
Create new site:
- Site name: Walkers Game Ear
- PHP: 7.4 or 8.0
- Web server: Nginx
- Database: MySQL 5.7
Start site and note the local URL

Database Import

Export from production/staging:

wp db export walkers-backup.sql --ssh=production

Import locally:
```
wp db import walkers-backup.sql
```

Search and replace URLs:

wp search-replace 'walkershearingprotection.com' 'walkershearingprotection.test'

Repository Setup

Clone Repository

cd Z:\Repos  # or your repos folder
git clone [email protected]:rhino-group/walkers.git
cd walkers

Git Configuration

Recommended .gitignore (if not present):

# WordPress core
/wp-admin/
/wp-includes/
/wp-content/index.php
/wp-content/languages/
/wp-content/upgrade/
/wp-content/uploads/

# WordPress config
wp-config.php
wp-config-local.php
.htaccess

# Plugins (exclude custom)
/wp-content/plugins/*
!/wp-content/plugins/bigcommerce-suma/
!/wp-content/plugins/suma-*/

# Themes (exclude custom)
/wp-content/themes/*
!/wp-content/themes/suma-elementor/
!/wp-content/themes/suma-elementor-child/

# Build artifacts
node_modules/
vendor/
*.log
.DS_Store

Plugin Development Setup

Install Dependencies

For plugins with Composer dependencies:

# BigCommerce plugin
cd wp-content/plugins/bigcommerce-suma
composer install --no-dev

# Suma Dealer Locator
cd ../suma-dealer-locator
composer install

Theme Development Setup

Install Node Modules

cd wp-content/themes/suma-elementor
npm install

Development Build

Watch mode (auto-recompile on changes):

npm run watch

Tailwind CSS watch:

npm run tw:watch

Production Build

Before deploying to staging/production:

# Compile and minify assets
npm run prod

# Build Tailwind CSS
npm run tw:build

# Build Elementor widgets
npm run prod-widgets

BigCommerce API Setup

Create BigCommerce App

Log into BigCommerce store
Navigate to: Advanced Settings → API Accounts → Create API Account
Account type: Store-level API account
OAuth Scopes:
- Products: Read-only (or Modify if syncing back)
- Orders: Read-only
- Customers: Modify
- Carts: Modify
- Checkouts: Modify
- Channel: Modify
Save credentials: Client ID, Secret, Access Token

Configure WordPress

Navigate to: BigCommerce → Settings → API Credentials
Enter credentials from BigCommerce
Test connection: Click "Connect"
Set channel: Select or create channel for this WordPress site
Run initial import: Products → Import Now

Local API Testing

To avoid importing thousands of products locally:

Disable automatic sync: Settings → Import → Set to "Never"

Import select products:

wp bigcommerce import products --limit=10

Use staging data: Copy production database, use staging API credentials

Local Environment Variables

wp-config-local.php

Create a local config file (ignored by Git):

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

// Database
define('DB_NAME', 'wp_walkers');
define('DB_USER', 'root');
define('DB_PASSWORD', '');
define('DB_HOST', '127.0.0.1:3306');

// Debug mode
define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY', true);
define('WP_DEBUG_LOG', true);
define('SCRIPT_DEBUG', true);

// BigCommerce (use sandbox)
define('BIGCOMMERCE_API_URL', 'https://api.bigcommerce.com');

Include in main wp-config.php:

if (file_exists(__DIR__ . '/wp-config-local.php')) {
    require_once __DIR__ . '/wp-config-local.php';
}

Testing Integrations

Klaviyo (Local)

For local testing without sending real events:

Use test API key: Get from Klaviyo → Settings → API Keys

Disable on local:

// functions.php
if (WP_DEBUG) {
    add_filter('suma_klaviyo_enabled', '__return_false');
}

BazaarVoice (Staging)

Use BazaarVoice staging environment:

Settings: BazaarVoice → Settings
Environment: Select "Staging"
Site ID: Use staging site ID
Test reviews: Will show staging data

Algolia (Development Index)

Create separate Algolia index for local:

Algolia Dashboard: Create index walkers_dev
WordPress Settings: WP Search with Algolia
Index Prefix: Set to walkers_dev
Re-index: Indices → Re-index

FacetWP (Local)

FacetWP requires re-indexing after database import:

Navigate to: Settings → FacetWP → Settings
Click: "Re-index"
Wait: for indexing to complete (can take several minutes)

Development Workflow

Typical Development Day

Start local environment: Open Herd or Local
Pull latest code:
```
git pull origin main
```

Install dependencies:

cd wp-content/themes/suma-elementor && npm install

Start watch mode:
```
npm run watch
```
Make changes: Edit PHP, SCSS, JS files
Test in browser: Check http://walkershearingprotection.test

Commit changes:

git add .
git commit -m "Description of changes"
git push origin feature-branch

Feature Branch Workflow

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

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

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

# Create pull request on GitHub
# After approval, merge and delete branch

Code Standards

PHP: Follow WordPress Coding Standards

# Install PHP_CodeSniffer
composer global require "squizlabs/php_codesniffer=*"

# Check files
phpcs --standard=WordPress wp-content/themes/suma-elementor/inc/

JavaScript: ESLint with WordPress preset

npm install --save-dev eslint eslint-config-wordpress
npx eslint src/js/

CSS: Stylelint

npm install --save-dev stylelint stylelint-config-standard
npx stylelint "src/scss/**/*.scss"

Debugging

WordPress Debug Log

Enable in wp-config.php:

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

View log:

tail -f wp-content/debug.log

Query Monitor Plugin

Install for advanced debugging:

wp plugin install query-monitor --activate

Shows:

Database queries
PHP errors
Hooks fired
HTTP API calls
Environment info

Xdebug Setup

Herd includes Xdebug, just enable:

herd xdebug on

VS Code configuration (.vscode/launch.json):

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/Users/you/Herd/walkers": "${workspaceFolder}"
            }
        }
    ]
}

Common Issues

BigCommerce Products Not Syncing

Problem: Products not importing locally
Solution:

Check API credentials are correct
Verify channel configuration
Check WordPress cron is running: wp cron event list
Run manual import: wp bigcommerce import products

Assets Not Compiling

Problem: npm run watch throws errors
Solution:

Delete node_modules and package-lock.json
Run npm install
Check Node.js version: node -v (should be 16.x+)
Clear npm cache: npm cache clean --force

Elementor Widgets Missing

Problem: Custom widgets not appearing in Elementor
Solution:

Clear Elementor cache: Elementor → Tools → Regenerate CSS
Check widget registration: wp-content/themes/suma-elementor/inc/class-elementor-widgets.php
Verify widget files exist in inc/widgets/
Check for PHP errors: wp-content/debug.log

FacetWP Not Filtering

Problem: Filters not working after database import
Solution:

Re-index: Settings → FacetWP → Settings → Re-index
Check permalinks: Settings → Permalinks → Save Changes
Clear all caches
Test with FacetWP debug mode: Add ?fwp_debug=true to URL

Deployment

Staging Deployment

# Build production assets
cd wp-content/themes/suma-elementor
npm run prod

# Commit built files
git add dist/
git commit -m "Build assets for staging"

# Push to staging branch
git push origin staging

On staging server:

cd /var/www/walkers-staging
git pull origin staging
wp cache flush

Production Deployment

Test on staging: Verify all changes work

Create release tag:

git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

Merge to main:

git checkout main
git merge staging
git push origin main

Deploy to production: Via CI/CD or manual pull

Performance Testing

Local Performance Tools

Blackfire.io (profiling):

herd blackfire on

New Relic (monitoring):

Install New Relic PHP extension
Configure in php.ini

Speed Testing

Test page load times:

# Install Apache Bench
brew install httpd  # macOS

# Test 100 requests, 10 concurrent
ab -n 100 -c 10 http://walkershearingprotection.test/

Overview​

Prerequisites​

Required Software​

Recommended Tools​

Local Environment Setup​

Option 1: Laravel Herd (Recommended)​

Option 2: Local by Flywheel​

Database Import​

Repository Setup​

Clone Repository​

Git Configuration​

Plugin Development Setup​

Install Dependencies​

Theme Development Setup​

Install Node Modules​

Development Build​

Production Build​

BigCommerce API Setup​

Create BigCommerce App​

Configure WordPress​

Local API Testing​

Local Environment Variables​

wp-config-local.php​

Testing Integrations​

Klaviyo (Local)​

BazaarVoice (Staging)​

Algolia (Development Index)​

FacetWP (Local)​

Development Workflow​

Typical Development Day​

Feature Branch Workflow​

Code Standards​

Debugging​

WordPress Debug Log​

Query Monitor Plugin​

Xdebug Setup​

Common Issues​

BigCommerce Products Not Syncing​

Assets Not Compiling​

Elementor Widgets Missing​

FacetWP Not Filtering​

Deployment​

Staging Deployment​

Production Deployment​

Performance Testing​

Local Performance Tools​

Speed Testing​

Resources​

Documentation​

Support​

Next Steps​