Creating a cPanel Plugin

For cPanel & WHM 11.30 and 11.32

This document only applies to cPanel & WHM versions 11.30 and 11.32. If you are developing for a system that uses a version of cPanel prior to version 11.30, please review our legacy plugin documentation.

cPanel plugins allow you to add new functionality to cPanel. This particular document is germane only to cPanel. For information about creating WHM plugins, you should review our WHM plugins documentation.

The cPanel Plugin Development Workflow

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. At present, we do not offer a universal way to install cPanel plugins. You will need to create a custom installer for your plugin.

Querying cPanel's API

In cPanel & WHM 11.30 we added a new system for using our API 1 and API 2 called LiveAPI. LiveAPI is an expanding 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.
• The LiveAPI Perl Module (Documentation Coming Soon) — 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 also 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

Choosing an API 1 or API 2 function

• You should use API 1 functions if you intend to manipulate a single piece of data (e.g. 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.

Creating custom API functions

If you would like more information on how to create your own API functions, please review our Writing cPanel Modules documentation.

Step 1: Writing 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 and back ends of cPanel are handled by API calls. You can find single API functions contained within their corresponding Perl modules in /usr/local/cpanel/Cpanel.

Step 2: Creating the front end

The front end of your plugin comprises the fields and buttons your users will need to fil 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 will need to replace $themename with the actual value you intend to use.

You can find these files can in:

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

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

Step 3: Creating your plugin registration file

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

After creating the registration file, run the following command:

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

Remember: You will need to replace $path_to_plugin_file with an actual path.

You can bypass this system by writing dynamicui files directly. dynamicui files provide greater flexibility but are more complex. Visit our documentation about dynamicui files to learn more.

Step 4: Writing your plugin's installation script

We do not provide a universal method for managing 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. Download the tarball that contains the plugin using either wget or curl.
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 remaining installation information.