Setting Up a Local WordPress Development Environment with GitHub Integration

Setting up a local WordPress development environment is essential for any developer who wants to test changes without affecting the live site. By integrating GitHub repositories for your theme and plugin(s), you can easily manage version control and collaborate with others.

This guide will walk you through setting up a local WordPress instance, syncing with a remote site, and linking your GitHub repositories.

Prerequisites

Before we begin, ensure you have the following installed:
– MAMP (for managing your local server)
– Visual Studio Code (or any code editor)
– Git (for version control)
– SSH access to your remote server

Step 1: Syncing Your Remote Staging Site

First, we need to download the remote site files to your local machine. Open your terminal and run the following command:

rsync -avz -e "ssh -p 2222" --exclude 'some-folder-or-file' user@ip/path/to/install/ /path/to/local

This command uses rsync to synchronize your remote site with your local directory. Replace user, ip, and paths with your actual details.
Note that the --exclude 'some-folder-or-file' option can be repeated as many times as you need.

Step 2: Dumping and Importing the Database

Next, dump a copy of the database from your remote server.

First, ssh into the remote server, then run this command:

mysqldump -u {DB_USER} -p {DB_NAME} > /path/to/target-file.sql

Replace {DB_NAME}, {DB_NAME}, and paths with your actual details.

Transfer the SQL file to your local machine using rsync again:

rsync -avz -e "ssh -p 2222" user@ip/path/to/target-file.sql /path/to/local

Import the database into your local MAMP instance:

cd /Applications/MAMP/Library/bin
./mysql -u user -p databasename < /path/to/local/target-file.sql

Ensure to replace user, databasename, and paths with your actual details.

Step 3: Configuring wp-config.php

Update your local wp-config.php to point to the new database:

define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASSWORD', 'your_database_password');
define('DB_HOST', 'localhost');

Set the home and site URLs to your local development URL:

define('WP_HOME', 'https://local.tld/');
define('WP_SITEURL', 'https://local.tld/');

Replace local.tld with your local development URL.

Step 4: Cleaning Up

Remove any existing user.ini and clear the contents of .htaccess if they exist to avoid conflicts.
WordPress will regenerate the contents of the .htaccess as required, as soon you visit the Settings > Permalinks and re-save those options once.

Step 5: Linking GitHub Repositories

Delete the existing theme and your custom plugin from your local WordPress installation. Then, create symbolic links to your local GitHub repositories:

ln -s /path/to/local-github-repo/theme-name /path/to/local/wp-content/themes/theme-name
ln -s /path/to/local-github-repo/plugin-name /path/to/local/wp-content/plugins/plugin-name

Replace paths and names with your actual GitHub repository paths and theme/plugin names.

Careful, a symlink works both ways. If you want a true one-way synchronization from your GitHub Folder to the WordPress Plugin or Theme folder, you can set up a Background Task Shell script.
This is an example for MacOS:

#!/bin/bash

FSWATCH_PATH="/opt/homebrew/bin/fswatch"

# Source and target directories
SOURCE_THEME_DIR="/Users/{username}/path-to-your-github-repo-folder"
TARGET_THEME_DIR="/Users/{username}/path-to-your-mamp-themename-folder"

SOURCE_PLUGIN_DIR="/Users/{username}/path-to-your-github-repo-folder"
TARGET_PLUGIN_DIR="/Users/{username}/path-to-your-mamp-pluginname-folder"

# Function to sync files
sync_files() {
    rsync -av --delete --exclude '.*' "$1/" "$2/"
}

# Initial sync
sync_files "$SOURCE_THEME_DIR" "$TARGET_THEME_DIR"
sync_files "$SOURCE_PLUGIN_DIR" "$TARGET_PLUGIN_DIR"

# Watch for changes and sync
"$FSWATCH_PATH" -o "$SOURCE_THEME_DIR" "$SOURCE_PLUGIN_DIR" | while read f; do
    sync_files "$SOURCE_THEME_DIR" "$TARGET_THEME_DIR"
    sync_files "$SOURCE_PLUGIN_DIR" "$TARGET_PLUGIN_DIR"
done &

# Keep the script running
while true; do
    sleep 60
done

Add this script to your backgrounds tasks on MacOS:
nano ~/Library/LaunchAgents/com.{username}.{script-name}.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.{username}.{script-name}</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/{username/path-to-your-shell-script/{script-name}.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Step 6: Optional – Connecting to Remote SQL

While it’s not recommended for security reasons, you can connect directly to your remote SQL server by updating DB_HOST in your wp-config.php:

define('DB_HOST', 'remote_ip_or_hostname:port');

Ensure you have the necessary permissions and understand the security implications before doing this. Usually remote mySQL databases do not allow remote connections, and if enabled, they should only be enabled for a given list of allowed IP Addresses.

Advantages of This Setup

1. Version Control: Using GitHub repositories for your theme and plugin ensures you have full version control and can collaborate with others easily.
2. Local Testing: Test changes locally before deploying to the live site or merging changes to the remote repository, reducing the risk of breaking your site, or simply ensuring what you commit and merge actually works 😉
3. Efficiency: Quickly sync changes between your local environment and GitHub, streamlining the development process.

By following these steps, you’ll have a robust local WordPress development environment linked with your GitHub repositories, allowing for efficient and safe development.

Happy coding!