How to create a cPanel Plugin

For cPanel & WHM 11.34 and 11.36

Note: For cPanel & WHM 11.32 and earlier, read the legacy plugin documentation.

Overview

cPanel plugins allow you to add new functionality to cPanel. This particular document is relevant only to cPanel. For information about WHM plugins, read the WHM plugins documentation.

The cPanel Plugin Development Workflow

To develop a cPanel plugin:

1. Write a cPanel module that consists of the plugin's back end code and API interfaces.
2. Create the plugin's front end. The plugin's front end consists of the actual HTML files, or you may also use our LiveAPI system to create your plugin's user interface.
3. Generate the cPanel plugin registration file that dictates how and where to display the plugin in the cPanel interface.
4. Write an installation script for the cPanel plugin.
   Note: At present, we do not offer a universal way to install cPanel plugins. You will need to create a custom installer for your plugin.
5. Compress your cPanel plugin for distribution

Query cPanel's API

In cPanel & WHM 11.30, we added a new system for our API 1 and API 2 called LiveAPI. LiveAPI is an expanded set of environments that allow you to run API 1 and API 2 calls via the socket.

At present, we offer the following evironment:

• The LiveAPI PHP Class — This is a PHP implementation of cPanel & WHM's LiveAPI environment. This document provides a set of basic instructions and examples for working with the LiveAPI PHP class. You can find this PHP class at /usr/local/cpanel/php/cpanel.php.
• LiveAPI system — This is a Perl implementation of cPanel & WHM's LiveAPI environment. This document provides a set of basic instructions and examples for working with the LiveAPI Perl module. You can find this Perl module at /usr/local/cpanel/.

In addition to Perl and PHP, the LiveAPI system supports the following language environments; however, we do not yet provide a library for their use:

• Ruby: .liverb or .live.rb
• Python: .livepy or .live.py
• CGI: .livecgi or .live.cgi

Choose an API 1 or API 2 function

• You should use API 1 functions if you intend to manipulate a single piece of data (for example, a single string or integer).
• You should use API 2 functions if you intend to manipulate multiple pieces of data, or you need a custom template.

Create custom API functions

If you would like more information on how to create your own API functions, read the cPanel Modules documentation.

Step 1: Write your cPanel module

Your cPanel module consists of the plugin's back end code and API interfaces. cPanel is an API-driven system. This means that interactions between the front end and back end of cPanel are handled by API calls. You can find single API functions contained within their associated Perl modules in the /usr/local/cpanel/Cpanel directory.

Step 2: Create the front end

The front end of your plugin comprises the fields and buttons that your users will need to fill out and access to functionally use your plugin. Your plugin's front end interface should consist of HTML, PHP, or CGI files placed in the following directory:

• /usr/local/cpanel/base/frontend/$themename/

Remember: You should replace $themename with the actual value you intend to use.

You can access these files at the following location:

• $ip:2082/frontend/$themename/$filename

Remember: You should replace $ip, $themename, and $filename with the actual values you intend to use.

Step 3: Create your plugin registration file

The plugin registration file is how cPanel (the application) will know that your plugin exists. To create a registration file, use our cPanel plugin registration file generator.

After you create the registration file, run the following command:

• /usr/local/cpanel/bin/register_cpanelplugin $path_to_plugin_file

Remember: You should replace $path_to_plugin_file with an actual path.

You can bypass this system if you write the dynamicui files directly. dynamicui files provide greater flexibility but are more complex. To learn more, read the dynamicui files documentation.

Step 4: Write your plugin's installation script

We do not provide a universal method to manage your plugins. To distribute your plugin, you will need to create a custom script that handles the installation.

Your installation script must do the following:

1. Verify the system is in a compatible state.
2. Use wget or curl to download the tarball that contains the plugin.
3. Place the tarball's contents in the appropriate locations.
4. Successfully run /usr/local/cpanel/bin/register_cpanelplugin $path_to_plugin_file.
   • Remember: You will need to replace $path_to_plugin_file with an actual path.
5. Clean any installation information that remains.

Step 5: Compress your cPanel plugin for distribution

Your cPanel plugin contains the application source files, cPanel registration file, and the installation script that you created. Once you write your installation script, compress the files together for simple distribution and installation. For example, you can convert your plugin to a tarball file, which has a file extension of .tar.gz.