Skip to main content

Development Setup

Local development environment configuration for HHA Sports WordPress site.

Overview​

This guide covers setting up a local development environment for the HHA Sports retail site using Herd, managing the database, and working with the codebase.

Local Environment​

Repository Location​

Path: Z:\Repos\hhasports

Development Stack​

Environment Manager: Laravel Herd or similar local development environment

Requirements:

  • PHP: 7.4+ (optimal: 7.4)
  • MySQL: 5.6+ or MariaDB 10.1+
  • WordPress: 6.7.2
  • Web Server: Nginx or Apache

Database Configuration​

Database Name: wp_hhasports
User: root
Password: (empty)
Host: 127.0.0.1:3306
Table Prefix: wp_

wp-config.php:

define('DB_NAME', 'wp_hhasports');
define('DB_USER', 'root');
define('DB_PASSWORD', '');
define('DB_HOST', '127.0.0.1:3306');
define('DB_CHARSET', 'utf8');
define('DB_COLLATE', 'utf8_unicode_ci');
$table_prefix = 'wp_';

Initial Setup​

1. Clone Repository​

cd Z:\Repos
git clone <repository-url> hhasports
cd hhasports

2. Database Setup​

Import Database:

mysql -u root wp_hhasports < database-backup.sql

Or use GUI tool (phpMyAdmin, TablePlus, etc.)

3. Configure wp-config.php​

For Local Development:

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

4. Update Site URLs​

Update via SQL:

UPDATE wp_options 
SET option_value = 'http://hhasports.test' 
WHERE option_name IN ('siteurl', 'home');

Or via WP-CLI:

wp search-replace 'https://hhasports.com' 'http://hhasports.test'

5. File Permissions​

Unix/Mac:

chmod -R 755 wp-content/
chmod -R 777 wp-content/uploads/

Windows: Ensure appropriate permissions for web server user.

Plugin Configuration​

BigCommerce API Credentials​

Location: BigCommerce → Settings → API Credentials

For Development:

  • Use separate BigCommerce channel for dev environment
  • Create dev-specific API credentials
  • Configure webhook URLs to point to local site

Important: Don't sync dev changes back to production BigCommerce store.

Suma Patches Dev Site Detection​

Suma Patches automatically detects dev environments and:

  • Redirects all emails to configured address
  • Sets suma_is_dev_site option to yes
  • May disable certain production features

Email Override: Configure in Suma Patches settings to prevent production emails.

FacetWP​

Re-index facets after database import:

wp facetwp index

Or: Settings → FacetWP → Indices → Re-index

Algolia​

Use separate Algolia index for development:

  1. Create dev indices in Algolia dashboard (e.g., dev_products, dev_posts)
  2. Update Algolia settings to use dev indices
  3. Re-index content: 
    wp algolia reindex

Theme Development​

Theme Location​

Parent: wp-content/themes/suma-elementor/
Child: wp-content/themes/suma-elementor-child/

Asset Compilation​

Note: Build process not explicitly defined in codebase. Compiled assets in dist/.

If build tools are available:

cd wp-content/themes/suma-elementor
# Run build command (npm run dev, grunt, etc.)

Elementor Development​

Enable Elementor Debug Mode:

  1. Elementor → Settings → Advanced
  2. Switch Editor Loader Method → Enable
  3. Enable Debug Mode

Clear Elementor Cache:

  • Elementor → Tools → Regenerate CSS
  • Elementor → Tools → Regenerate Files & Data

Theme Customizations​

Edit child theme files in wp-content/themes/suma-elementor-child/:

  • functions.php - Theme setup
  • inc/class-theme.php - Main theme class
  • inc/class-bigcommerce-product.php - BC customizations
  • inc/class-klaviyo.php - Klaviyo tracking
  • inc/class-yotpo.php - Yotpo reviews
  • bigcommerce/components/ - BC template overrides

After changes:

  1. Clear WordPress cache
  2. Clear browser cache
  3. Regenerate Elementor CSS

Plugin Development​

Custom Plugins​

Suma Dealer Locator: wp-content/plugins/suma-dealer-locator/
Suma Patches: wp-content/plugins/suma-patches/
Suma Analytics: wp-content/plugins/suma-analytics-master/

Suma Analytics Build​

Location: wp-content/plugins/suma-analytics-master/

Build Process:

cd wp-content/plugins/suma-analytics-master
npm install
npm run dev        # Development build
npm run watch      # Watch for changes
npm run production # Production build

Config: webpack.mix.js (Laravel Mix)

WordPress CLI (WP-CLI)​

Common Commands​

Site Management​

# Check WordPress version
wp core version

# Update WordPress
wp core update

# Verify checksums
wp core verify-checksums

Plugin Management​

# List plugins
wp plugin list

# Activate plugin
wp plugin activate plugin-name

# Deactivate plugin
wp plugin deactivate plugin-name

# Update plugins
wp plugin update --all

Database​

# Export database
wp db export backup.sql

# Import database
wp db import backup.sql

# Search and replace
wp search-replace 'old-url' 'new-url'

# Optimize database
wp db optimize

BigCommerce Commands​

# Import products
wp bigcommerce import products

# Clear BigCommerce cache
wp bigcommerce cache clear

# Check import status
wp bigcommerce import status

Algolia Commands​

# Re-index all
wp algolia reindex

# Index specific content type
wp algolia reindex --indices=posts

# Clear index
wp algolia clear

FacetWP Commands​

# Re-index facets
wp facetwp index

# Clear FacetWP cache
wp cache flush

User Management​

# Create admin user
wp user create username [email protected] --role=administrator

# Update password
wp user update username --user_pass=newpassword

# List users
wp user list

Debugging​

Debug Log​

Location: wp-content/debug.log

Enable in wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

View log:

tail -f wp-content/debug.log

Query Monitor Plugin​

Recommended: Install Query Monitor for development debugging.

wp plugin install query-monitor --activate

Features:

  • Database queries analysis
  • PHP errors and warnings
  • HTTP requests
  • Hooks and actions
  • Template files used
  • Scripts and styles enqueued

Elementor Debug​

Debug Info: Elementor → System Info

Shows:

  • Server environment
  • WordPress environment
  • Plugin versions
  • Theme details
  • Elementor settings

BigCommerce Debug​

Check import log: BigCommerce → Settings → Diagnostics

Enable verbose logging in BigCommerce settings.

Browser DevTools​

JavaScript Errors: Check browser console for:

  • Klaviyo tracking issues
  • Algolia search errors
  • FacetWP AJAX failures
  • Elementor widget errors

Network Tab: Monitor:

  • AJAX requests
  • API calls to BigCommerce
  • Algolia queries
  • Image loading

Caching​

Development Caching​

Disable caching during development:

wp-config.php:

define('WP_CACHE', false);

Disable Object Cache:

  • Remove wp-content/advanced-cache.php
  • Remove wp-content/object-cache.php

Clear All Caches:

# WordPress cache
wp cache flush

# FacetWP cache
# Settings → FacetWP → Tools → Clear Cache

# Elementor cache
# Elementor → Tools → Regenerate CSS

# Browser cache
# Hard refresh: Ctrl+Shift+R or Cmd+Shift+R

WP Rocket Configuration​

For Development:

  • Disable WP Rocket or clear cache frequently
  • Exclude development pages from caching
  • Use WP Rocket DevMode

Git Workflow​

Branch Strategy​

Recommended:

  • main - Production code
  • staging - Staging environment
  • develop - Active development
  • feature/* - Feature branches
  • hotfix/* - Production fixes

Gitignore​

Typical .gitignore for WordPress:

# WordPress core
wp-admin/
wp-includes/
wp-*.php
xmlrpc.php
readme.html
license.txt

# Configuration
wp-config.php
.htaccess

# Uploads
wp-content/uploads/

# Caching
wp-content/cache/
wp-content/advanced-cache.php

# Logs
*.log
wp-content/debug.log

# Node modules
node_modules/
npm-debug.log

# Composer
vendor/

# OS files
.DS_Store
Thumbs.db

Committing Changes​

Best Practices:

  1. Don't commit wp-config.php (use wp-config-sample.php)
  2. Don't commit uploads
  3. Commit plugin/theme updates separately
  4. Write descriptive commit messages
  5. Test before committing

Sync with Production​

Database Sync​

Export from Production:

# On production server
wp db export production-backup.sql

Import to Local:

mysql -u root wp_hhasports < production-backup.sql
wp search-replace 'https://hhasports.com' 'http://hhasports.test'

File Sync​

Uploads:

# Rsync from production
rsync -avz user@server:/path/to/wp-content/uploads/ ./wp-content/uploads/

Plugins/Themes (if not in git):

rsync -avz user@server:/path/to/wp-content/plugins/ ./wp-content/plugins/
rsync -avz user@server:/path/to/wp-content/themes/ ./wp-content/themes/

Testing​

Manual Testing Checklist​

General:

  • Homepage loads correctly
  • Menu navigation works
  • Search functionality (Algolia)
  • Product catalog displays
  • Product filtering (FacetWP)
  • Product detail pages
  • Add to cart functionality
  • Cart page
  • Checkout process
  • User account pages
  • Forms submit correctly
  • Dealer locator works
  • Job listings display

Integrations:

  • Klaviyo tracking (check browser console)
  • Yotpo reviews display
  • BigCommerce product sync
  • Algolia search results
  • FacetWP filters update

Responsive:

  • Mobile layout (< 768px)
  • Tablet layout (768px - 1024px)
  • Desktop layout (> 1024px)

Browser Testing​

Browsers:

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest)
  • Edge (latest)
  • Mobile Safari (iOS)
  • Chrome Mobile (Android)

Performance Testing​

Tools​

GTmetrix: https://gtmetrix.com/
Google PageSpeed Insights: https://pagespeed.web.dev/
WebPageTest: https://www.webpagetest.org/

Optimization Checklist​

  • Images optimized (WP Smush)
  • Caching enabled (WP Rocket)
  • Minification enabled (CSS, JS)
  • Lazy loading enabled
  • Database optimized
  • Unused plugins removed
  • HTTP/2 enabled on server
  • CDN configured (if applicable)

Deployment​

Pre-Deployment Checklist​

  • Test all functionality on staging
  • Database backup created
  • File backup created
  • Plugin versions documented
  • Theme version documented
  • BigCommerce sync tested
  • Caching cleared
  • Debug mode disabled
  • Error reporting disabled

Deployment Process​

Via Git:

  1. Merge feature branch to main
  2. Pull on production server
  3. Run any necessary migrations
  4. Clear caches
  5. Test production site

Manual Deployment:

  1. FTP/SFTP changed files
  2. Import database changes (if any)
  3. Clear caches
  4. Test production site

Post-Deployment:

  1. Verify homepage loads
  2. Test critical functionality
  3. Check error logs
  4. Monitor for issues

Troubleshooting​

Common Issues​

White Screen of Death (WSOD)​

Solution:

  1. Enable WP_DEBUG in wp-config.php
  2. Check debug.log
  3. Deactivate plugins one by one
  4. Switch to default theme
  5. Check file permissions

Database Connection Error​

Solution:

  1. Verify database credentials in wp-config.php
  2. Check MySQL service is running
  3. Test database connection manually
  4. Check database user permissions

BigCommerce Import Stuck​

Solution:

  1. Check cron jobs: wp cron event list
  2. Run import manually: wp bigcommerce import products
  3. Check BigCommerce API credentials
  4. Review import log in BigCommerce settings
  5. Increase PHP memory limit and max execution time

Elementor Editor Not Loading​

Solution:

  1. Clear Elementor cache
  2. Switch editor loader method
  3. Check for JavaScript errors
  4. Deactivate conflicting plugins
  5. Regenerate CSS

FacetWP Not Filtering​

Solution:

  1. Re-index facets
  2. Check facet configuration
  3. Clear FacetWP cache
  4. Verify template query is correct
  5. Check for JavaScript errors

Resources​

Documentation​

Support​

  • Rhino Group: [email protected]
  • BigCommerce Support: Via BigCommerce account
  • Elementor Support: Via Elementor account
  • Gravity Forms Support: Via Gravity Forms account