Develop Plesk Extensions Series: Create extension stub and IDE project

In the previous part (Install a local version of Plesk), I showed you how to install Plesk locally in a virtual machine. In this part we will create an extension stub with the help of the command line and add this extension into your favorite IDE (Integrated Development Environment), like PHPStorm. Additionally, we will setup the development environment correctly to be able to use auto-completion, which makes it much easier to write proper code.

Let’s get started.

Part 2 – Create extension stub and IDE project

Open your terminal and use SSH to connect to the Plesk VM (see the first part of the series for an explanation how to use SSH with the VM). Plesk has a built-in command to create an extension stub and one command to register this extension within the Plesk instance. This means that the extension is directly visible in Plesk under Extensions. Once logged in, enter the following command:

$ plesk bin extension --create my-extension

Replace my-extension with the name of your extension. You shouldn’t use blank spaces or names that already exist in your Plesk installation. Use hyphens (-) if you want to separate words. After the creation of the stub, you will see a success message and different paths of the newly created extension.

I would like to describe in more detail what the paths mean:

The extension’s entry points: /opt/psa/admin/htdocs/modules/my-extension
This is the path where the PHP file is located that is directly callable from outside. So, this is the file that is called if you open the extension in Plesk.

The PHP classes: /opt/psa/admin/plib/modules/my-extension
In this path we will put all extension code such as controllers, language files and views.

The installation scripts: /opt/psa/admin/plib/modules/my-extension/scripts
Path for the scripts that are executed in installation process, e.g. pre-install.php.

The directory with run-time data: /opt/psa/var/modules/my-extension
Path where the system writes data during its operation.

The executable programs: /opt/psa/sbin/modules/my-extension
Path for executable script, e.g. shell scripts.

You will need these files later for the mapping within the IDE. I will explain this in more detail later. Now we will register the stub in Plesk, so that we can access it directly with the browser within the Plesk instance.

Type the following command into your console:

$ plesk bin extension --register my-extension

You will see the success message The extension was successfully registered. Go to Plesk and select the menu item Extensions. Voilà, your first extension is already installed and even selectable. But this is just a skeleton, we still have to put some flesh on the bones!

So far, so good! But how do we get the extension into a project in our IDE on the local machine? This is easy! First we create a Zip package with all required files and folders with the help of a special command in the console. By the way, it is great how Plesk supports developers here! Just type in your console:

$ plesk bin extension --pack my-extension

You will see a success message and the path to the archive that you need to download to your local machine. You can use the Linux command scp or an SFTP client, such as FileZilla. Using the client is much easier, for scp you should read the manual or visit StackOverflow. 🙂

Add the extension to your local IDE and sync changes

So far, so good! Now we have to prepare our local environment. Plesk extensions are written in PHP (besides HTML, CSS and JavaScript for the output), so we need a good IDE for PHP which will help us to write great extensions. I always use PhpStorm by JetBrains which is a powerful and fast tool.

Let’s start first a new project within PhpStorm. Select the option New Project Without Server because we will map our local copy with the copy in the virtual machine later once we’ve created the project. Select the folder where you extracted the downloaded extension stub and define the folder as the Project Root. After PhpStorm has analyzed all files in the selected folder, you will see the complete file structure of the basic extension on the left.

I will explain the structure and what files are used for what purpose in more detail in the next part of this tutorial on the basis of the cheesy Pizza extension.

What is about auto-completion?

Well, this is exactly the reason why we want to use an IDE instead of a simple editor. But since we don’t have the code of the complete system in our local environment, the IDE does not know what classes and functions it can suggest to help us.

For that reason, the Plesk team has created so-called API stubs which will help us to use the Plesk Extension SDK efficiently and quickly. Download the files from the official GitHub account and include them as an external library to the local project.

To include the files, go to Preferences… – Languages & Frameworks – PHP and click on the + button at the bottom of the page.

Additionally, you should also include the Zend Framework because internally Plesk uses this framework and also the Plesk extensions rely on components of this framework. Download the latest 1.x version of the Zend Framework and include it the same way as you did it with the API stubs. The latest release of the framework is at the moment version ZF 1.12.20.

How to update my Plesk instance in the virtual machine easily?

We will map all needed paths and activating auto-deployment to simplify the development process. At first, we have to connect PhpStorm with the VM using Tools – Deployment – Connection. Select the type SFTP and use the SSH credentials to connect to the VM in the Connection tab. Use the same data that you’ve already used to connect via your terminal!

Once the connection can be established properly, click on the Mappings tab and map all paths from your local copy to the paths of the extension in the virtual machine. Use the paths that were displayed when you created the extension stub (see above). Map the corresponding local folder to each path properly, e.g. the htdocs folder has to be mapped to the path /opt/psa/admin/htdocs/modules/my-extension and so on.

If you want to deploy changes automatically, then select the option Tools – Deployment – Automatic Upload (always). You can also update the remote files manually by clicking on the Upload option in the menu.

Still following? I’ve got good news for you! This was the preliminary game, now we can finally start to write our first Plesk extension. This topic will be covered in the next part of the tutorial series where I will explain the basics of an extension and show you the code of a simple extension.

Stay tuned and stay Plesky!