Development Setup

Complete guide for setting up a local development environment for the ScentLok site.

Prerequisites

Required Software

PHP: 8.1 or higher
MySQL: 8.0 or higher
Node.js: 20.x LTS
Composer: 2.x
Git: Latest version

Recommended Tools

Laravel Herd (macOS/Windows) or Local by Flywheel (macOS/Windows)
VS Code with extensions:
- PHP Intelephense
- ESLint
- Prettier
- Tailwind CSS IntelliSense
Postman or Insomnia for API testing
TablePlus or phpMyAdmin for database management

Local Environment Setup

Option 1: Laravel Herd (Recommended)

Laravel Herd provides the simplest setup experience:

# Install Herd from https://herd.laravel.com

# Create site directory
cd ~/Herd
mkdir scentlok.test
cd scentlok.test

# Herd automatically serves sites at https://scentlok.test

Option 2: Local by Flywheel

# Install Local from https://localwp.com

# Create new site in Local:
# - Site name: ScentLok
# - PHP: 8.1
# - Web Server: Nginx
# - MySQL: 8.0

# Start site and note the local URL

Option 3: Docker

# docker-compose.yml
version: '3.8'

services:
  wordpress:
    image: wordpress:latest
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: wordpress
      WORDPRESS_DB_NAME: scentlok
    volumes:
      - ./wp-content:/var/www/html/wp-content

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: scentlok
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: wordpress
      MYSQL_ROOT_PASSWORD: root
    volumes:
      - db_data:/var/lib/mysql

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db

volumes:
  db_data:

# Start Docker containers
docker-compose up -d

WordPress Installation

Download WordPress

# Using WP-CLI (recommended)
wp core download --locale=en_US

# Or download from wordpress.org
curl -O https://wordpress.org/latest.zip
unzip latest.zip

Configure WordPress

// wp-config.php
define( 'DB_NAME', 'scentlok' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', '' );
define( 'DB_HOST', 'localhost' );
define( 'DB_CHARSET', 'utf8mb4' );
define( 'DB_COLLATE', '' );

// Authentication keys (generate at 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' );

$table_prefix = 'wp_';

// Development settings
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

// BigCommerce API credentials (use test store)
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_STORE_HASH', 'your-test-store-hash' );

// SLoyalty API credentials (use test account)
define( 'SLOYALTY_API_KEY', 'your-test-api-key' );

// Klaviyo credentials
define( 'KLAVIYO_API_KEY', 'your-test-api-key' );
define( 'KLAVIYO_COMPANY_ID', 'VE7rVK' );

// Disable WP Cron in development
define( 'DISABLE_WP_CRON', true );

if ( ! defined( 'ABSPATH' ) ) {
    define( 'ABSPATH', __DIR__ . '/' );
}

require_once ABSPATH . 'wp-settings.php';

Install WordPress

# Using WP-CLI
wp core install \
  --url=https://scentlok.test \
  --title="ScentLok" \
  --admin_user=admin \
  --admin_password=password \
  [email protected]

# Or visit http://scentlok.test and follow installation wizard

Plugin Installation

Install Required Plugins

# Core plugins
wp plugin install \
  elementor \
  elementor-pro \
  advanced-custom-fields-pro \
  facetwp \
  wp-search-with-algolia \
  --activate

# Install custom plugins from Git
cd wp-content/plugins

# BigCommerce for WordPress (Suma fork)
git clone [email protected]:rhino-group/bigcommerce-for-wordpress.git
cd bigcommerce-for-wordpress
composer install
cd ..

# Suma plugins
git clone [email protected]:rhino-group/suma-dealer-locator.git
git clone [email protected]:rhino-group/suma-patches.git
git clone [email protected]:rhino-group/suma-analytics.git
git clone [email protected]:rhino-group/suma-bazaarvoice-integrator.git
git clone [email protected]:rhino-group/back-in-stock-notifications.git
git clone [email protected]:rhino-group/bigcommerce-middleware-for-narvar.git

# Activate custom plugins
wp plugin activate \
  bigcommerce-for-wordpress \
  suma-dealer-locator \
  suma-patches \
  suma-analytics \
  suma-bazaarvoice-integrator \
  back-in-stock-notifications \
  bigcommerce-middleware-for-narvar

Install Plugin Dependencies

# Install Composer dependencies for each plugin
for plugin in wp-content/plugins/suma-* wp-content/plugins/bigcommerce-*; do
    if [ -f "$plugin/composer.json" ]; then
        cd "$plugin"
        composer install
        cd -
    fi
done

Theme Installation

Install Suma Elementor Theme

cd wp-content/themes

# Clone theme from Git
git clone [email protected]:rhino-group/suma-elementor.git

# Install dependencies
cd suma-elementor
composer install
npm install

# Build assets
npm run dev

# Activate theme
wp theme activate suma-elementor

Theme Build Process

# Development build (with source maps)
npm run dev

# Watch for changes
npm run watch

# Production build (optimized)
npm run production

BigCommerce Setup

Create Test Store

Sign up for BigCommerce trial at https://www.bigcommerce.com/
Create a new store for testing
Install "BigCommerce for WordPress" app from BC app marketplace
Copy API credentials to wp-config.php

Configure BigCommerce Plugin

# Set store connection
wp option update bigcommerce_store_settings '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_SECRET","access_token":"YOUR_TOKEN","store_hash":"YOUR_HASH"}'

# Initial product import
wp bigcommerce import products --limit=50

# Set up webhooks
wp bigcommerce webhooks register

Import Sample Products

# Import first 50 products
wp bigcommerce import products --limit=50

# Import specific category
wp bigcommerce import products --category=123

# Force re-import
wp bigcommerce import products --force

Database Setup

Import Database Backup

# Import production database (sanitized)
wp db import backup.sql

# Search and replace URLs
wp search-replace 'https://scentlok.com' 'https://scentlok.test'

# Clear caches
wp cache flush

Create Test Data

// create-test-data.php
<?php
require 'wp-load.php';

// Create test customers
for ( $i = 1; $i <= 10; $i++ ) {
    $user_id = wp_create_user(
        "testuser{$i}",
        'password123',
        "testuser{$i}@example.com"
    );
    
    wp_update_user([
        'ID'         => $user_id,
        'first_name' => "Test{$i}",
        'last_name'  => 'User',
    ]);
}

// Create test dealer locations
for ( $i = 1; $i <= 20; $i++ ) {
    wp_insert_post([
        'post_type'   => 'dealer',
        'post_title'  => "Test Dealer {$i}",
        'post_status' => 'publish',
        'meta_input'  => [
            'address'   => "{$i}00 Main St",
            'city'      => 'Springfield',
            'state'     => 'IL',
            'zip'       => '62701',
            'latitude'  => 39.7817 + ( $i * 0.01 ),
            'longitude' => -89.6501 + ( $i * 0.01 ),
        ],
    ]);
}

echo "Test data created!\n";

# Run test data script
php create-test-data.php

Development Tools

WP-CLI Aliases

Add to ~/.wp-cli/config.yml:

@scentlok:
  ssh: user@server
  path: /var/www/scentlok
  url: https://scentlok.com

aliases:
  dev:
    path: ~/Herd/scentlok.test
    url: https://scentlok.test

# Use aliases
wp @scentlok option get siteurl
wp @dev cache flush

Debugging Tools

Query Monitor

# Install Query Monitor for debugging
wp plugin install query-monitor --activate

Debug Bar

# Install Debug Bar
wp plugin install debug-bar --activate

Xdebug Configuration

; php.ini (for Herd/Local)
[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

VS Code launch.json:

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

Git Workflow

# Initialize Git repository
git init

# Create .gitignore
cat > .gitignore << 'EOF'
# WordPress core
/wp-admin/
/wp-includes/
/wp-content/index.php
/wp-content/plugins/index.php
/wp-content/themes/index.php

# Configuration
wp-config.php
.htaccess

# Caches
/wp-content/cache/
/wp-content/uploads/cache/

# Logs
*.log
debug.log

# OS files
.DS_Store
Thumbs.db

# Node
node_modules/
npm-debug.log

# Build files
/wp-content/themes/suma-elementor/assets/dist/

# IDE
.vscode/
.idea/
*.sublime-*
EOF

# Initial commit
git add .
git commit -m "Initial commit"

API Testing

Test BigCommerce API

# Test product API
curl -X GET \
  "https://api.bigcommerce.com/stores/YOUR_STORE_HASH/v3/catalog/products?limit=10" \
  -H "X-Auth-Token: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Test SLoyalty API

# Test customer balance
curl -X GET \
  "https://api.sloyalty.com/v1/customers/[email protected]/balance" \
  -H "Authorization: Bearer e6838c7d" \
  -H "Content-Type: application/json"

Test WordPress REST API

# Get products
curl https://scentlok.test/wp-json/bigcommerce/v1/products

# Add to cart
curl -X POST https://scentlok.test/wp-json/bigcommerce/v1/cart/add \
  -H "Content-Type: application/json" \
  -d '{"product_id":123,"variant_id":456,"quantity":1}'

Running Tests

PHPUnit Tests

# Install PHPUnit
composer require --dev phpunit/phpunit

# Run tests
cd wp-content/plugins/bigcommerce-for-wordpress
vendor/bin/phpunit

# Run specific test
vendor/bin/phpunit tests/Integration/ProductSyncTest.php

JavaScript Tests

# Run Jest tests
cd wp-content/themes/suma-elementor
npm test

# Run with coverage
npm test -- --coverage

# Watch mode
npm test -- --watch

Cron Jobs

Manual Cron Execution

# Run WP Cron manually
wp cron event run --due-now

# List scheduled events
wp cron event list

# Schedule specific event
wp cron event schedule bigcommerce/import/queue now

Set up System Cron

# Edit crontab
crontab -e

# Add WordPress cron job (runs every 5 minutes)
*/5 * * * * cd /path/to/wordpress && wp cron event run --due-now --path=/path/to/wordpress

Performance Testing

Load Testing with WP-CLI

# Generate test content
wp post generate --count=100 --post_type=bigcommerce_product

# Benchmark database queries
wp db query "SELECT * FROM wp_posts WHERE post_type='bigcommerce_product'" --bench

Frontend Performance

# Install Lighthouse CLI
npm install -g lighthouse

# Run Lighthouse audit
lighthouse https://scentlok.test --output=html --output-path=./lighthouse-report.html

Troubleshooting

Common Issues

Cannot connect to database:

# Check MySQL is running
mysql.server status  # macOS
sudo systemctl status mysql  # Linux

# Test connection
mysql -u root -p

Plugin won't activate:

# Check for fatal errors
tail -f wp-content/debug.log

# Check PHP version
php -v

Asset build fails:

# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

BigCommerce sync not working:

# Check webhook status
wp bigcommerce webhooks list

# Re-register webhooks
wp bigcommerce webhooks register --force

# Check API credentials
wp eval "print_r( get_option( 'bigcommerce_store_settings' ) );"

Reset Development Environment

# Reset database
wp db reset --yes

# Reinstall WordPress
wp core install \
  --url=https://scentlok.test \
  --title="ScentLok" \
  --admin_user=admin \
  --admin_password=password \
  [email protected]

# Reactivate plugins
wp plugin activate --all

# Re-import products
wp bigcommerce import products --limit=50

Deployment

Pre-Deployment Checklist

Run production build: npm run production
Run tests: npm test && composer test
Check for PHP errors: wp eval "error_log('test');"
Verify API credentials are correct
Clear all caches
Test checkout flow
Verify BigCommerce webhook endpoints

Deploy to Staging

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

# Commit changes
git add .
git commit -m "Build assets for deployment"
git push origin main

# SSH to staging server
ssh [email protected]

# Pull changes
cd /var/www/staging
git pull origin main

# Run Composer
composer install --no-dev --optimize-autoloader

# Clear caches
wp cache flush
wp rewrite flush

Useful Commands

# Quick reference

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

# Reset BigCommerce data
wp bigcommerce cleanup --force

# Export database
wp db export scentlok-$(date +%Y%m%d).sql

# List all options
wp option list --search="*bigcommerce*"

# Check plugin status
wp plugin status

# Update all plugins
wp plugin update --all

# Check for WordPress updates
wp core check-update

Prerequisites​

Required Software​

Recommended Tools​

Local Environment Setup​

Option 1: Laravel Herd (Recommended)​

Option 2: Local by Flywheel​

Option 3: Docker​

WordPress Installation​

Download WordPress​

Configure WordPress​

Install WordPress​

Plugin Installation​

Install Required Plugins​

Install Plugin Dependencies​

Theme Installation​

Install Suma Elementor Theme​

Theme Build Process​

BigCommerce Setup​

Create Test Store​

Configure BigCommerce Plugin​

Import Sample Products​

Database Setup​

Import Database Backup​

Create Test Data​

Development Tools​

WP-CLI Aliases​

Debugging Tools​

Query Monitor​

Debug Bar​

Xdebug Configuration​

Git Workflow​

API Testing​

Test BigCommerce API​

Test SLoyalty API​

Test WordPress REST API​

Running Tests​

PHPUnit Tests​

JavaScript Tests​

Cron Jobs​

Manual Cron Execution​

Set up System Cron​

Performance Testing​

Load Testing with WP-CLI​

Frontend Performance​

Troubleshooting​

Common Issues​

Reset Development Environment​

Deployment​

Pre-Deployment Checklist​

Deploy to Staging​

Useful Commands​