Development Setup

Local environment configuration, build tools, debugging, and deployment workflow for StealthCam development.

Overview

StealthCam uses modern development tools and workflows for efficient local development, testing, and deployment.

Local Environment Options

Option 1: Laravel Herd (Recommended)

Platform: Laravel Herd for Windows/macOS
Version: Latest
Website: https://herd.laravel.com/

Why Herd?

Zero Configuration - PHP, Nginx, MySQL, Redis pre-configured
Automatic HTTPS - Secure local URLs out of the box
Fast - Native PHP binaries, no Docker overhead
Integrated Tools - Composer, Node.js, MySQL admin
Multiple PHP Versions - Switch between PHP 7.4, 8.0, 8.1, 8.2, 8.3
Database GUI - Built-in TablePlus-like interface

Installation

Download Herd:
- Visit https://herd.laravel.com/
- Download for your OS
- Install and launch
Configure Herd:
- Open Herd preferences
- Set PHP version: 8.0 or 8.1
- Enable Redis
- Set parked directory: Z:\Repos\ or ~/Sites/
Park StealthCam Directory:
```
cd Z:\Repos\stealthcam
herd park
```
Access Site:
- URL: https://stealthcam.test
- Herd automatically detects WordPress and configures Nginx

PHP Configuration

Location: Herd → Preferences → PHP

Recommended Settings:

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

Database Management

Built-in GUI: Herd → Preferences → Database

Credentials:

Host: 127.0.0.1
Port: 3306
User: root
Password: (empty)

Command Line:

herd mysql

Option 2: Local by Flywheel

Platform: Local by Flywheel
Version: Latest
Website: https://localwp.com/

Why Local by Flywheel?

WordPress-Specific - Built for WordPress development
One-Click Setup - Automated WordPress installation
WP-CLI Integration - Run WP-CLI commands easily
Live Link - Share local site via public URL
Blueprints - Save and reuse site configurations

Installation

Download Local:
- Visit https://localwp.com/
- Download and install
Create New Site:
- Click "Create a new site"
- Site name: StealthCam
- Environment: Preferred (Nginx, latest PHP, MySQL)
- WordPress setup: Choose version, admin user, password
Configure Site:
- PHP version: 8.0 or 8.1
- Web server: Nginx
- MySQL: 8.0
Import Existing Site (if migrating):
- Tools → Import
- Select database backup .sql
- Select wp-content folder

Database Management

Adminer: Built-in at /adminer.php

Credentials: Shown in Local app

Command Line:

local-cli db

Database Setup

Import Production Database

Preparation:

Export production database (via cPanel, phpMyAdmin, or WP-CLI)
Download backup .sql file
(Optional) Search-replace URLs using Better Search Replace plugin or WP-CLI

Using WP-CLI

# Import database
wp db import /path/to/backup.sql

# Search-replace production URL with local URL
wp search-replace 'https://stealthcam.com' 'https://stealthcam.test' --all-tables

# Search-replace BigCommerce API URLs (if needed)
wp search-replace 'https://api.bigcommerce.com/stores/HASH' 'https://api.bigcommerce.com/stores/LOCAL_HASH' --all-tables

Using phpMyAdmin/Adminer

Navigate to phpMyAdmin/Adminer
Select database
Go to Import tab
Choose .sql file
Execute import
Run search-replace queries:

-- Update site URL
UPDATE wp_options SET option_value = 'https://stealthcam.test' WHERE option_name IN ('siteurl', 'home');

-- Update post content URLs (if needed)
UPDATE wp_posts SET post_content = REPLACE(post_content, 'https://stealthcam.com', 'https://stealthcam.test');

Create Clean Database

If starting fresh:

# Using WP-CLI
wp db create
wp core install --url=https://stealthcam.test --title="StealthCam Local" --admin_user=admin [email protected]

Repository Setup

Clone Repository

# Clone from GitHub/GitLab/Bitbucket
git clone [email protected]:rhino-group/stealthcam.git Z:\Repos\stealthcam
cd Z:\Repos\stealthcam

Install Dependencies

Composer (PHP Dependencies)

# Install Composer packages (if any root composer.json exists)
composer install

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

# Install plugin dependencies
cd wp-content/plugins/suma-dealer-locator
composer install

npm (JavaScript Dependencies)

# Install theme npm packages
cd wp-content/themes/suma-elementor
npm install

Build Tools

Theme Build System

Location: wp-content/themes/suma-elementor/

Build Tool: Laravel Mix v6.0.39

Available Commands

# Development mode - compile without minification
npm run dev

# Watch mode - recompile on file changes
npm run watch

# Hot reload - BrowserSync with live reload
npm run hot

# Production build - minified, optimized
npm run production

Development Workflow

# Start watch mode
npm run watch

# Edit files in assets/src/
# - SCSS files: assets/src/scss/
# - JS files: assets/src/js/
# - Preact components: assets/src/preact/

# Compiled files output to assets/dist/
# - CSS: assets/dist/css/app.css
# - JS: assets/dist/js/app.js
# - Preact: assets/dist/js/preact.js

Hot Module Replacement (HMR)

# Start BrowserSync with HMR
npm run hot

BrowserSync URL: http://localhost:3000

Configuration (webpack.mix.js):

mix.browserSync({
    proxy: 'stealthcam.test', // Your local site URL
    files: [
        'assets/dist/**/*',
        '**/*.php'
    ],
    notify: false
});

Production Build

Before deploying to staging/production:

npm run production

Changes:

Minifies CSS and JavaScript
Removes console logs
Generates versioned filenames
Optimizes images

WordPress Configuration

wp-config.php (Local)

Location: wp-config.php

Local Configuration:

<?php
/**
 * Local Development Configuration
 */

// Database
define('DB_NAME', 'stealthcam');
define('DB_USER', 'root');
define('DB_PASSWORD', ''); // Empty for Herd/Local
define('DB_HOST', 'localhost');
define('DB_CHARSET', 'utf8mb4');
define('DB_COLLATE', '');

// URLs
define('WP_HOME', 'https://stealthcam.test');
define('WP_SITEURL', 'https://stealthcam.test');

// Debug Mode
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true); // Logs to wp-content/debug.log
define('WP_DEBUG_DISPLAY', true); // Show errors on screen
define('SCRIPT_DEBUG', true); // Use unminified scripts
define('SAVEQUERIES', true); // Log database queries

// BigCommerce API (Local credentials)
define('BIGCOMMERCE_CLIENT_ID', 'local_client_id');
define('BIGCOMMERCE_CLIENT_SECRET', 'local_client_secret');
define('BIGCOMMERCE_ACCESS_TOKEN', 'local_access_token');
define('BIGCOMMERCE_STORE_URL', 'https://store-local-hash.mybigcommerce.com');
define('BIGCOMMERCE_CHANNEL_ID', '12345'); // Test channel

// Klaviyo API (Test account or disabled)
define('KLAVIYO_API_KEY', ''); // Leave empty to disable

// Algolia (Local index)
define('ALGOLIA_APPLICATION_ID', 'local_app_id');
define('ALGOLIA_SEARCH_API_KEY', 'local_search_key');
define('ALGOLIA_ADMIN_API_KEY', 'local_admin_key');

// Google Maps API (Dev key)
define('SUMA_DEALER_LOCATOR_GOOGLE_API_KEY', 'dev_google_maps_key');

// Disable caching
define('WP_CACHE', false);

// Disable auto-updates
define('AUTOMATIC_UPDATER_DISABLED', true);

// Security keys (generate at https://api.wordpress.org/secret-key/1.1/salt/)
define('AUTH_KEY', '...');
define('SECURE_AUTH_KEY', '...');
// ... etc.

// Table prefix
$table_prefix = 'wp_';

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

require_once ABSPATH . 'wp-settings.php';

Environment-Specific Config

Using wp-config-local.php:

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

wp-config-local.php (gitignored):

<?php
// Local overrides
define('WP_DEBUG', true);
define('BIGCOMMERCE_CLIENT_ID', 'local_id');
// etc.

Debugging

WordPress Debug Log

Enabled via: WP_DEBUG_LOG = true in wp-config.php

Log File: wp-content/debug.log

Viewing:

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

# On Windows (PowerShell)
Get-Content wp-content/debug.log -Wait -Tail 50

Writing to Log:

error_log('Debug message: ' . print_r($variable, true));

Query Monitor Plugin

Plugin: Query Monitor
Install: wp plugin install query-monitor --activate

Features:

Database query analysis
Hook and action inspection
HTTP request logging
PHP error tracking
Performance profiling

Access: Toolbar → Query Monitor

Browser DevTools

Chrome/Edge DevTools:

Network Tab: Inspect AJAX requests, API calls
Console: JavaScript errors, console.log output
Performance Tab: Page load profiling
Application Tab: Cookies, localStorage, sessionStorage

BigCommerce API Debugging

Log API Requests:

add_filter('bigcommerce/api/request', function($request) {
    error_log('BC API Request: ' . print_r($request, true));
    return $request;
});

add_filter('bigcommerce/api/response', function($response) {
    error_log('BC API Response: ' . print_r($response, true));
    return $response;
});

Klaviyo Event Debugging

Console Logging:

// Track Klaviyo events in console
_learnq.push(['onEventSent', function(event, data) {
    console.log('Klaviyo Event:', event, data);
}]);

Testing

Browser Testing

Recommended Browsers:

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
Mobile: iOS Safari, Chrome Android

Responsive Testing:

Chrome DevTools Device Toolbar
BrowserStack (cross-browser testing)
Physical devices (iPhone, Android)

Automated Testing

PHPUnit (Plugin Testing)

Installation:

composer require --dev phpunit/phpunit

Run Tests:

vendor/bin/phpunit

JavaScript Testing (Jest)

Installation:

npm install --save-dev jest @testing-library/react @testing-library/preact

Run Tests:

npm test

Code Quality

PHP Code Sniffer

Install:

composer require --dev squizlabs/php_codesniffer
composer require --dev wp-coding-standards/wpcs

Configure (.phpcs.xml):

<?xml version="1.0"?>
<ruleset name="StealthCam">
    <description>WordPress Coding Standards</description>
    
    <rule ref="WordPress-Core"/>
    <rule ref="WordPress-Docs"/>
    <rule ref="WordPress-Extra"/>
    
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*/node_modules/*</exclude-pattern>
</ruleset>

Run:

vendor/bin/phpcs wp-content/themes/suma-elementor/
vendor/bin/phpcbf wp-content/themes/suma-elementor/ # Auto-fix

ESLint (JavaScript)

Install:

npm install --save-dev eslint eslint-plugin-react

Configure (.eslintrc.js):

module.exports = {
    extends: ['eslint:recommended', 'plugin:react/recommended'],
    parserOptions: {
        ecmaVersion: 2020,
        sourceType: 'module',
        ecmaFeatures: {
            jsx: true
        }
    },
    env: {
        browser: true,
        node: true,
        es6: true
    },
    rules: {
        'no-console': 'warn',
        'no-unused-vars': 'warn'
    }
};

Run:

npm run lint

Add to package.json:

{
  "scripts": {
    "lint": "eslint assets/src/js --ext .js,.jsx"
  }
}

Stylelint (SCSS)

Install:

npm install --save-dev stylelint stylelint-config-standard-scss

Configure (.stylelintrc.json):

{
  "extends": "stylelint-config-standard-scss",
  "rules": {
    "indentation": 4,
    "color-hex-case": "lower",
    "color-hex-length": "short"
  }
}

Run:

npx stylelint "assets/src/scss/**/*.scss"

Version Control

Git Workflow

Branching Strategy: Gitflow

Main Branches:

main - Production-ready code
develop - Integration branch for features
staging - Staging environment (optional)

Supporting Branches:

feature/* - New features
bugfix/* - Bug fixes
hotfix/* - Urgent production fixes

Feature Development

# Start new feature
git checkout develop
git pull origin develop
git checkout -b feature/product-comparison-widget

# Make changes, commit frequently
git add .
git commit -m "feat: add product comparison widget"

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

# Create pull request (GitHub/GitLab/Bitbucket)
# After review and approval, merge to develop

Commit Message Format

Convention: Conventional Commits

Format: <type>(<scope>): <subject>

Types:

feat - New feature
fix - Bug fix
docs - Documentation changes
style - Code formatting (no logic change)
refactor - Code restructuring
test - Adding tests
chore - Build process, dependencies

Examples:

feat(widgets): add product comparison widget
fix(cart): resolve add to cart AJAX error
docs(readme): update installation instructions
style(scss): format product card styles
refactor(utils): extract helper functions

.gitignore

File: .gitignore

# WordPress
wp-config-local.php
wp-content/uploads/
wp-content/cache/
wp-content/backup-db/
wp-content/advanced-cache.php
wp-content/wp-cache-config.php
wp-content/object-cache.php
wp-content/debug.log

# Theme builds
wp-content/themes/*/assets/dist/
wp-content/themes/*/node_modules/
wp-content/themes/*/vendor/

# Plugin builds
wp-content/plugins/*/node_modules/
wp-content/plugins/*/vendor/

# Dependencies
node_modules/
vendor/

# OS files
.DS_Store
Thumbs.db
desktop.ini

# IDE
.vscode/
.idea/
*.sublime-project
*.sublime-workspace

# Environment files
.env
.env.local

Deployment

Manual Deployment (FTP/SFTP)

Tools: FileZilla, Cyberduck, WinSCP

Process:

Build production assets: npm run production
Connect to server via SFTP
Upload changed files:
- wp-content/themes/suma-elementor/
- wp-content/plugins/*/ (custom plugins)
- Exclude node_modules/, vendor/ (regenerate on server)
Run composer install on server (if needed)
Clear cache (WP Rocket, object cache)

Automated Deployment (CI/CD)

GitHub Actions Example

File: .github/workflows/deploy.yml

name: Deploy to Production

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      
      - name: Install dependencies
        run: |
          cd wp-content/themes/suma-elementor
          npm ci
      
      - name: Build production assets
        run: |
          cd wp-content/themes/suma-elementor
          npm run production
      
      - name: Deploy via FTP
        uses: SamKirkland/FTP-Deploy-[email protected]
        with:
          server: ${{ secrets.FTP_SERVER }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          local-dir: ./
          server-dir: /public_html/
          exclude: |
            **/.git*
            **/.git*/**
            **/node_modules/**
            **/vendor/**
      
      - name: Clear cache
        run: |
          curl -X POST https://stealthcam.com/wp-json/wp-rocket/v1/purge/cache \
            -H "Authorization: Bearer ${{ secrets.WP_API_TOKEN }}"

Database Migration

Using WP Migrate DB Pro (plugin):

Install WP Migrate DB Pro on local and production
Configure push/pull between environments
Select tables to migrate
Handle search-replace automatically
Run migration

Manual Process:

Export database from staging/production
Import to local (see Database Setup above)
Run search-replace for URLs

Performance Testing

Local Performance Profiling

Query Monitor: Analyze slow queries, hook execution times

New Relic (if configured): Full application performance monitoring

Xdebug + Profiler:

; php.ini / xdebug.ini
xdebug.mode=profile
xdebug.output_dir=/tmp/xdebug
xdebug.profiler_enable_trigger=1

Analyze with: Webgrind, QCacheGrind

Load Testing

Tools: Apache Bench, K6, Loader.io

Example (Apache Bench):

# 1000 requests, 10 concurrent
ab -n 1000 -c 10 https://stealthcam.test/

Troubleshooting

Common Issues

"White Screen of Death" (WSOD)

Causes: PHP error, plugin conflict, memory limit

Solutions:

Check wp-content/debug.log
Disable all plugins: wp plugin deactivate --all
Enable plugins one by one to identify conflict
Increase memory limit in wp-config.php: define('WP_MEMORY_LIMIT', '512M');

BigCommerce Products Not Syncing

Troubleshooting:

Check BigCommerce API credentials in Settings → BigCommerce
Test API connection: Settings → BigCommerce → Test Connection
Check webhook configuration in BigCommerce admin
Manually trigger import: Settings → BigCommerce → Import Products
Check debug log for API errors

AJAX Errors (Add to Cart, Filters)

Troubleshooting:

Open browser DevTools → Network tab
Reproduce error, inspect failed request
Check response body for error message
Verify AJAX URL is correct: ajaxurl variable
Check nonce validation

Asset Changes Not Reflecting

Solutions:

Hard refresh browser: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
Clear WP Rocket cache
Rebuild assets: npm run dev or npm run production
Check asset versioning in webpack.mix.js
Disable browser cache in DevTools (Network tab → Disable cache)

Composer/npm Install Fails

Solutions:

Delete composer.lock / package-lock.json
Delete vendor/ / node_modules/
Re-run composer install / npm install
Check PHP/Node version compatibility
Increase PHP memory limit for Composer: php -d memory_limit=-1 composer install

Development Checklist

Before Starting Work

Pull latest code from develop branch
Update database from staging (if needed)
Run composer install and npm install
Start watch mode: npm run watch
Verify local site loads correctly

During Development

Commit changes frequently with descriptive messages
Test changes in multiple browsers
Check responsive design (mobile, tablet, desktop)
Verify no JavaScript console errors
Check WordPress debug log for PHP errors
Validate HTML/CSS (W3C validators)

Before Committing

Run linters: npm run lint, vendor/bin/phpcs
Build production assets: npm run production
Test add to cart, checkout flow
Verify FacetWP filters work
Test search functionality
Check page load performance (PageSpeed Insights)

Before Deploying

Merge feature branch to develop
Test on staging environment
Run full regression testing
Get stakeholder approval
Create backup of production site
Deploy during low-traffic window
Clear all caches after deployment
Verify critical functionality (cart, checkout)
Monitor error logs for 24 hours

Additional Resources

WordPress Documentation: https://developer.wordpress.org/
BigCommerce Developer Docs: https://developer.bigcommerce.com/
Elementor Developer Docs: https://developers.elementor.com/
FacetWP Documentation: https://facetwp.com/documentation/
Algolia Developer Docs: https://www.algolia.com/doc/
Laravel Mix Docs: https://laravel-mix.com/docs/
Preact Documentation: https://preactjs.com/

Support & Contacts

Internal Development Team: [email protected]
BigCommerce Support: https://support.bigcommerce.com/
Hosting Provider: [Hosting company contact info]
Emergency Hotline: [Emergency contact number]

Overview​

Local Environment Options​

Option 1: Laravel Herd (Recommended)​

Why Herd?​

Installation​

PHP Configuration​

Database Management​

Option 2: Local by Flywheel​

Why Local by Flywheel?​

Installation​

Database Management​

Database Setup​

Import Production Database​

Using WP-CLI​

Using phpMyAdmin/Adminer​

Create Clean Database​

Repository Setup​

Clone Repository​

Install Dependencies​

Composer (PHP Dependencies)​

npm (JavaScript Dependencies)​

Build Tools​

Theme Build System​

Available Commands​

Development Workflow​

Hot Module Replacement (HMR)​

Production Build​

WordPress Configuration​

wp-config.php (Local)​

Environment-Specific Config​

Debugging​

WordPress Debug Log​

Query Monitor Plugin​

Browser DevTools​

BigCommerce API Debugging​

Klaviyo Event Debugging​

Testing​

Browser Testing​

Automated Testing​

PHPUnit (Plugin Testing)​

JavaScript Testing (Jest)​

Code Quality​

PHP Code Sniffer​

ESLint (JavaScript)​

Stylelint (SCSS)​

Version Control​

Git Workflow​

Feature Development​

Commit Message Format​

.gitignore​

Deployment​

Manual Deployment (FTP/SFTP)​

Automated Deployment (CI/CD)​

GitHub Actions Example​

Database Migration​

Performance Testing​

Local Performance Profiling​

Load Testing​

Troubleshooting​

Common Issues​

"White Screen of Death" (WSOD)​

BigCommerce Products Not Syncing​

AJAX Errors (Add to Cart, Filters)​

Asset Changes Not Reflecting​

Composer/npm Install Fails​

Development Checklist​

Before Starting Work​

During Development​

Before Committing​

Before Deploying​

Additional Resources​

Support & Contacts​

Overview

Local Environment Options

Option 1: Laravel Herd (Recommended)

Why Herd?

Installation

PHP Configuration

Database Management

Option 2: Local by Flywheel

Why Local by Flywheel?

Installation

Database Management

Database Setup

Import Production Database

Using WP-CLI

Using phpMyAdmin/Adminer

Create Clean Database

Repository Setup

Clone Repository

Install Dependencies

Composer (PHP Dependencies)

npm (JavaScript Dependencies)

Build Tools

Theme Build System

Available Commands

Development Workflow

Hot Module Replacement (HMR)

Production Build

WordPress Configuration

wp-config.php (Local)

Environment-Specific Config

Debugging

WordPress Debug Log

Query Monitor Plugin

Browser DevTools

BigCommerce API Debugging

Klaviyo Event Debugging

Testing

Browser Testing

Automated Testing

PHPUnit (Plugin Testing)

JavaScript Testing (Jest)

Code Quality

PHP Code Sniffer

ESLint (JavaScript)

Stylelint (SCSS)

Version Control

Git Workflow

Feature Development

Commit Message Format

.gitignore

Deployment

Manual Deployment (FTP/SFTP)

Automated Deployment (CI/CD)

GitHub Actions Example

Database Migration

Performance Testing

Local Performance Profiling

Load Testing

Troubleshooting

Common Issues

"White Screen of Death" (WSOD)

BigCommerce Products Not Syncing

AJAX Errors (Add to Cart, Filters)

Asset Changes Not Reflecting

Composer/npm Install Fails

Development Checklist

Before Starting Work

During Development

Before Committing

Before Deploying

Additional Resources

Support & Contacts