I have been noticing several people challenged with calling cPanel functions via our various ways of hooking into our APIs. Unfortunately, this isn’t as cut and dry as just calling a function within a programming language.ย Various factors, such as whether the call is being made from within cPanel or from a remote system, affect how this needs to be done.
To help you understand this, I will begin covering these topics in a series of posts on cPanel’s various functions and how they work. In this first post of the series, I will discuss the basics of cPanel’s APIs, and how to call API1 functions.
The basics
Before we can even begin going over how to call cPanel’s API functions, we need to discuss the various API types.
For the most part, cPanel’s API is divided into two sub-systems; API1 and API2. The difference between these is in how they are called and how they return data.
API1 will normally print data to the cPanel interface.ย This works well when the functions are called via cpanel tags (covered later in this article), but won’t return much useful data when called via the XML API, livePHP or CGI scripts.
API2, on the other hand, is a much more robust system, capable of returning complex data structures that can be parsed into templates contained within a cp tag. API2 calls, as they do actually return data, will always return relevant information when called via the XML API, livePHP or CGI scripts.
One of my favorite features of API2 is that it uses named-based parameters that translate well into URL parameters.
Calling API1 functions
API1 functions can be called via a tag. As previously mentioned, these print data to the cPanel interface. cpanel tags use the following format:
<cpanel Module="function( params )">โจ
So, if you wanted to call Ftp::ftpservername(), which is used to print out which FTP server is being used, it would be called with the following syntax:
<cpanel Ftp="ftpservername()">
Now, you will not want all functions to actually display data. For example, Mysql::adddb is generally something that you do not want printing data, for security reasons. Instead you want to check for error handling.
Any data being printed from this function can be suppressed in the browser via HTML comments, like so:
<!--Module="function()"-->โจ
Sending input to the API1 function
So, in order to pass data to an API function, we will need a way to pull in the data.
Inside of cPanel’s HTML parsing, we have access to certain variables. The main variables that you need to be aware of are $FORM and $CPERROR.
$FORM is merely a variable that is populated with either GET or POST data passed to the page from the browser. This variable is how cPanel passes data around from page to page. To access it, you call the $FORM variable the same way that you would call a hash in Perl ($FORM{‘element’}).
So, for example, if you had a page called add_mysql_db that was passed the following:
add_mysql_db.html?db=dbname
It would contain the following:
<cpanel Mysql="addb( $FORM{'db'} )">
The <cpanelif> tag
Along with the cpanel tag, there is also support for some really basic logic within this system, via the <cpanelif> tag. This tag allows for checking of basic boolean logic to see if a variable is set; if true, it will send whatever is contained between the <cpanelif> tags to the browser.ย <cpanelif> tags cannot be nested in any way.
To call cpanelif, you will do something like the following:
<cpanelif $VAR{''}>
HTML CODE HERE
</cpanelif>
This is useful when you want to display an error message within cPanel’s interface.ย These are populated into the $CPERROR{$context} variable.
Unfortunately, context is defined on the back-end on a per-module basis, so generally $context will be the same as whatever module you are calling.ย In the case of our previous MySQL example, if we wanted to check for an error message, we would want to do the following:
<cpanel Mysql="adddb( $FORM{'db'} )">
<cpanelif $CPERROR{‘mysql’}>
ERROR: $CPERROR{‘mysql’}
</cpanelif>
Of course, you would want to also want to do !$CPERROR{‘mysql’} around any success messages to make sure you don’t end up with “ERROR: errormsg This was successful”.
These are the basics of how to call API1 via .html files. You can always use the XML API to call these functions as well, but because this is API1, you may not get any useful data.
