Before we start writing our first WordPress plugin, it is important to have a good set of tools in place that will allow you to work locally on your computer and be more efficient in your work. While it is possible to perform some development tasks with the built-in tools that are provided with the operating system, creating a solid local development environment will help you develop plugins quickly and have full control over your server settings to be able to test different configurations.

This chapter proposes a set of free tools that can easily be installed on your computer, regardless of your preferred operating system, to facilitate the development of your future WordPress plugins. These tools include a local web server to speed up page access and avoid sending files constantly to a remote server, a version control system to keep incremental backups of your work, and a code editor to enhance your editing capabilities. In addition to installing and learning how to use these tools, this chapter also shows how to download and configure a local WordPress installation on a local web server.

The first step to configure a local development environment is to install a local web server on your computer. This will transform your computer into a system capable of displaying web pages and performing all tasks related to rendering a WordPress website locally.

Having a local web server has many benefits, as follows:

• It provides a quick response to the frequent page refreshes that are made as plugin code is written, tested, and refined, since all information is processed locally
• It removes the need to constantly upload new plugin file versions to a remote web server to validate code changes
• It allows development to take place when no internet connection is available (for example, when traveling on an airplane)
• It offers a worry-free programming environment, where you cannot bring down a live website with a programming error or an infinite loop

There are many free packages available online that contain all of the web server components necessary to run a WordPress installation. This recipe shows you how to easily install one of these packages.

1. Visit the XAMPP website (https://www.apachefriends.org/) and download the appropriate XAMPP package for your computer.

2. Optional on Windows: Disable the Windows User Access Control (UAC) feature to give full permissions to XAMPP to install itself on your system (look up the steps to perform this procedure on your favorite search engine).
3. Launch the XAMPP installer (xampp-win32-5.6.30-0-VC11-installer.exe on the Windows platform).
4. Acknowledge the warning message about User Access Control (UAC) and click on Next to start the installation process.
5. On the following screen, which lists all of the components that can be installed, uncheck the boxes for FileZilla FTP Server, Mercury Mail Server, Tomcat, Perl, and Webalizer, then click on Next:

6. On the Installation folder screen, leave the default value for the installation directory if possible (c:\xampp), since some references to this folder will be made in this book, then click on Next.
7. Click on the Next button to proceed with the web server installation.
8. Make sure that the option to start the Control Panel is checked and click on Finish once the installation is complete.
9. Select your preferred language for the XAMPP Control Panel and click on Save to launch the application.
10. Click the Start buttons for Apache and MySQL to launch these modules. Their names will be highlighted in green once they have been successfully started, as shown in the following screenshot:

11. Open a web browser and navigate to the address http://localhost to display your local web server's welcome page:

12. Open the c:\xampp\apache\conf\httpd.conf file in a text editor (for example, Notepad).
13. Search for the DocumentRoot configuration option and change its value to a different location on the disk to avoid keeping your project files under the original installation directory. For example, you could set it to a new directory designed to hold your local development installation of WordPress, such as DocumentRoot "C:/WPDev".

14. Search for the Directory option and change it to the same path that was used for DocumentRoot, that is, <Directory "C:/WPDev">.
15. Save and close the httpd.conf file.
16. Create the directory specified as DocumentRoot, if it does not already exist on your computer.
17. Open XAMPP Control Panel.
18. Stop and re-start the Apache service for the new configuration to take effect.

The XAMPP package contains all of the components necessary to run a web server capable of hosting a WordPress website on your computer. These components include:

• Apache web server
• PHP interpreter
• MySQL database server
• phpMyAdmin database management interface

The XAMPP package also includes other components, which are not required to run a local WordPress development site.

Once XAMPP is installed and started, the keyword localhost that we type in the web browser is recognized by the operating system as a request to communicate with the web server on the local computer and the Apache web server displays the welcome page from its documentation.

The XAMPP documentation is a set of flat HTML files located in the c:\xampp\htdocs directory on the Windows platform. This is the web server's default working directory.

The last few steps of the recipe instruct the Apache web server to look for the local website's content in a new directory. This is a safety precaution to be sure that site files are not deleted inadvertently if XAMPP is uninstalled. It can also help in managing multiple sites on a single computer.

While XAMPP is a full-featured local web server package and is available on the three major operating systems, there are many others available online. Most of these packages will run the required web services on the computer directly, while more advanced packages, such as Varying Vagrant Vagrants (VVV), will virtualize a Linux-based web server on your computer to create a more accurate replica of a final deployment environment optimized for WordPress. Here is a list of some of the most popular local web server packages:

For Windows:

• WampServer (http://www.wampserver.com/en/)
• EasyPHP (http://www.easyphp.org/)

For macOS X:

• MAMP (https://www.mamp.info/en)

For Windows, Mac, or Linux:

• Varying Vagrant Vagrants (https://varyingvagrantvagrants.org)

If it's not possible for you to set up a local web server to develop WordPress plugins, or if you are planning to share the development tasks with one or more people, then an alternative to setting up a local web server is to create a remote development environment.

The easiest way to create such an environment, assuming that you already have a web hosting account set up, is to create a sub-domain off your main domain. This will allow you to create a standalone test installation for WordPress that will still provide safety from affecting a live site, but will not carry the other benefits of a local installation.

• The Downloading and configuring a local WordPress installation recipe

The next component of our local development environment is to install WordPress on your local web server to run a fully working website and have all of its files hosted locally.

WordPress has always prided itself with its easy five minutes installation process. Installing it on a local web server is even easier and quicker than it would be on a live remote server. This recipe covers the creation of a MySQL database to store all data related to our new WordPress installation and the actual setup process.

This recipe assumes that you have a local web server installed on your computer. This web server can be a fresh install performed using the previous recipe or can be from a previous installation. The steps in the following section are written with a focus on new local web servers. If you have created a new account to access the MySQL database or changed the root user's password, some of the steps will change slightly. The location of the phpMyAdmin tool might also be different if you are using a different web server than XAMPP. You should refer to your web server's documentation to find out what that address is.

1. In the web browser, navigate to the address http://localhost/phpmyadmin/ to access your web server's database administration tool.
2. Click on Databases tab in phpMyAdmin.
3. Type the name of the new database to be created in the empty field following to the words Create database. In this case, we will use the name wordpressdev:

4. Click on the Create button to complete the database creation process.
5. Download the latest WordPress installation package from the official WordPress website (https://wordpress.org). The download link can be found on the very first page of the website and the download package will work on any web server, local, or remote.

6. Extract the WordPress archive file contents using your favorite file archiver utility or your operating system's built-in capabilities.

7. Copy the contents of the resulting wordpress folder to your local web server's web content directory (c:\WPDev, if you followed the previous recipe). You should not copy the wordpress folder itself unless you want the address of your WordPress website to be http://localhost/wordpress.
8. Direct your web browser to http://localhost to start the WordPress installation process.
9. Select your preferred language and click on Continue.
10. On the next page, click on the Let's Go button to start your development site's configuration.
11. Update the Database Name field to reflect the name of our newly-created database (wordpressdev).
12. Set the MySQL User Name to root.
13. Delete all the characters from MySQL Password to leave it empty, since local MySQL server root accounts are typically configured without any password.
14. Leave the Database Host field with its default value (localhost).
15. Change the Table Prefix field from its default value to wpdev_:

16. Click on the Submit button to validate the information entered. If any parameters are not entered correctly, or if the WordPress installation process cannot correctly access your database server, it will display an error page and give you an opportunity to make corrections.
17. Click on the Run the install button for WordPress to create the required table structure in the designated MySQL database.
18. Specify a Site Title (for example, Development Site).
19. Set Username for the admin user. For increased security, it's always best to choose a username that people would not be able to easily guess. Obvious names such as admin or administrator should be avoided.
20. Optionally, change the randomly generated password with a password of your own choice. If WordPress determines that your new password is weak, you will need to check the additional checkbox that appears to confirm that you want to use a weak password.
21. Enter your email address in the appropriate field (although no email will actually be sent on most local development installations).
22. If you are configuring a live external development server, check the Discourage search engines from indexing this site option, since we do not want this development site to appear anywhere.
23. Click on Install WordPress to complete the installation and you will be automatically logged in to the site's WordPress Dashboard.

24. Click on the Development Site link in the Dashboard admin bar to see your new site:

In the first few steps, the phpMyAdmin interface is used to create a database on the local MySQL server. This web-based database management tool comes bundled with XAMPP and most other web servers. The http://localhost/phpmyadmin address will always take you to the database administration tool, even if you relocate your web server's document root directory as documented in the previous recipe.

Once a database is created and the WordPress files have been copied to the correct location, pointing your browser to the local web server gets it to search through the document root directory to find HTML files to send back to the browser or PHP files to execute. In the case of WordPress, the web server finds the index.php file and executes it using its PHP interpreter. As the WordPress code is executed, it checks if a configuration file is present and launches the installation process when it does not find one. The WordPress code does not see any difference between the local web server that we are running it on and a remote live web server that would be accessible anywhere online.

While we specified an email address for the administrator during the installation, many local web servers are not configured to send out email messages so we will never receive any email communication in these cases. It is preferable to use a remote server when developing and testing email functionality in a plugin.

Once this recipe has been completed, you will have a functional WordPress installation in place.

Version control is an important part of any code development project, to keep track of a project's history, to have full and organized backups, and to be able to easily roll back changes to get back to a known working state. Version control is also the best and most efficient way to share code and other files when developing a project in a team environment. In addition to being a great version control system that is easy to use and configure, Subversion (often referred to as SVN) is also the technology that manages all submissions on the official WordPress plugin directory. Therefore, by setting up and using a local Subversion repository during your initial plugin development, you will immediately be ready to share your creations with the community.

1. Visit the TortoiseSVN website (https://tortoisesvn.net/downloads.html) and download the free Subversion client for your version of Windows (32-bit or 64-bit).

2. Launch the TortoiseSVN installation program and install it using all the default installation options.
3. Create a new folder on your hard drive that will host the local Subversion repository (for example, c:\WPSVN).
4. Right-click on the new folder and select the TortoiseSVN | Create repository here menu item, then click on Start Repobrowser. TortoiseSVN will create the required file structure in the target directory and display the contents of the repository, which is currently empty:

Subversion is a free, open source version control system that is designed to keep file revisions organized and backed up over the course of a project's development, as well as provide access to older versions of all files at any time. If you have ever found yourself copying a directory on your computer and giving each copy sequentially numbered names or adding dates to their names, then you will recognize that version control is really just a more organized and efficient method of achieving the same goal of keeping backups of known working versions of code files and being able to access any older version of a file.

While the default Subversion interface is a set of command-line utilities, TortoiseSVN and many other client applications provide graphical tools to create, access, and manage local and remote repositories.

In addition to familiarizing yourself with this system for later use on wordpress.org, using a local Subversion repository will ensure that you will always have older versions of your plugins easily accessible in case a code change that you perform breaks your work and you cannot figure out how to get back to a working state.

While there are many Subversion clients available online to interact with a repository, not all of them include the necessary administration tools to easily create a repository, as shown in this recipe. You should look for these administration capabilities when searching for a Subversion client for non-Windows platforms.

On macOS X, versions (http://versionsapp.com/) and Cornerstone (https://www.zennaware.com/cornerstone) offer similar capabilities but are paid applications.

On Linux, PagaVCS is a free TortoiseSVN clone (https://code.google.com/p/pagavcs/) while SmartSVN (http://smartsvn.com) is a paid SVN client.

If your Subversion client does not offer the ability to create a local repository, you can download the Subversion command-line tools from the official Subversion website (https://subversion.apache.org/packages.html) and create a repository manually following instructions found in the online Subversion reference manual (http://svnbook.red-bean.com/).

While Subversion is easy to learn and is the system that is used by WordPress on its official plugin repository, other version control systems, such as Git (https://git-scm.com/) and Mercurial (https://mercurial-scm.org/), are gaining traction in the open source development community and could also be considered to manage your plugin code.

• The Importing initial files to a local Subversion repository recipe

Once you have a local repository in place, this recipe describes the steps required to add files and start tracking their revisions over time. To have the flexibility to create multiple plugins, as discussed throughout this cookbook, without having to worry about adding each of them to the repository individually, we will add the entire WordPress plugin directory to your local repository.

You should have already installed a Subversion client on your computer and created a local repository, as described in the Creating a local Subversion repository recipe. These steps will be slightly different based on the Subversion client that you have selected and your operating system.

1. Navigate to the wp-content/plugins directory of your local WordPress installation (for example, c:\WPDev\wp-content\plugins, if you followed the previous recipe) with the file explorer.
2. Right-click on the folder and select the TortoiseSVN | Import menu item.
3. Enter the file location of your local Subversion repository in the URL of repository field (for example, file:///c:/WPSVN), if it is not already specified.
4. Write a message in the Import message field that gives an overview of the files that are being imported into the repository:

5. Click on the OK button to complete the import process.

Once the import operation has started, TortoiseSVN sends all the selected files to the repository, displaying each of their names in the process. At the end of the import operation, it also displays the revision number that it assigned to this first set of files.

Using the Import Subversion feature copies all the selected files to the repository. In addition to storing the files themselves, Subversion identifies each file with a revision number and an import message. The revision number is generated by Subversion and incremented every time a group of files is added. It is especially useful when searching through a file's history.

The import message is specified by the user and is actually optional. That being said, it is important to set meaningful import messages when adding files to a repository, as it will make it easier for you to identify what these files are, the state that they are in, and the reason they were added to the repository when performing future searches.

While these steps have led to a successful import, you may be wondering why nothing changed in the plugin directory. The reason is that the import process only makes copies of the selected files to the Subversion repository. An additional step, called the checkout process, needs to take place to start keeping track of changes and file history.

• The Checking out files from a Subversion repository recipe

After performing an initial import of the files to a Subversion repository, the files need to be checked out to really start working in a version control environment. This recipe explains how to check out files from your local repository and what the resulting file structure changes will be.

You should have already installed a Subversion client, created a local repository, and imported files before following this recipe. These steps will be slightly different based on the Subversion client that you have selected and the operating system you are using.

1. Navigate to the WordPress plugin directory of your local installation in the file explorer if you are not already there.
2. Right-click in the white space of the directory window and select the SVN Checkout... menu item.
3. Enter the file location of your local Subversion repository in the URL of repository field (for example, file:///c:/WPSVN), if it is not already specified.
4. Set Checkout directory to the plugin folder of your local WordPress installation (for example, C:\WPDev\wp-content\plugins).

5. Click Yes on the dialog asking if files should be checked in a folder that is not empty. At this time, TortoiseSVN will retrieve all the files that were added to the repository and copy them locally.
6. Once the operation is complete, look back at the file listing in the plugins directory to see that it has changed from its previous state:

Performing a checkout operation takes copies of all files from the repository and places them in the target directory. It also creates a .svn directory at the top level of the file hierarchy to store files that will support the version control functionality.

By default, most operating systems do not show folders that have a period at the beginning of their name, since this usually identifies hidden files and directories. To display hidden folders on the Windows 10 platform, carry out the following steps:

1. Open Windows Explorer.
2. Click on the View tab and check the option labeled Hidden Items.

The .svn directory contains information on the address of the repository that is associated with the files in the current folder. It also contains an original version of each file that was checked out. These original files are used for Subversion to determine when changes have been made to each file relative to their state when they were checked out or updated. While it might seem a bit redundant to have an original copy of all the files in the .svn folders when our repository is locally hosted, this functionality allows Subversion to identify file changes when working on a remote repository, such as the official WordPress plugin server, even when your computer is not connected to the internet.

As you work with Subversion and TortoiseSVN, files that you create, modify, and delete will go through a number of different states. The following section explains what each of them represents.

The green check mark indicator shown over each file icon, after performing this recipe, shows us that our files and directories have not been modified since they were last checked out or updated. These indicators will change over time as we start modifying existing files and creating new ones. The following is a list of the most common statuses that files will have as you work on a project, along with their associated TortoiseSVN icons:

• Normal (green check mark): The file or directory is in a normal state and has not changed since it was last checked out or updated.
• Modified (red exclamation mark): The file or directory has been modified since it was last checked out or updated.
• Non-versioned (blue question mark): The file or directory is not under version control.
• Added (blue plus sign): The file or directory is new and has been marked to be committed to the repository in the next commit operation.
• Deleted (red x icon): The directory has been deleted and will be removed from the repository in the next commit operation.
• Ignored (grey do not pass symbol): This file or directory will never be sent to the repository and Subversion should stop checking for changes. This state is useful for keeping private files, such as personal documentation or to-do lists, in the same directory as the plugin but without uploading them to the repository and tracking their history over time.
• Conflicted (yellow exclamation mark): This icon appears in situations of conflict, typically when more than one person works on the same repository and multiple users have made changes to the same file. While the Subversion client will normally try to merge these changes to create a single file, a conflicted state indicates that the system was not able to merge these changes automatically. Conflicted files need to be manually merged or the user needs to indicate if the file has priority over the version that is currently stored in the repository.

• The Committing changes to a Subversion repository recipe

During the course of a project, plugin files will typically be created, modified, or deleted. These changes should be transmitted regularly to the Subversion repository to have proper backups of all the files in a project. A good practice is to commit changes at least once a day, with more frequent commit operations taking place when specific milestones are reached in the implementation of a plugin's features.

This recipe indicates how to manage file creation, modification, and deletion operations to keep everything organized and mirrored in the Subversion repository.

You should have already installed a Subversion client, created a local repository, and imported and checked out files before performing the steps in this recipe. These steps will be slightly different based on the Subversion client that you have selected and the operating system you are using.

1. Navigate to the WordPress plugin directory of your local installation in the file explorer if you are not already there.
2. Open the hello.php file in a text editor.
3. Edit the plugin name on line 7 to change it from Plugin Name: Hello Dolly to Plugin Name: Goodbye Dolly.
4. Save and close the file. You should now notice that the modified file is identified by a red exclamation mark icon in the file explorer, indicating that it has been modified.
5. Create a new folder in the plugins directory named chapter1.
6. Right-click on the new folder and select the TortoiseSVN | Add... menu item to bring up the Add dialog.
7. Click on the OK button to queue the file to be added to the repository when changes are next committed. You will see a blue plus sign appear over the folder name to indicate that it will be added to the repository on the next code commit.
8. Navigate to the chapter1 directory and create a new text document named example.txt.
9. Navigate back to the plugins directory.
10. Right-click on the index.php file and select the TortoiseSVN | Delete menu item. The selected file is immediately deleted and disappears from the file explorer.

11. Right-click in an empty part of the plugins directory and select the SVN Commit... menu item. This last step will display the Commit dialog, with a top section to write a message detailing the changes that are being committed, and a bottom section containing a file listing. Notice that all files but one have check marks next to them, since they have either been recognized as being changed by the Subversion client or have been added or deleted through the TortoiseSVN interface. The file that does not have a check mark next to it is the text file that was created but not tagged to be included in the next commit operation using the TortoiseSVN contextual menu:

12. Type a message in the appropriate field indicating the reason for the operation.
13. Right-click on the chapter1/example.txt file and select the Add menu item to add it to the operation.
14. Click on the OK button to send all the changes to the Subversion repository.

Using the local data stored in the .svn folder, the Subversion client is able to analyze the directory contents and identify all the files that are new, have been modified, or are missing since the last checkout or update operation was performed, and then generate a list of these changes.

When the commit operation is performed, new files are added to the repository, modified files are uploaded and stored next to their previous versions, while deleted files are tagged as no longer being part of the current project version. While some of these behaviors might seem strange, it's by preserving previous versions of files and even keeping files that are no longer part of a project that Subversion is able to let us navigate through a project's entire history.

While it is preferable to use the TortoiseSVN menu to mark files and directories for addition and to delete items that are no longer needed, it is also possible to perform these operations when the commit is about to take place, as we saw in the recipe steps.

Before files are committed to the repository, many programmers and developers want to see what changes were made to the modified files, especially in an environment that promotes peer reviews before committing code changes.

By right-clicking on any modified file in the Commit dialog and selecting the Diff menu item, the TortoiseSVN client will display its built-in file difference viewer tool, highlighting the parts that are different between the last version of the file in the repository and the current version of this file. This allows users to see what changed at a glance and be sure that no code was modified inadvertently.

If you are the only person committing files to a repository and you are working on a single computer, then you will never need to use the SVN Update menu item. This function is designed to compare your local files with the repository and check if new files or new revisions are available in the repository that are not present locally. It will then apply all the necessary changes to the local versions of these files. Remember to use the SVN Update option in TortoiseSVN regularly if you are working in a team environment or are developing a project across multiple computers.

Until a file is committed to a repository, it's possible to reverse all the changes made to it since the last checkout, update, or committal by using the Revert item in the TortoiseSVN menu. This can be useful if you made changes to the code that broke its functionality and want to get back to a known good state.

As multiple versions of files are committed to a repository over time, Subversion keeps track of all the versions of these files along with the messages that were associated with each commit operation. The Show Log tool, accessible from the TortoiseSVN menu, allows you to see a full history of changes made to one more files, use the difference viewer to see changes between previous and current versions of each file, and easily restore a specific revision of these files.

Most operating systems provide a built-in text editor. While it is possible to create WordPress plugins using such a simple tool, it is highly recommended to install a dedicated code editor on your computer to simplify your plugin development work.

Of course, not all code editors are equal. Here are some of the features that you should look for when selecting a code editing application:

• PHP syntax highlighting
• Completion of PHP function names
• Ability to search in multiple files simultaneously
• Ability to highlight all instances of search keyword(s) or selected text
• Line numbering
• Ability to resize the editor text or specify a replacement font
• Possibility of opening multiple files simultaneously

The following editors contain most or all of these key features. Most are free tools, but some are paid applications:

On the Windows platform:

• Programmer's Notepad (http://www.pnotepad.org)
• Notepad++ (https://notepad-plus-plus.org/)
• Visual Studio Code (https://code.visualstudio.com)

On the Mac platform:

• TextMate (https://macromates.com)
• TextWrangler (https://www.barebones.com/products/TextWrangler)

On the Linux platform:

• Screem (http://www.screem.org/)

Cross-platform:

• Sublime Text (https://www.sublimetext.com)

This recipe explains how to install a dedicated code editor and shows basic editor operations. It provides detailed steps using Programmer's Notepad for Windows.

1. Download the installation package for one of the text editors listed previously.
2. Run the installation program for the editor and select the default settings.
3. Launch the text editor.
4. Open the hello.php file from the plugin directory of your local WordPress installation. You will see that different parts of the code are displayed in different colors based on the type of code.
5. Double-click on a word to select it. You will see any other instance of that same word highlighted across the file contents:

6. Select the View | Line Numbers menu item (or similarly named item based on your selected text editor) to display line numbers in the editor.

Code editors have built-in parsers that enable them to identify the parts of the code that are comments, PHP language functions, text strings, and a variety of other elements. Having these elements colored on the screen makes it much easier to read through code and to see that a function's name is not spelled correctly, or to quickly identify comments.

Another functionality that is crucial when developing plugins for WordPress is the ability to see line numbers in the editor. This function comes in handy, especially when PHP code errors come up, since the filename and line of code that was being processed at the time of the error are normally displayed. In most code editors, the developer can either scroll to the specific line or enter the line number in a quick Go To dialog box to jump to that line right away.