Wordpress
Setting up development environment
When you want to develop a WordPress app, or you are joining an existing project, it is important to have local development ready. There are a number of solutions that can be used.
App based dev solutions
If you want to use simple solutions that only include the bare minimum (server config), you can use WAMP, MAMP, XAMPP, or Local by Flywheel.
Vagrant based dev environments
We do recommend more WordPress-friendly solutions. One such solution is Varying Vagrant Vagrants. It is a Vagrant configuration focused on WordPress development. The advantage of VVV over MAMP or XAMPP is that it comes bundled with a WordPress-ready server configuration and software packages, such as php-fpm, WP-CLI, Composer, NodeJs, and other useful packages.
The advantage of using Vagrant is that it is configured independently of your machine because it runs on a virtual machine. This way, everyone on your team will develop in the same environment.
Homestead is another such dev environment.
Docker based solutions
WP Docker is another development environment you can use.
The main difference is that Vagrant uses virtual machines to run environments independent of the host machine via VirtualBox or VMware. Each environment has its own virtual machine. Docker, on the other hand, uses 'containers' that include your application and all of its dependencies, but shares the operating system with other containers. They are isolated processes on the host operating system but are not tied to any specific infrastructure.
Vagrant is easier to set up and get up and running but can be resource-intensive (RAM and space on the disk). Docker is a bit harder to understand and set up, but it is much faster and uses less CPU and RAM than Vagrant.
Local environment on Unix based systems
You can also set your own dev server on Mac OS or any Unix based system. You'll need to set up your own PHP (FPM), database (MySQL), and a web server (Apache or Nginx). We usually use Nginx on client projects.
A web service stack based on Linux, Apache, MySQL, and PHP is known as a LAMP stack. The Nginx one is known as the LEMP stack.
If you want to use a local dev environment you can also check Laravel Valet, or Valet Plus.
Default local TLD
When setting up local projects it's important to avoid using the reserved .dev top-level domain (TLD). At NMC, we chose .test, as all our local TLD. VVV and Laravel Valet will set sites up with .test by default, in other solutions, you need to make sure to set this up yourself.
If the client project has a production URL
https://clientproject.comyour local environment should be
https://clientproject.testIn the following chapters, you'll learn how to set up various environments.
Vagrant setup
Installing VVV
Setting up VVV is easy. You can either follow the manual install instructions, as described in the official documentation, or you can use the brew package manager for quick and easy installation.
First, install VirtualBox. You can install it using Homebrew:
brew cask install virtualbox
After you install VirtualBox, install Vagrant.
brew cask install vagrant
Then you'll want to install a few Vagrant plugins.
vagrant plugin install vagrant-hostsupdaterWe recommend that you reboot your computer to avoid any networking issues.
After you install the plugins, you'll want to install VVV in the local folder.
cd ~
git clone -b stable git://github.com/Varying-Vagrant-Vagrants/VVV.git ~/vagrant-local
cd vagrant-localThis will clone the official VVV repository to your vagrant-local folder in the home folder. If you want the latest updates and features, switch to the develop branch instead of the master branch.
Before starting VVV, go to Vagrantfile and uncomment the config.vm.network :public_network line. This will enable you to debug across devices later on.
You can set up your custom sites by creating a copy of the default-config.yml file and renaming it to custom.yml. Both are located in the config folder.
While in your vagrant-local folder, type
vagrant up
This will set VVV up for the first time. This may take some time (about 10 minutes on an average network). While VVV is setting up, you can read the rest of this handbook.
What Vagrant is actually doing is downloading a packaged box with the Ubuntu virtual machine and caching it for future use. After downloading, it will provision the running script that will download other packages necessary for local development.
Once it has installed everything, you'll be all set to work on your local WordPress. You can type
http://vvv.test
in your browser, which will open a screen with some interesting links you can explore.
When you want to close Vagrant and save your RAM, type
vagrant halt
The next time you start your Vagrant with vagrant up, the cached box will start and boot in a minute or so. Re-provisioning your Vagrant is necessary when adding new folders or changing your configuration.
Making your Vagrant public-friendly
Modern web development is mobile first oriented. With that in mind, it is natural that you want to be able to see what you are developing on your mobile phone.
To do that, you need to change your Vagrantfile located in the vagrant-local folder. Search for
config.vm.network :public_network
and uncomment it. You can also enable port forwarding while you're at it:
config.vm.network "forwarded_port", guest: 80, host: 8888
Now you need to re-provision your Vagrant.
vagrant reload --provision
When you do that, you'll be asked which network interface you use to connect to the Internet.
==> default: Clearing any previously set forwarded ports...
==> default: Clearing any previously set network interfaces...
==> default: Available bridged network interfaces:
1) en0: Wi-Fi (AirPort)
2) en1: Thunderbolt 1
3) en2: Thunderbolt 2
4) bridge0
5) p2p0
6) awdl0
==> default: When choosing an interface, it is usually the one that is
==> default: being used to connect to the internet.
default: Which interface should the network bridge to?In our case, we connect via Wi-Fi, so choose 1. If you're connecting via Ethernet, you'll need to select that as your network bridge.
Adding new sites
The official documentation on adding a new site can be found here. An easier way to provision a new site is by using site templates. A site template is a Git repo that contains scripts and files necessary to set up a new VVV site.
You can also create provision scripts. First, you need to add your site to the custom.yml file.
Let's say we want to create a wordpress-nmc site. After the
wordpress-two:
skip_provisioning: false
description: "A standard WP install, useful for building plugins, testing things, etc"
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
custom:
# locale: it_IT
delete_default_plugins: true
install_plugins:
- query-monitor
hosts:
- two.wordpress.testcode in the file add
wordpress-nmc:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
vm_dir: /srv/www/nmc/wordpress-nmc
local_dir: www/nmc/wordpress-nmc
hosts:
- wordpress-nmc.testWe've told Vagrant that there should be a site it can access inside www/nmc/wordpress-nmc. So we need to create it.
Every time we add a new site to custom.yml or the provisioner files, we need to reprovision VVV. To do this, you need to run
vagrant reload --provision
After that, either import the database via phpMyAdmin or WP-CLI or start from scratch.
You can modify the provision scripts if you need a special setup.
Laravel Homestead setup
Homestead is an official, pre-packaged Vagrant box from the Laravel team. Its default approach is to have multiple sites set up on a single Vagrant instance, which makes adding new sites a trivial task. For more advanced requirements, each site can also be set up on its own instance.
Homestead runs on any Windows, Mac, or Linux system and includes the Nginx web server, PHP 7.3, PHP 7.2, PHP 7.1, MySQL, PostgreSQL, Redis, Memcached, Node, etc. For a full list of features, check out the official documentation
Installing Laravel Homestead
As any other Vagrant box, Homestead requires a few prerequisites installed:
Either one of the following: VirtualBox, VMWare1, Parallels2, or Hyper-V
1 Requires the purchase of both VMware Fusion / Workstation and the VMware Vagrant plug-in.
2 Not free but has a free trial period and requires a free Vagrant plug-in.
If you want to use one of the paid options, you can use your education budget to cover the cost. For more information, consult your team lead.
For the easiest setup, use VirtualBox — it is free, multi-platform, and regularly updated.
After everything is installed, we can begin with Homestead setup.
First, add/download the laravel/homestead box to your Vagrant installation from the terminal:
vagrant box add laravel/homesteadClone the Homestead repository into a directory that will hold all your Homestead projects:
git clone https://github.com/laravel/homestead.git ~/homesteadGo into the directory the repo was cloned into, and check out the latest stable release tag:
cd ~/homestead
# Checkout latest stable tag.
# At the time of writing v12.3.0 is latest stable version
# Check the latest version on https://github.com/laravel/homestead/releases
git checkout v12.3.0Next, run init.sh or init.bat depending on the system you are using. This will create a Homestead.yml file that will be used to configure the environment:
# Mac OSX and Linux
bash init.sh
# Windows
init.batNow that we have Homestead.yml, we can start configuring our environment.
Configuring Homestead
Open Homestead.yml in your code editor. You'll see that some parts are already filled.
Provider is the first thing that needs to be configured. This relates to the virtualization provider that was installed.
# Default value
provider: virtualbox
# Other providers
provider: vmware_fusion | vmware_workstation | parallels | hypervOne of the most important things to configure is the shared folder config. These folders will contain all files for our websites. Shared folders are defined like this:
folders:
# Local path to the directory where we cloned the Homestead repo
- map: ~/homestead
# Path to the directory from the virtual machine
to: /home/vagrant/homesteadFor multiple sites, each with its own instance:
folders:
- map: ~/homestead/project-1
to: /home/vagrant/homestead/project-1
- map: ~/homestead/project-2
to: /home/vagrant/homestead/project-2It is also important to configure sites. They are stored in one or many shared folders, and they are defined with a domain name that will map to a site folder:
sites:
# Local domain name
- map: homestead.test
# Location of the sites public folder
to: /home/vagrant/homestead/www/The site's domain name must also be mapped to the actual IP address of the Vagrant server. This is done by editing the hosts file of the local machine. You can do this manually. However, for a more automated approach, it is recommended to use the vagrant-hostsupdater plugin.
Install it by running vagrant plugin install vagrant-hostsupdater inside the terminal while in the /homestead directory. Homestead already has a config for the vagrant-hostsupdater plugin and should map all site's domains to the Vagrant's IP address. The IP address is by default defined in Homestead.yml, but you can change it to some other address.
Note for Windows users: You'll need to change permissions on the hosts file to give the current user write access to that file.
The last thing in the basic configuration is database property. With this, we define all databases that will be created on server startup or reprovision.
databases:
- homestead
- wordpressAnother thing to note is that the default Homestead database name is homestead, and the password is secret.
Using Homestead
When we are done with the Homestead configuration, we can start the server with the vagrant up command, stop the server with vagrant halt, and restart it with vagrant reload. If something is changed in Homestead.yml, the configuration server will need to be reprovisioned so that all changes in the configuration are visible on our sites. Use vagrant reload --provision to reprovision a server.
Now you have everything you need to run your WordPress site. Download the instance of WordPress in your preferred way and set it up in wp-config.php. To finish the installation, go to your local site URL (e.g., wordpress.test).
Extra features
Accessing Vagrant from inside
Sometimes, you'll need to change some things inside the virtual machine, e.g. access your MySQL database, edit the php.ini file, or run some WP CLI functions. To access it, type vagrant ssh, and you are in. Since the server and database are inside the virtual machine, this is the only way to access them.
You will be positioned in the /home directory that will contain only the /homestead directory (the same one that holds the Homestead configuration and sites). From there, you can navigate to the root folder and other parts of the Linux installation.
Installing Adminer
To install Adminer on Homestead you will need to setup a new site in Homestead.yml for a specific Homestead instance. Define a local URL to PHPMyAdmin application and
sites:
- map: adminer.test
to: /home/vagrant/homestead/www/adminerAfter that, log into the homestead box with vagrant ssh and position yourself in a directory that holds all your projects (in this case that would be the www directory).
Run curl -L -o index.php https://www.adminer.org/latest.php and that should be it. Visit the Adminer local URL and log in with the default Homestead database credentials.
Mailhog
Mailhog is a really useful tool for intercepting incoming and outgoing emails on a local machine. To set it up, first create a .env file in the /homestead directory and place the Mailhog config inside:
MAIL_DRIVER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=nullAfter that, the Mailhog interface will be accessible at http://localhost:8025.
Laravel Valet setup
As stated in the official documentation, Valet is a Laravel development environment for Mac minimalists.
Laravel Valet configures your Mac to always run Nginx in the background when your machine starts. Then, Valet proxies all requests on the *.test domain using DnsMasq to point to sites installed on your local machine.
It is ideal for machines with a small amount of RAM.
Installing Laravel Valet
The setup for Valet is really easy.
Install or update Homebrew to the latest version using the brew update.
Install PHP using Homebrew via
brew install php.If you don't have Composer installed, install it via
brew install composer. Be sure to restart the shell and add the~/.composer/vendor/bindirectory in your system's "PATH" (see instructions below).Install Laravel via Composer:
composer global require laravel/installer.Install Valet with Composer:
composer global require laravel/valet.Run the
valet installcommand. This will configure and install Valet and DnsMasq, and register Valet's daemon to launch when your system starts.
Possible issues
Composer not in the global system $PATH
$PATHWhen you type echo $PATH, you should get something like this:
/Users/nmc/.composer/vendor/bin:/usr/local/sbin:/Users/nmc/wpcs/vendor/bin:/Users/nmc/.rbenv/shims:/Users/nmc/.rbenv/bin:/Users/nmc/bin:/usr/local/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/X11/binIf the /Users/nmc/.composer/vendor/bin part is missing, it means that you need to add the composer to the global system $PATH, so that it is available for use through your terminal.
If you are using Z shell, you need to edit your /.zshrc file, and add
export PATH="$HOME/.composer/vendor/bin:$PATH"to the list. Then you need to restart the terminal, and the composer should be added to your $PATH. If you are using bash, then you should do the same but in the /.bash_profile file.
Setting up the site
Valet has a built-in WordPress driver, so it supports running WordPress. You can serve your sites in two ways — by using the park or link option.
The park option can be used to add a whole folder to Valet. Every folder in there will then be mapped to a site and get its own .test domain. So, if you add the ~/Sites folder to Valet and have a subfolder in there named wp-valet, the content of that folder will be served when you visit http://wp-valet.test in your browser. No setup is required. The link option can be used to serve a single site, without adding a whole directory.
$ mkdir ~/Sites
$ cd ~/Sites
$ valet parkThen, you need to add the wp-valet folder and use WP CLI to install WordPress.
$ mkdir wp-valet
$ cd wp-valet
$ wp core downloadAnd this is it. Once you do this, you should be able to go to http://wp-valet.test and see the classic WordPress installation screen.
Setting up the multisite
Multisite is a WordPress feature that allows you to have multiple sites managed from a single WordPress installation. Sites in WordPress multisite/network can have shared themes, plugins and users. It is an ideal solution when there is a need for multiple sites with similar design and functionality. More details on WordPress multisite feature can be found here.
To set up a multisite on Laravel Valet you'll start with a WordPress download, create a database and initialize the wp-config.php. Don't install WordPress yet, or use valet park command, as we will need to map multiple URLs to a single directory (depending on the type of Multisite).
Multisite with sub-domains
This type of multisite allows you to access sites with a sub-domain. The URLs will look like this:
dev.multisite-sub.test # Main site
site-1.dev.multisite-sub.test
site-2.dev.multisite-sub.testThis type of multisite is more common and usually requested by the clients. It is also a bit more complicated to set up. To achieve this some changes to the server configuration are required before the multisite can be installed. You need to point many domains/subdomains to the same directory. Luckily, Valet is already prepared for that and has all the configurations for this type of multisite.
Taking the above URLs as an example we can start installing the multisite. First, create a main domain for the site by navigating to the directory and running: valet link dev.multisite-sub.
After that, add additional domains with: valet link site-1.dev.multisite-sub.
To install multisite run: wp core multisite-install --prompt and fill all the necessary data.
1/9 [--url=<url>]: dev.multisite-sub.test # The main sites URL
2/9 [--base=<url-path>]: /
3/9 [--subdomains] (Y/n): Y
4/9 --title=<site-title>: Your site title
5/9 --admin_user=<username>: username # This is the username of the Super Admin that will be created
6/9 [--admin_password=<password>]: password
7/9 --admin_email=<email>: [email protected]
8/9 [--skip-email] (Y/n): Y
9/9 [--skip-config] (Y/n): n # This will add additional constants to the wp-config.phpThis will install the main site of your multisite. More info on this WP CLI command can be found here
To add additional sites run: wp site create --prompt and fill all the necessary data. More info on this WP CLI command can be found here
1/6 --slug=<slug>: site-1 # This needs to match the sub-domain that you registered with Valet
2/6 [--title=<title>]: Site Title
3/6 [--email=<email>]: [email protected] # This will add existing or create a new Administrator user for this site
4/6 [--network_id=<network-id>]: 1 # Network to associate new site with
5/6 [--private] (Y/n): n
6/6 [--porcelain] (Y/n):Multisite with sub-directories
This type of multisite allows you to access sites with sub-directories. The URLs will look like this:
dev.multisite-sub.test # Main site
dev.multisite-sub.test/site-1
dev.multisite-sub.test/site-2Laravel Valet does not come with configuration for this setup out of the box. For this you will need to use a custom driver. Guide for the installation of the custom drivers can be found here.
There are multiple drivers available for Valet that enable multisite with sub-directories and they provide installation instructions: * WordPress Multisite Subdirectory Valet Driver from Objectiv * Roots Laravel Valet and Bedrock Multisite
One thing to note is that by enabling custom driver for this type of multisite, the configuration for sub-domain multisite will be overwritten and will not work.
Other than installing custom drivers for sub-directory type of multisite, there is no difference in setting up this type of multisite from the sub-domain type of multisite. You won't need to register multiple domains or sub-domains as they don't apply for this type of multisite.
Possible issues
MySQL not started and database not set up
In the odd case that installation does not work and you get the blue 404 screen, try checking whether you are connected to the MySQL database.
brew services listYou should see something like this:
Name Status User Plist
dnsmasq started root /Library/LaunchDaemons/homebrew.mxcl.dnsmasq.plist
mysql started nmc /Users/nmc/Library/LaunchAgents/homebrew.mxcl.mysql.plist
nginx started root /Library/LaunchDaemons/homebrew.mxcl.nginx.plist
php71 started root /Library/LaunchDaemons/homebrew.mxcl.php71.plist
postgresql started nmc /Users/nmc/Library/LaunchAgents/homebrew.mxcl.postgresql.plistIf MySQL is not running, start it with
brew services start mysqlLog into your MySQL with mysql -u root and create the desired database.
create database db_name;
grant all privileges on db_name.* to 'root'@'localhost' identified by "";
flush privileges;
exit;This will create a db_name (change this according to your project) database and add a root user to it.
You should then be able to add those details to wp-config.php and install WordPress.
Docker
In order to install a WordPress development environment on Docker, you'll need to install Docker and use docker-compose.
For setting up docker with SSL enabled you can check the wordpress-docker repository.
After adding those files, from your terminal, run the following command
docker-compose up -d
This will build a Docker container and image with the specified settings from the .yml file in the detached state.
For more information about setting up and using Docker with WordPress, click here.
You can see if the containers are running by typing
docker ps --allYou should see something like
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
353c53e7721b nginx "nginx -g 'daemon of…" 8 seconds ago Up 5 seconds 0.0.0.0:8010->80/tcp wp-docker-nginx
8cf9f52c0540 wordpress:5.1.1-fpm "docker-entrypoint.s…" 9 seconds ago Up 7 seconds 80/tcp, 9000/tcp wp-docker-app
e1f1d0799b40 mysql:5.7 "docker-entrypoint.s…" 10 seconds ago Up 8 seconds 33060/tcp, 0.0.0.0:33066->3306/tcp wp-docker-db
352d5f6f64a9 phpmyadmin/phpmyadmin "/run.sh supervisord…" 10 seconds ago Up 8 seconds 9000/tcp, 0.0.0.0:8181->80/tcp wp-docker-phpmyadminYour project will be available on https://your.custom.url.test:8443.
Another way of using Docker is to use Dockerfile, which is especially useful when working on continuous integration and deployment (CI/CD). For instance, one such Dockerfile can look like this
# Stage 0, build app
FROM php:7.2-fpm as build-container
RUN curl -sS https://getcomposer.org/installer | php \
&& chmod +x composer.phar && mv composer.phar /usr/local/bin/composer
RUN apt-get update && apt-get install -y gnupg
RUN curl -sL https://deb.nodesource.com/setup_8.x | bash - && \
apt-get install -yq nodejs build-essential \
git unzip \
libfreetype6-dev \
libjpeg62-turbo-dev \
libmcrypt-dev \
libpng-dev \
&& curl -sL https://deb.nodesource.com/setup_8.x | bash - \
&& pecl install mcrypt-1.0.1 \
&& docker-php-ext-enable mcrypt \
&& docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
&& docker-php-ext-install -j$(nproc) gd \
&& docker-php-ext-install -j$(nproc) mysqli
RUN npm install -g npm
WORKDIR /build
COPY . /build
RUN cp /build/wp-config.php.template /build/wp-config.php
RUN bash /build/scripts/build-plugins.sh
# Stage 1, build app container
FROM php:7.2-fpm
RUN apt-get update && apt-get install -y \
libfreetype6-dev \
libjpeg62-turbo-dev \
libmcrypt-dev \
libpng-dev \
unzip \
mysql-client \
&& docker-php-ext-configure gd --with-freetype-dir=/usr/include/ --with-jpeg-dir=/usr/include/ \
&& docker-php-ext-install -j$(nproc) gd \
&& docker-php-ext-install -j$(nproc) iconv \
&& docker-php-ext-install -j$(nproc) mysqli \
&& docker-php-ext-install gd mysqli opcache zip
ADD https://downloads.wordpress.org/release/wordpress-4.9.8-no-content.zip /var/www/latest.zip
RUN cd /var/www && unzip latest.zip && rm latest.zip
RUN rm -rf /var/www/html
RUN mkdir -p /var/www/html/ \
&& mv /var/www/wordpress/* /var/www/html/
# Copy wp files
COPY --from=build-container /build/ /var/www/html/
RUN chown www-data:www-data /var/www/html/ -R
COPY config/php.ini /usr/local/etc/php/
WORKDIR /var/www/html/
CMD ["exec","php-fpm"]This Dockerfile will first build a local container with PHP, composer, and node. At that stage, your theme/plugins can be built. It also contains the RUN bash bin/build-plugins.sh command. You can replace this with your installation script (be it for plugins or theme). You'll place composer and npm builds in that shell script.
After that, you'll build the WordPress container and copy the plugins built in the previous stage. You can modify this to your liking. Beside this, you'll probably need a Docker image for nginx. But we won't be going into too much detail about it.
If you named this file Dockerfile, you'll run
docker build -t yourtag .In case you named it something like Dockerfile.php (if you need multiple stages and builds), you'll run
docker build -t yourtag -f Dockerfile.php .The Dockerfiles should be located in the root of your project.
To go in the interactive shell of the built image, type
docker run -it CONTAINER_NAME bashIf that fails, you can try
docker run -d CONTAINER_NAME
docker exec -it CONTAINER_NAME bashRunning the docker run with -d means that you are detaching it, and you can check the logs created while building it.
Useful Docker commands
Here are some useful Docker commands you might use.
List all containers
docker ps -as
List all images
docker images
Stop all running containers
docker stop $(docker ps -aq)
Remove all containers
docker rm $(docker ps -a -q)
Remove all images
docker rmi $(docker images -q)
Prune the system from unused images, containers, and networks documentation link
docker system prune
Docker notes
Depending on your project, the Docker compose or Dockerfile may differ. For more information, consult your friendly DevOps.
Useful links
Structuring the Docker setup for PHP projects
Sharing your sites
Installation
For more details see https://expose.dev/docs/getting-started/installation
PHP Archive (PHAR)
curl https://github.com/beyondcode/expose/raw/master/builds/expose -L --output expose
chmod +x expose
./exposesudo mv expose.phar /usr/local/bin/exposeVia Composer
composer global require beyondcode/exposeMake sure that your global composer directory is inside of your PATH environment variable. Simply add this directory to your PATH in your ~/.bash_profile (or ~/.bashrc) like this:
export PATH=~/.composer/vendor/bin:$PATHAs a docker container
Expose has a Dockerfile in the root of the source that you can build and use without any extra effort.
docker build -t expose .Usage:
docker run expose <expose command>Examples:
docker run expose share http://192.168.2.100 # share a local site
docker run expose serve my-domain.com # start a serverShare your first site
Once your authentication token is setup, you are ready to share your first site with Expose. Expose creates a tunnel between your local development URLs/HTTP server and a publicly available web server.
The easiest way to share your local URLs is by calling expose share followed by the local URL that you want to share:
# Will share access to http://192.168.2.100
expose share http://localhost:3000
# Will share access to http://my-local-site.dev
expose share my-local-site.devBy default, Expose assumes that you want to share unenecrypted local traffic through HTTP. If you want to share a local HTTPS URL append the protocol to the url, like this:
# Will share access to https://my-local-site.dev
# Note the https for tunneling locally encrypted sites
expose share https://my-local-site.devLast updated