{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Guide to Testing Custom Code","description":"With its world-class support and rich feature set, cPanel &amp; WHM has been the industry-leading web hosting platform for over 20 years. Trusted worldwide by our technology partners WordPress, CloudLinux, LiteSpeed, and more.","siteUrl":"https://api.docs.cpanel.net/","image":"/assets/cpanel-whm.ccd85fdccb18de0645f8a6ebf38e36a0489b92fc9d4ca92776f06aa5a160b167.db81178d.svg","keywords":"documentation, api, portal, cpanel","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides"},"children":["Development Guides Home"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"guide-to-testing-custom-code","__idx":0},"children":["Guide to Testing Custom Code"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide explains the basics of how to test your custom code. You can avoid many common issues when you test your code regularly throughout the development process."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Warning:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["cPanel Technical Support cannot always assist third-party developers with problems that relate to custom code. For this reason, always test your projects thoroughly before you attempt to use them on production servers."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"basic-troubleshooting","__idx":2},"children":["Basic troubleshooting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["While the items below may seem basic, we see many support tickets and forum posts with these issues. As a result, we recommend that, when you troubleshoot custom code, you check the following items first:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"does-your-code-include-any-typos","__idx":3},"children":["Does your code include any typos?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common mistakes include missing semicolons (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[";"]},") at the ends of lines, out-of-place comment characters, and misspelled variable names, function names, or filenames."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Perl code, add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use strict;"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use warnings;"]}," statements to the beginning of your custom code to find these errors more easily."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"are-the-users-permissions-correct","__idx":4},"children":["Are the user's permissions correct?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make certain that the user who will execute the code possesses the correct permissions."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Unless you properly implement privilege escalation, cPanel users ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cannot"]}," run WHM functions. For more information, read our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/guide-to-api-privilege-escalation"},"children":["Guide to API Privilege Escalation"]}," documentation."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["WHM users ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cannot"]}," run cPanel functions unless you supply a cPanel user to authenticate as. For more information, read our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/guide-to-testing-custom-code/guide-to-testing-custom-code-whm-api-calls"},"children":["Guide to Testing Custom Code - WHM API 1 Calls"]}," documentation."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some functions require specific ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.cpanel.net/whm/packages/feature-manager/"},"children":["feature lists"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.cpanel.net/whm/server-configuration/tweak-settings/"},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Tweak Settings"]}]}," values, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["root"]}," privileges. For more information, read the desired function's documentation."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"does-the-function-exist-in-the-api-that-you-called","__idx":5},"children":["Does the function exist in the API that you called?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["WebPros International, LLC produces two current and three deprecated APIs, and they all include separate sets of functions. Make ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["certain"]}," that the function and module that you call exist in the API version that your code uses."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API calls ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," use the correct port:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2082"]}," — Unsecure calls to cPanel's APIs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2083"]}," — Secure calls to cPanel's APIs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2095"]}," — Unsecure calls to cPanel's APIs via a Webmail session."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2096"]}," — Secure calls to cPanel's APIs via a Webmail session."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2086"]}," — Unsecure calls to WHM's APIs, or to cPanel's APIs via the WHM API."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2087"]}," — Secure calls to WHM's APIs, or to cPanel's APIs via the WHM API."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Otherwise-correct calls will return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Permission denied"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Function not found"]}," errors if they use an incorrect port number."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Call examples"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"whm-api-1","__idx":6},"children":["WHM API 1"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Browser-based call..."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://hostname.example.com:2087/cpsess##########/json-api/accountsummary?api.version=1&user=username\n"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Browser-based calls to WHM API 1 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," include the WHM API 1 version (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.version=1"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Command-line call..."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"whmapi1 accountsummary user=username\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, read our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/guide-to-testing-custom-code/guide-to-testing-custom-code-whm-api-calls"},"children":["Guide to Testing Custom Code - WHM API 1 Calls"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/whm/introduction"},"children":["Guide to WHM API 1"]}," documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"cpanel-uapi","__idx":7},"children":["cPanel UAPI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cPanel or Webmail session URL call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://hostname.example.com:2083/cpsess##########/execute/Module/function?parameter=value&parameter=value&parameter=value\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Command-line call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"uapi --user=username --output=type Module function parameter=value parameter=value\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LiveAPI PHP Class call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"$cpanel = new CPANEL(); // Connect to cPanel - only do this once.\n\n// Call a UAPI function.\n$function_result = $cpanel->uapi(\n   'Module', 'function',\n   array(\n       'parameter'     => 'value',\n       'parameter'     => 'value',\n       'parameter'     => 'value',\n        )\n);\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LiveAPI Perl Module call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.\n\n# Call a UAPI function.\nmy $function_result = $cpliveapi->uapi(\n   'Module', 'function',\n   {\n       'parameter'     => 'value',\n       'parameter'     => 'value',\n       'parameter'     => 'value',\n   }\n);\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Template Toolkit call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<!-- Call a UAPI function. -->\n[%\nexecute(\n    'Module', 'function',\n    {\n       'parameter' => 'value',\n       'parameter' => 'value',\n       'parameter' => 'value',\n    }\n);\n%]\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, read our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/guide-to-testing-custom-code/guide-to-testing-custom-code-cpanel-api-and-uapi-calls"},"children":["Guide to Testing Custom Code - cPanel API and UAPI Calls"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cpanel/introduction/"},"children":["Guide to cPanel UAPI"]}," documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"cpanel-api-2","__idx":8},"children":["cPanel API 2"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["cPanel API 2 is deprecated."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Call through the WHM API 1"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://hostname.example.com:2087/cpsess##########/json-api/cpanel?cpanel_jsonapi_user=user&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=Module&cpanel_jsonapi_func=function&parameter=\"value\"\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Command-line call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"cpapi2 --user=username --output=type Module function parameter=value parameter=value\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Template Toolkit call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<!-- Call a cPanel API 2 function. -->\n[%-\nUSE Api2;\nSET myvariable = execute(\n    'Module', 'function',\n   {\n       'parameter'      => 'value',\n       'parameter'      => 'value',\n       'parameter'      => 'value',\n   }\n);\n%]\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LiveAPI PHP Class call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"$cpanel = new CPANEL(); // Connect to cPanel - only do this once.\n\n// Call the function.\n$my_variable = $cpanel->api2(\n   'Module', 'function',\n   array(\n       'parameter'      => 'value',\n       'parameter'      => 'value',\n       'parameter'      => 'value',\n   )\n);\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["LiveAPI Perl Module call"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.\n\n# Call the function.\nmy $my_variable = $cpliveapi->api2(\n   'Module', 'function',\n   {\n       'parameter'      => 'value',\n       'parameter'      => 'value',\n       'parameter'      => 'value',\n   }\n);\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, read our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/guide-to-testing-custom-code/guide-to-testing-custom-code-cpanel-api-and-uapi-calls"},"children":["Guide to Testing Custom Code - cPanel API and UAPI Calls"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cpanel-api-2/"},"children":["Guide to cPanel API 2"]}," documentation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"deprecated-apis","__idx":9},"children":["Deprecated APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["cPanel API 2 is deprecated. We ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["strongly"]}," recommend that you only use the equivalent ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cpanel/introduction/"},"children":["cPanel UAPI"]}," functions instead."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Warning:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," attempt to use cPanel or WHM interface URLs to perform actions in custom code. You ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," call the appropriate API functions in order to perform the actions of cPanel & WHM's interfaces. For example, do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," pass values to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".html"]}," pages, as in the following example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://example.com:2083/cpsess###########/frontend/jupiter/email_accounts/index.html/create#email=test&domain=example.com"]},". While this ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unsupported"]}," method sometimes worked in previous versions of cPanel & WHM, we ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["strongly"]}," discourage its use and do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," guarantee that it will work in the future. Instead, the correct method to perform this action is to call the appropriate API function."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"are-the-file-permissions-correct","__idx":10},"children":["Are the file permissions correct?"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"success","name":"Remember:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API functions run as a specific user. If that user does not posses the correct permissions, errors may occur."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Often, integrators see errors because of file permission issues with one or more of the files that relate to their custom code."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note:"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make certain that your custom code does not change the permissions for cPanel & WHM's files. Changes to system file permissions may cause unexpected problems on cPanel & WHM servers."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following examples describe two possible scenarios in which incorrect file permissions could cause problems:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you see the following error when you call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://api.docs.cpanel.net/openapi/cpanel/operation/add_pop/"},"children":["UAPI's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Email::add_pop"]}," function"]},", the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/home/username/etc/example.com/shadow"]}," file possesses incorrect permissions:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"File open for /home/username/etc/example.com/shadow failed with error Permission denied\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the system cannot write to this file, it cannot create an email address, because it ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," use this file to store email password hashes during the account creation process."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you see the following error when you call ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/cpanel-api-2/cpanel-api-2-modules-fileman/cpanel-api-2-functions-fileman-mkfile"},"children":["cPanel API 2's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Fileman::mkfile"]}," function"]},", the user cPanel account's files and directories may posses incorrect permissions:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Encountered error in Fileman::mkfile: Could not create file \"example.txt\" in /home/user/public_html/: Permission denied: Permission denied\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To check the permissions for a directory's files, run the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ls -al"]}," command."]}]},"headings":[{"value":"Guide to Testing Custom Code","id":"guide-to-testing-custom-code","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"Basic troubleshooting","id":"basic-troubleshooting","depth":2},{"value":"Does your code include any typos?","id":"does-your-code-include-any-typos","depth":3},{"value":"Are the user's permissions correct?","id":"are-the-users-permissions-correct","depth":3},{"value":"Does the function exist in the API that you called?","id":"does-the-function-exist-in-the-api-that-you-called","depth":3},{"value":"WHM API 1","id":"whm-api-1","depth":4},{"value":"cPanel UAPI","id":"cpanel-uapi","depth":4},{"value":"cPanel API 2","id":"cpanel-api-2","depth":4},{"value":"Deprecated APIs","id":"deprecated-apis","depth":4},{"value":"Are the file permissions correct?","id":"are-the-file-permissions-correct","depth":3}],"frontmatter":{"seo":{"title":"Guide to Testing Custom Code"}},"lastModified":"2026-05-18T23:59:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/guide-to-testing-custom-code","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}