One of the most frequently asked questions we get regarding WordPress on .NET is how to work with plugins. This tutorial will explain how to install plugins with the current state of PeachPie and how to get past some of the basic problems you might encounter.
Note: this process will change over time and only reflects the current state of PeachPie as of June 2018. Please always refer to the most current way of working with plugins.
PeachPie and WordPress
In case you are new to the project, PeachPie is an open-source PHP compiler and runtime on .NET and .NET Core, which is able to run PHP applications, frameworks and libraries on the .NET (Core) runtime. One of the most popular applications PeachPie is fully compatible with is WordPress, the world’s most popular CMS. But what makes WordPress such an easy choice for web development is its incredibly rich ecosystem of plugins. Because PeachPie runs WordPress fully compiled to .NET Core, the way you will install and use plugins will differ, as they also have to be compiled ahead of time.
Pre-requisites
If you are completely new to the idea of running WordPress on .NET Core, we suggest to start with this article first. We will breeze through the setup of WordPress itself in this tutorial.
Before you begin, you will need the following:
- .NET Core 2.0 or higher
- A MySQL database either installed physically or virtualized with Docker
- The PeachPie WordPress project or the original WordPress sources and proceed according to this article.
Before proceeding, make sure you have a MySQL database set up, either locally or in a virtualized environment. We are using Docker for this purpose. Note that Docker only works on Windows 10 Professional; because Hyper-V is disabled in the Home Edition, you will have to use the Docker Toolbox, where you create a separate virtual machine with a different IP address, so you can’t use localhost as your MySQL server address. Make sure you assign your MySQL server the IP address of the virtual machine the Toolbox launches. On Mac OS, Docker works just fine, but we have previously run into issues with dotnet quitting unexpectedly.
To start your MySQL database, use a command such as:
[bash]
docker run -e MYSQL_ROOT_PASSWORD=password -e MYSQL_DATABASE=wordpress -p 3306:3306 -d mysql:5.7
[/bash]
The easiest way to start is by downloading or opening the WordPress project in your GitHub desktop application from our official repository [HERE]. These sources already include a pre-prepared project for VSCode and a draft of a C# API for those who are interested. Alternatively, you can also use the original source code of WordPress and proceed as per our tutorial.
Open the project in Visual Studio or VS Code. We’ll use VS Code for this purpose:
And that’s all you have to do for now. Now just hit F5.
Assuming everything goes as planned, the project should compile without any errors and the application should start and listen on port 5004. Navigate to http://localhost:5004/ in your favorite browser and if your database is set up correctly, the classic WordPress installation window should appear. Go through the installation and you should get the first “Hello world!” blog post right away:
Installing a plugin
Now that we have WordPress set up, we would also like to install some plugins. The process for this when you are running WordPress on .NET Core with PeachPie is different from the regular plugin installation you might be used to. You have to compile the plugins separately along with the main project. So let’s pick an easy plugin first and see how it works. We’ll start off with the popular “Insert Headers and Footers” plugin.
First, either stop the debugging process in VS Code (stop button or Shift+F5) or close the web server in the terminal with Ctrl+C. Download the plugin’s sources and extract them to the WordPress plugin folder, which should be in wp-content/plugins. Now you can hit F5 again and rebuild. The Terminal in VS Code will likely have outputted a bunch of warnings, but the build should have succeeded. Now go ahead and reload your WordPress site in the browser and navigate to the plugins.
You should see the newly installed plugin listed here, and now you will have to activate it. After the compilation, this is the second major milestone we have to pass in order to get the plugin running. In general, if your chosen plugin doesn’t activate correctly, it means that there is probably a bug or missing feature in PeachPie. We would really appreciate if you report such behavior by submitting a new issue to us.
However, “Insert Headers and Footers” should work and so once you activate it, you should see two success messages at the top of your dashboard:
Now when you click on the link to configure the plugin, you have reached the final milestone: making sure that the plugin runs. If you find any misbehaviors now, we again kindly ask you to report them to us and we will fix them as soon as we can. In case of our small test plugin, there isn’t much that could go wrong, so your screen should now look as follows:
What happens if you run into issues?
Not all troubles on your way to run a plugins have to be reported. Some issues are solved with a quick workaround, whereas others do require some actual implementation work in PeachPie. Let’s take a look at what happens when we try to install another plugin called Auth0:
We get 2 errors, both related to tests. At this point in time, albeit not for much longer, PeachPie doesn’t support the PHAR extension yet and therefore cannot resolve some of the PHPUnit test cases. Since these are just tests, however, we can work around this issue by simply deleting the test folders from the plugin files (or for more advanced users by excluding test files right in the .msbuildproj project file). After doing so, the plugin compiles just fine:
Go ahead and reload your WordPress running locally on .NET Core and you will see the Auth0 plugin listed among those that are installed; you can now try to activate it. For the sake of the tutorial, we’ll stop here; we haven’t gone on to test if the plugin works. Let’s rather discuss what happens when you run into an actual error that either prevents the plugin from compiling or causes it to crash while running.
When this happens, you can proceed in one of two ways. If you believe you know how to fix the issue, feel free to submit a pull request with your fix to the main PeachPie repository. If your contribution meets our standards of code, is clean, doesn’t break anything and doesn’t make unnecessarily large changes, we will be thrilled to accept it. The second thing you can do is to submit an issue. Ideally, we like to see a small test case that isolates the problem and lets us reproduce it, as well as a meaningful title and a detailed description of how the error occurred. We usually address issues within the first day of submitting.
Future Work
Keep in mind that PeachPie is still in version 0.9. First and foremost, as the project moves along and more libraries, functions and constructs will be implemented, you are less likely to encounter an issue with your PHP code on PeachPie. Secondly, many issues occur due to the massive cURL library, which we are continuously implementing, or PHAR, which is also coming up soon on the roadmap.
UPDATE: The process of working with plugins is now significantly more elegant. This repo provides the WordPress project split into several NuGet packages, which allows each of the NuGet package to reference the others, meaning that you will only compile the plugin alone when going through the process of checking whether it runs. This speeds up the compile time and consequently your process by a lot.
We are also working on offering a packaged and fully configured product for WordPress on .NET. If you are interested in being one of the early testers for this, let us know and we’ll be happy to include you in the testing.