Child pages
  • UAPI Functions - PassengerApps::edit_application
Skip to end of metadata
Go to start of metadata

Description

This function edits a Ruby application for an account.

Important:

In cPanel & WHM version 76 and later, when you disable the WebServer role, the system disables this function. For more information, read our How to Use Server Profiles documentation.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/PassengerApps/edit_application?name=slippers&new_name=littledog&path=%2Flittledog&domain=toto.com&deployment_mode=production&envvar_name-1=scarecrow&envvar_value-1=brain&envvar_name-2=lion&envvar_value-2=courage&clear_envvars=0&enabled=1


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Edit the slippers application.
$poll = $cpanel->uapi(
    'PassengerApps', 'edit_application',
    array(
        'name' 			  => 'slippers',
		'new_name'		  => 'littledog',
        'path' 			  => '/littledog',
        'domain' 		  => 'toto.com'
		'deployment_mode' => 'production',
		'envvar_name-1'	  => 'scarecrow',
		'envvar_value-1'  => 'brain',
		'envvar_name-2'	  => 'lion',
		'envvar_value-2'  => 'courage',	
		'clear_envvars'   => '0',	
		'enabled'		  => '1',
  )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
 #  Edit the slippers application.
my $poll = $cpliveapi->uapi(
    'PassengerApps', 'edit_application',
    {
        'name'    		   => 'slippers',
		'new_name'		   => 'littledog',
        'path'    		   => '/tlittledog',
        'domain'  		   => 'toto.com',
		'deployment_mode'  => 'production',
		'envvar_name-1'	   => 'scarecrow',
		'envvar_value-1'   => 'brain',
		'envvar_name-2'	   => 'lion',
		'envvar_value-2'   => 'courage',
		'clear_envvars'	   => '0',
		'enabled'		   => '1',
  }
);


Note:

For more information, read our Guide to the LiveAPI System.

 cPanel Template Toolkit
<!--  Edit the slippers application. -->
[% execute('PassengerApps', 'edit_application', { 'name' => 'slippers', 'new_name' => 'littledog', 'path' => '/littledog', 'domain' => 'toto.com', 'deployment_mode' => 'production', 'envvar_name-1' => 'scarecrow', 'envvar_value-1' => 'brain', 'envvar_name-2' => 'lion', 'envvar_value-2' => 'courage', 'clear_envvars' => 0, 'enabled='1' } ) %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username PassengerApps edit_application name="slippers" new_name="littledog" path="/littledog" domain="toto.com" deployment_mode="production" envvar_name-1="scarecrow" envvar_value-1="brain" envvar-name-2="lion" envvar_value-2="courage" clear_envvars="0" enabled="1"


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
  "messages": null,
  "errors": null,
  "status": 1,
  "metadata": {
      
  },
	"data": {
    "littledog": {
        "base_uri": "/littledog",
        "domain": "toto.com",
        "enabled": 1,
        "envvars": {
			"scarecrow": "brain"
			"lion": "courage"
					},
        "name": "toto",
        "path": "/home/dorothy/littledog"
		"deployment_mode": "production"
    }
  }
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
namestring

Required

The application's current name.

A valid application name.slippers
new_namestring

The application's new name.

If you do not use this parameter, the function does not change the application's name.

A valid string.

Important:

  • You must use an application name that does not already exist.
  • An application name must contain 50 or fewer characters.
littledog
pathstring

The application's new filepath.

If you do not use this parameter, the function does not change the application's filepath.

A valid filepath, relative to the user's /home directory.

/home/dorothy/littledog
domain string

The application's new domain.

If you do not use this parameter, the function does not change the application's domain.

A valid domain on the cPanel account.toto.com
deployment_modestring

The new server environment in which to run the application.

If you do not use this parameter, the function does not change the application's server environment.

  • development — Sets the application to run in a development environment.
  • production — Sets the application to run in a production environment.
production
envvar_namestring

A new server environment variable for the application.

Important:

  • The function replaces all current environment variables with the variables that you pass in this parameter.
  • You must pass this parameter for each envvar_value parameter that you pass.

Note:

To add multiple environment variables, you must increment this parameter. For example, envvar_name-1, envvar_name-2, envvar_name-3.

If you do not use this parameter, the function does not change an environment variable's name.

A valid string.

Important:

This parameter's value can only contain letters, numbers, underscores, and dashes, and must begin with a letter.

scarecrow
envvar_valuestring

The server environment variable's new value.

Important:

  • The function replaces all current environment variable values with the values that you pass in this parameter.
  • You must pass this parameter for each envvar_name parameter that you pass.
  • An environment variable value must contain 1024 or fewer ASCII-printable characters.

Note:

To add multiple environment variable values, you must increment this parameter. For example, envvar_value-1, envvar_value-2, envvar_value-3.

If you do not use this parameter, the function does not change an environment variable's value.

A valid string.brain
clear_envvarsBoolean

Whether to clear the application's environment variables.

This parameter defaults to 0.

  • 1 — Clear the variables.
  • 0 — Do not clear the environment variables.
0
enabledBoolean

Whether to enable the application and generate the Apache configuration.

This parameter defaults to 1.

  • 1 — Enabled.
  • 0 — Disabled.
1

Returns

ReturnTypeDescriptionPossible valuesExample
application namehash

A hash that contains an application's configuration information.

Note:

The hash's name is the application name.

This hash contains the base_uri, domain, enabled, name, old_name, old_domain, path and deployment_mode returns and the envvars hash.

 

base_uri

string

The application's base URI.

The function returns this value in the application name hash.

A valid URI./littledog

domain

string

The domain for which the function created the application's Apache configuration.

The function returns this value in the application name hash.

A valid domain on the cPanel account.toto.com

enabled

Boolean

Whether the application is enabled.

The function returns this value in the application name hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

envvars

hash

A hash of application environment variables and their values.

The function returns this hash in the application name hash.

A hash of valid environment variables and their values. 

name

string

The application's new name.

The function returns this value in the application name hash.

A valid application name.littledog

deployment_mode

string

The type of environment in which the application will run.

The function returns this value in the application_name hash.

  • development
  • production
production

path

string

The application's filepath.

The function returns this value in the application name hash.

A valid filepath./home/dorothy/littledog