Development Guides Home >> Guide to Testing Custom Code

Guide to Testing Custom Code - cPanel Plugin Registration

Introduction

This guide explains the basics of how to troubleshoot registration issues for cPanel plugins.

This document lists appropriate test steps for most custom code, and helpful information to troubleshoot common problems. Make certain that you evaluate the testing requirements of your own code, and allow its functionality to determine the appropriate steps.

Testing steps

Check to ensure that you used the correct method for the desired theme and version

Each cPanel theme requires different methods of registration, and these methods vary between different cPanel & WHM versions. For more information, read our Guide to cPanel Plugins documentation.

Check to ensure that you formatted the install.json file correctly

cPanel plugins for cPanel & WHM version 11.44 and later use the install.json file to interface with the dynamicui system, which adds icons to the cPanel interface.

Your install.json file should resemble the following example:

[
   {
      "name" : "Support",
      "order" : 11,
      "type" : "group",
      "id" : "custom_support_group"
   },
   {
      "icon" : "supportcontact.png",
      "group_id" : "custom_support_group",
      "order" : 10000,
      "name" : "Contact Support",
      "type" : "link",
      "id" : "contact_support",
      "uri" : "http://support.example.com"
   }
]

Troubleshoot common issues

error: No file found at example.tar.gz

Problem:

You receive the following error when you attempt to use the /usr/local/cpanel/scripts/install_plugin script to install your plugin:

error: No file found at example.tar.gz

Solution:

This error occurs because the /usr/local/cpanel/scripts/install_plugin script could not locate the plugin file that you specified.

To resolve this issue, make certain that the plugin file exists in the specified location on your server.

error: No archive given!

Problem:

You receive the following error when you attempt to use the /usr/local/cpanel/scripts/install_plugin script to install your plugin:

error: No archive given!

Solution:

This error occurs because you did not pass a file location to the /usr/local/cpanel/scripts/install_plugin script.

To resolve this issue, make certain that you include the file location when you run the script. For more information, read our Guide to cPanel Plugins documentation.

error: install.json is missing from the plugin archive, cannot process

Problem:

You receive the following error when you attempt to use the /usr/local/cpanel/scripts/install_plugin script to install your plugin :

error: install.json is missing from the plugin archive, cannot process

Solution:

This error occurs when the /usr/local/cpanel/scripts/install_plugin script cannot find the install.json file in the specified plugin file. In cPanel & WHM version 11.44 and later, plugin registrations require this file.

For more information, read our Add Plugins documentation.

Permission denied

Problem:

You receive one or more Permission denied errors when you attempt to use the /usr/local/cpanel/scripts/install_plugin script to install your plugin.

Solution:

These errors occur when you attempt to run the /usr/local/cpanel/scripts/install_plugin script as any user other than the root user. Due to the permissions that this script requires in order to access the necessary files, only the root user can run this script successfully.