WP Core Development with Local Lightning

Firstly, this is only meant as a how I do it. I’m using MacOS.

core.git.wordpress.org

It is based on using git://core.git.wordpress.org/. This would be similar to WP core development on a regular install using the WordPress Beta Tester plugin set for bleeding edge nightlies.

  • Create a new site in Local Lightning.
  • From Local Lightning Open Site Shell
  • You should cd into /app.
  • Move the wp-config.php and delete /public.
  • Then clone core.git.wordpress.org to /public.
cd ..
mv ./public/wp-config.php .
rm -rf ./public
git clone git://core.git.wordpress.org/ public

Create symlink of wp-config.php into /public

ln -sv $PWD/wp-config.php $PWD/public/wp-config.php

The following can be used to keep your clone less cluttered. Add ./app/public/.gitignore with the following data.

.gitignore
wp-config\.php
wp-tests-config\.php
debug\.log
local-phpinfo\.php
/wp-content/plugins/*
/wp-content/upgrade/*
/wp-content/db\.php

Add the above from my gist to the /app directory with the following command.

curl -o ./public/.gitignore https://gist.githubusercontent.com/afragen/43dfff563e942353d866c81904498cb2/raw/.gitignore

Add setup-phpunit.sh script for testing.

curl -o setup-phpunit.sh https://raw.githubusercontent.com/afragen/setup-phpunit/master/setup-phpunit.sh

I’ve written a script to aid in applying patches or changesets from core.trac.wordpress.org. It is added to the commands as well.

curl -o apply-trac-patch.sh https://gist.githubusercontent.com/afragen/977d765414189d5f5fae42215fe92a27/raw/apply-trac-patch.sh

Run setup-phpunit.sh script.

Update trunk via git pull from /app/public using Open Site Shell

Below are the list of sequential commands after Open Site Shell

cd ..
mv ./public/wp-config.php .
rm -rf ./public
git clone git://core.git.wordpress.org/ public
ln -sv $PWD/wp-config.php $PWD/public/wp-config.php
curl -o ./public/.gitignore https://gist.githubusercontent.com/afragen/43dfff563e942353d866c81904498cb2/raw/.gitignore
curl -o setup-phpunit.sh https://raw.githubusercontent.com/afragen/setup-phpunit/master/setup-phpunit.sh
curl -o apply-trac-patch.sh https://gist.githubusercontent.com/afragen/977d765414189d5f5fae42215fe92a27/raw/apply-trac-patch.sh
bash setup-phpunit.sh
cd public/

Someway to automate this setup in a one-click install or an advanced setting on the install would be tremendous. see https://localbyflywheel.com/community/t/feature-request-add-simple-install-of-a-wp-core-dev-environment/12985/3

develop.git.wordpress.org

A separate one-click install using git://develop.git.wordpress.org/ would also be great but that would also likely require installing npm and setting the database to display /build as the home URL endpoint.

As above you will need to create a new site in Local Lightning and then Open Site Shell from Local Lightning.

To make this function, before running the commands you must ensure that your local environment has wget and npm installed. If you’re on a Mac I highly recommend using Homebrew and brew install wget. Installing npm using Homebrew can be done but isn’t necessarily the recommended method.

I have to give lots of credit to Sal Ferrarello for his post WordPress Core Development on Local by Flywheel and to Kees Meijer for his script setup-phpunit.sh

I had to modify the setup-phpunit.sh script to work with Local Lightning. It is heavily biased towards using MacOS. I’m hoping I can get a little help making it more universal. My version is on GitHub

Here’s the sequential commands I’ve adapted from Sal’s post to use the git://develop.git.wordpress.org repository.

cd ..
mv ./public/wp-config.php .
rm -rf ./public
git clone git://develop.git.wordpress.org/ public
ln -sv $PWD/wp-config.php $PWD/public/wp-config.php
svn co https://plugins.svn.wordpress.org/wordpress-importer/trunk/ public/tests/phpunit/data/plugins/wordpress-importer
curl -o setup-phpunit.sh https://raw.githubusercontent.com/afragen/setup-phpunit/master/setup-phpunit.sh
curl -o apply-trac-patch.sh https://gist.githubusercontent.com/afragen/977d765414189d5f5fae42215fe92a27/raw/apply-trac-patch.sh
bash setup-phpunit.sh
cd public/
siteurl="$(wp option get siteurl | sed -e 's#/build##')";wp option update siteurl "$siteurl/build"
home="$(wp option get home | sed -e 's#/build##')";wp option update home "$home/build"
npm install && npm run build

The preceding bases your WordPress installation on develop.git.wordpess.org. You will open your site from a URL similar to mylocalsite.local/build/ and the dashboard is mylocalsite.local/build/wp-admin/.

One-click Install

For a one-click install you can use the following commands.

# Setup environment from core.git.wordpress.org
sh -c "$(curl -fsSL https://gist.github.com/afragen/e1aa3ffccf1a73618ee6e756bd95d297/raw/core-git-wp.sh)";cd .

# Setup environment from develop.git.wordpress.org
sh -c "$(curl -fsSL https://gist.github.com/afragen/e1aa3ffccf1a73618ee6e756bd95d297/raw/develop-git-wp.sh)";cd .

Translations Updater and Easy Digital Downloads

My Translations Updater Composer library also works for any plugins or themes that are using EDD Software Licensing. I have recently written about the basic purpose and function of the Translations Updater library.

EDD Software Licensing Integration

As of EDD Software Licensing v3.6, there are a couple of action hooks in the plugin/theme updater samples that allow for this integration. As part of the setup for using EDD SL, you need to create a new EDD SL updater class with a configuration array customized to your plugin.

This array is contains data regarding the specific plugin or theme that uses EDD Software Licensing. Integration with the Translations Updater library only requires the addition of 2 elements to the configuration array and a slightly different command that runs the translations updater.

The additional array elements are a designation to where the translations repository is hosted, GitHub, Bitbucket, GitLab, or Gitea, and the URI to the repository.

‘git’ => ‘bitbucket’,
‘languages’ => ‘https://bitbucket.org/afragen/test-language-pack,

Specific instructions are in the GitHub repository.

Translations Updater

As part of the GitHub Updater I introduced a process for independent language pack updating. The normal process is to include translation files, as part of your plugins, in a /languages directory inside of your plugin and load them via load_plugin_textdomain(). This also works for themes.

Decoupled Language Packs

If your plugin is in the dot org plugin directory you benefit from translations that are done by the community on GlotPress. If your particular WordPress installation is localized and the plugin has a translation file for that locale, the translation file will be automatically added and none of the other unused translation files will be added.

These translations take precedence over those included in your plugin as of WordPress 4.6. If there are updates for the translation file, they will be added via the normal dashboard update process.

This allows for a decoupled language pack updating experience where the plugin doesn’t need to include additional files that can contribute significantly to the overall plugin size; but can benefit from maintaining the translations independently from the main plugin.

Get Your Own Decoupled Language Packs

The language pack updating method I created in GitHub Updater works in the same manner as in the dot org plugin directory. The developer maintains a separate repository that contains the language packs and the Translations Updater code independently installs the needed translation files. This allows for a more efficient method of distribution of language packs and allows the main plugin and translations to be developed and maintained separately.

composer require

Recently I have converted the Translations Updater to a Composer library. In this way it can be installed in any plugin or theme via composer require afragen/translations-updater:dev-master and decoupled language pack updating can be used. This does require a separate, public repository that contains the translations files.

I have created a Language Pack Maker library that will create the language packs from a folder of translation MO/PO files and create a language-pack.json file that contains the data regarding the current state of all the language packs.

Real World Example

I maintain the translations for GitHub Updater using this method. What I do is maintain the public repository of translations and take PRs for updated or new translations. These PRs are only for the MO/PO files. I would then update the repository locally where I would run the Language Pack Maker and then push the new language packs and language-pack.json to the public repository.

As always, ask questions. I’m happy to explain in more detail as needed.

Install a Zipfile with GitHub Updater

If you maintain your codebase on GitHub, or another git host, the standard download of your repository from within GitHub is an automatically generated zipfile created from your repository. GitHub Updater uses this generated zipfile when it updates or installs a repository from GitHub.

Build Processes

Sometimes your project may require build tools such as Grunt, Gulp, Webpack, or some other process. The built project is usually added as a release asset to your release. GitHub Updater is capable of updating using this release asset.

PHP Fatal

Recently a problem and discussion arose about installing a plugin via either GitHub Updater’s Remote Install function or as a download of a GitHub repository. Obviously if the plugin requires a build process to be functional a PHP fatal error is likely to occur as some files will only exist after the completion of the build process.

Solution

I created a solution where a Zipfile was merely one more type of git host for Remote Installation using GitHub Updater. You may either drop a local file path into the Plugin URI field or insert the URI to the remote zipfile.

Zipfile install
Install from a Zipfile or URI of Zipfile

I was actually pleasantly surprised at how easy it was to add this functionality.

WordPress Debugging

It is inevitable. At some point when running a WordPress site you will have a conflict, an error, or worst case – a PHP Fatal leading to a WSOD (White Screen of Death).

My goal is to provide the means with which you should be able to view and hopefully understand, to some degree, the errors so that the most appropriate person can provide a solution.

Why is it Inevitable?

By virtue of the shear number of different WordPress plugins, themes, and PHP versions, there are bound to be interactions that cause issues. Hopefully these issues don’t bring down your site. But some will.

Types of Errors

There are a few basic types of errors common to WordPress sites. Primarily all are PHP errors. There are 3 primary types of PHP errors: PHP Fatal, PHP Warning, and PHP Notice.

Under most circumstances you might not even be aware of either the PHP Warning or PHP Notice errors as they commonly only display in your PHP error log. A PHP Fatal error is the most common cause of the WSOD, but again you won’t see the actual error outside of an error log.

By default WordPress doesn’t display these errors to the user. You can adjust certain settings within wp-config.php to bring these errors to display and/or log them to a WordPress specific debug.log.

For many, modifying the wp-config.php file is a daunting task that in and of itself, can bring your site down. I’ve tried to simplify this with the creation of my WP Debugging plugin.

My plugin will add settings to wp-config.php. More specifically setting WP_DEBUG to true and setting WP_DEBUG_LOG to true. There are a number of additional settings that can also set to assist in debugging.

xDebug Isn’t the Only Way

Tom McFarlin has written extensively about coding and debugging.

In this member’s only post, Tom explains many of the individual settings that can assist in debugging a WordPress site using only native WordPress functions. These constants are also described in Debugging in WordPress.

Automate All the Things

WP Debugging is a plugin I wrote to automatically add many of WordPress’ built-in settings on plugin activation and remove them on plugin deactivation. The plugin uses the WP-CLI command to add and remove constants from the wp-config.php file. WP Debugging should be available in the Plugins Repository soon.

There are two optional plugin dependencies that request to be installed, Query Monitor by John Billion and Debug Bar. The notice for these dismisses for 45 days.

Query Monitor is an established development plugin that provides a wealth of information for debugging. Debug Bar is another excellent development plugin by Automattic.

Debug Quick Look by Andrew Norcross is a wonderful plugin whose sole function is to display the debug.log that WordPress writes debugging errors to when WP_DEBUG_LOG is set to true. I have included a modified version of this plugin.

Looking in the Logs

Viewing the debug.log will allow you to gain insight into the cause of the error. Often these errors will provide a stack trace pointing to exactly the file, function, or line of the error. They will definitely aid the developer.

Debugging is a art. One that you will only gain proficiency in through practice. It is my goal to help bring this information closer to you as simply as possible via the WP Debugging plugin.

You can read more about the specifics of what the WP Debugging plugin does on GitHub and, as always, PRs are happily considered on the develop branch.