| META TOPICPARENT
Creating Legacy cPanel Plugins
For cPanel & WHM versions before 11.30
The methods detailed in this document are supported; however, cPanel tags will eventually be phased out. If you plan to make your application compatible with all future versions of cPanel & WHM, you should use our LiveAPI system whenever possible.
If you are using cPanel & WHM version 11.30 or 11.32, please review our most recent cPanel 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 can view the relevant documentation here.
The cPanel Plugin development workflow
- You must first write the cPanel module. The cPanel module consists of the plugin's back end code and API interfaces.
- The second step is to create the plugin's front end. This consists of the actual HTML files. You may also use PHP to create the cPanel plugin's front end.
- To continue, you need to generate the cPanel plugin registration file. This file dictates how and where to display the plugin within the cPanel interface.
- Finally, you must write an installation script for the cPanel plugin. Currently, there is not a universal method for installing cPanel plugins. You will need to create a custom installer for your cPanel plugin.
Writing your cPanel module
cPanel is an API-driven system. This means that interactions between the front and back ends of cPanel are handled by API calls. API calls are divided into 2 categories: API1 and and API2.
A single API function corresponds to a function contained within a Perl module. These Perl modules are located in /usr/local/cpanel/Cpanel. If you would like more information on how to use API calls, you can view our documentation here.
Whether you should use an API1 or API2 call depends on the functions you wish to use and the data you wish to manipulate. Generally, if you intend to manipulate a single piece of data (e.g. a single string or integer), you will probably need to use an API1 call. If you intend to manipulate multiple pieces of data, or you need a custom template, you should probably use an API2 call.
Writing your front end
Your plugin's front end interface should consist of HTML, PHP, or CGI files placed in the following directory:
These files can be accessed via
You can write these files using a variety of methods:
HTML is the fastest available option. If you choose to use HTML, you can provide logic and querying via cPanel HTML tags. Using cPanel HTML tags depends on which API you wish to access.
- For information about using cPanel HTML tags to access API1, click here.
- For information about using cPanel HTML tags to access API2, click here.
There are 2 implementation options for PHP within a cPanel plugin:
- phpcp and cpphp — This option allows you to run PHP code then cPanel HTML tags or run cPanel HTML tags before running PHP code, respectively.
- For more information about using phpcp and cpphp, you can visit our documentation here.
- LivePHP — This method allows you to access cPanel's API calls via an object oriented interface.
- Note: LivePHP does not support cPanel HTML tags.
- For more information about using LivePHP, you can visit our documentation here.
cPanel also supports the ability to run a normal CGI application. If you choose to use this method, you should know that there is no way to directly access cPanel's API. You will need to use our XMLAPI to make calls. For information about using CGI applications to access our APIs, click here.
Querying cPanel's API
cPanel Template Toolkit
One feature provided as of 11.25.0 is Template::Toolkit. cPanel Template Toolkit is a template-driven parser for API2 calls. The toolkit uses the Template Toolkit Perl library to format a response from an API2 function. The cPanel Template Toolkit provides an even simpler interface for accessing cPanel's API2 functions, resulting in code that is easier to write.
cPanel HTML tags
Most of our
x3 interfaces use cPanel HTML tags. These tags are unique HTML tags that are parsed on the server-side to query the cPanel back end. You can use these tags with both HTML and cPPHP. For more information on using cPanel HTML tags, visit our documentation here.
Note: LivePHP does not support cPanel HTML tags.
Our XMLAPI provides a function called
cpanel XMLAPI call implements extra overhead to your plugin when used, so use this method sparingly. For more information on our XMLAPI's
cpanel function, you can visit our documentation here.
LivePHP is an object-oriented PHP interface to cPanel's APIs. Its output is similar to the XMLAPI's
cpanel function. However, LivePHP does not return an associative array. For more information on LivePHP, you can read the documentation here.
Creating Your cPanel Plugin Registration File
The cPanel Plugin Registration File is how cPanel knows that your plugin exists. You can create your plugin's registration here. After creating the file, you will need to run the following command:
You can bypass this system by writing
- /usr/local/cpanel/bin/register_cpanelplugin $path_to_plugin_file
dynamicui files directly.
dynamicui files provide greater flexibility but are more complex. Visit our documentation about dynamicui files to learn more.
Currently, we do not provide a universal method for managing plugins. To distribute your plugin, you will need to provide a script that handles its installation. We recommend a script that adheres to the following structure:
- Verifies that the system is in a compatible state.
- Downloads the tarball that contains the addon, using either
- Places contents from the tarball in the appropriate locations.
- Successfully runs register_cpanelplugins.
- Cleans up any remaining installation information.
- Set PAGETITLE = Creating legacy cPanel plugins