Introduction
UAPI modules use the Cpanel::Args object to receive arguments (input parameters). When you write a custom UAPI module, you must use this object for your functions to operate correctly.
Required $args declaration
Before you can use Cpanel::Args methods, you must declare the $args variable, as in the following example:
|
1
2
3
|
sub custom_function { my ( $args, $result ) = @_;} |
This example declares the $args and $result variables, and assigns values from the input parameters that the function received.
Important:
We strongly recommend that you begin all custom functions with the my ( $args, $result ) = @_; declaration. Functions that do not perform this action will experience errors.
For more information about the Cpanel::Result object, read our Cpanel::Result Object documentation.
Methods
The Cpanel::Args object includes methods that you can use to incorporate input parameter values into your function call.
$args->exists()
This method checks whether a named parameter exists. Use this method, for example, to ensure that a value exists for an input parameter before you attempt to perform the function's action.
# Check whether the param1 input parameter exists.$args->exists('param1'); |
In this example, the exists method checks whether a value exists for the param1 input parameter.
- If the
param1parameter exists, the method returns true (1). - If the
param1parameter does not exist, the method returns false (0).
Note:
This method returns true if the parameter exists with a null or blank value.
$args->get()
This method retrieves one or more named parameters. We recommend that you use this method to assign values from optional input parameters.
# Assign param1's value to $arg1 and param2's value to $arg2.# The param1 and param2 input parameters are optional.my($arg1, $arg2) = $args->get('param1', 'param2'); |
This example assigns the param1 parameter's value to the $arg1 variable, and the param2 parameter's value to the $arg2 variable.
Note:
This method does not return runtime errors if the method attempts to assign a value from a nonexistant parameter.
- For this reason, we recommend that you do not use this method with required parameters.
- To check whether a parameter exists and then return the value or an error message, use the
get_required()method.
$args->get_required()
This method checks whether a named parameter exists.
- If the parameter exists, the method returns that parameter and its value.
- If it does not exist, the method returns a predetermined error message.
We recommend that you use this method to assign values from required input parameters that could have a blank value.
# Assign param1's value to $variable.# Returns an error if param1 does not exist.# No error if param1's value is blank.my ($variable) = $args->get_required('param1'); |
This example uses the get_required method to check whether the param1 parameter exists, and then assigns the parameter and its value to the $variable variable.
Note:
This method does not return an error if the parameter exists with a null or blank value.
$args->get_length_required()
This method checks whether a named parameter exists, and ensures that it is not a blank or null value.
- If the parameter exists and has a value, the method returns that parameter and its value.
- If it does not exist, has a blank value, or has a null value, the method returns a predetermined error message.
We recommend that you use this method to assign values from required input parameters that must not be empty.
# Assign param1's value to $variable.# Returns an error if param1 does not have a value or is empty.my ($variable) = $args->get_length_required('param1'); |
This example uses the get_length_required method to check whether the param1 parameter exists and has a valid value, and then assigns the parameter and its value to the $variable variable.
$args->add()
This method adds a key=value pair to the currently available named parameters. Use this method, for example, to introduce additional parameters from another subroutine.
$args->add('parameter_name','value'); |
In this example, the add method adds the parameter_name parameter, and assigns it a value of value.
$args->keys()
This method retrieves all of the current named parameters. Use this method to assign all of the named input parameters to an array, without the need to explicitly name each parameter.
my $value = $args->keys(); |
In this example, the keys method assigns all of the available named parameters and their values to the $value variable.