MAJOR=4
MINOR=6
DEVNAME=tty6
  #   ˆl–äY>”Ši?u ¾ ^¸È®4ú˜´oÁ„Á?À¿ ?÷     =encoding UTF-8

=head1 NAME

cPanel::PublicAPI - A perl interface for interacting with cPanel

=head1 SYNOPSIS

  use cPanel::PublicAPI;

  # Auto detect authentication information
  my $cp = cPanel::PublicAPI->new();
  # or specify a user/password
  my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'pass' => 'somepass' );
  # or specify an accesshash
  my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'accesshash' => $accesshash );
  # or specify an API token
  my $cp = cPanel::PublicAPI->new( 'user' => 'someuser', 'api_token' => $api_token );

  # Perform an xml-api query
  $cp->whm_api('listaccts');
  # Pass parameters to the xml-api
  $cp->whm_api('createacct', {'username' => 'someuser', 'password' => 's0m3P4$$w()Rd' } );
  # Return JSON from xml-api (rather than a hash reference)
  $cp->whm_api('version', undef, 'json');

  # Perform an API2 query
  $cp->cpanel_api2_request('whostmgr',
    {
      'module' => 'Email',
      'func' => 'listpopswithdisk',
      'user' => 'someuser',
    }
  );
  # Perform an API2 query when authenticated as a user
  $cp->cpanel_api2_request('cpanel',
    {
      'module' => 'Email',
      'func' => 'listpopswithdisk',
    }
  );
  # Pass parameters to an API2 call
  $cp->cpanel_api2_request('cpanel'
    {
        'module' => 'Email',
        'func' => 'addpop',
    },
    {
        'domain' => 'domain.com',
        'email' => 'username',
        'password' => 'SojmASDM(#(Jinasifodanosd',
        'quota' => 200
    },
  );

  # Perform an API1 query
  $cp->cpanel_api1_request('whostmgr',
    {
        'module' => 'LastLogin',
        'func' => 'lastlogin',
        'user' => 'someuser'
    }
  );
  # Pass parameters to an API1 query
  $cp->cpanel_api1_request('cpanel',
    {
        'module' => 'Mysql',
        'func' => 'adduserdb',
    },
    [ 'somedb', 'somedbuser', 'ALL' ]
  );

  # perform an HTTP GET request against a URL
  $cp->api_request('whostmgr', '/xml-api/loadavg', 'GET');

  # perform an HTTP GET request with parameters
  $cp->api_request('whostmgr', '/xml-api/createacct', 'GET', {'username' => 'someuser', domain => 'domain.com'} );

  # perform an HTTP POST request (with parameters)
  $cp->api_request('whostmgr', '/xml-api/createacct', 'POST', {'username' => 'someuser', domain => 'domain.com'} );

=head1 DESCRIPTION

cPanel::PublicAPI is a supported interface for interacting with cPanel's APIs over HTTP.
This allows you to query either WHM or cPanel accounts from a perl interface.  The purpose
of this module is to provide an easy-to-use interface into cPanel's various APIs without
requiring much knowledge of how they work.

=head2 Object Construction

a cPanel::PublicAPI object is constructed with the new() method.

  my $publicapi = cPanel::PublicAPI->new();

When passed no parameters, this will create the object using the accesshash in ~/.accesshash. If no .accesshash file exists, it will attempt to use the REMOTE_PASS environment variable. If the REMOTE_PASS variable is not defined, object creation will error out.

=head3 new() parameters

options for new() are specified as a hash reference, the following parameters are supported:

=over

=item * user - The username to authenticate as.

=item * pass - The password to use for authentication.

=item * accesshash - The accesshash to use for authentication (WHM only).

=item * api_token - The API token to use for authentication.

=item * timeout - The length of time (in seconds) before an http request should time out.  Default to 300.

=item * ip - The IP to be queried.  defaults to 127.0.0.1, if host is defined it will take precedence over the 'ip' parameter.

=item * host - The hostname to be queried.  This will take precedence over the 'ip' parameter.

=item * usessl - 1 or 0, Indicates whether communication should be performed over SSL or not (default to 1).

=item * ssl_verify_mode - 1 or 0, Indicates whether to verify SSL certificates or not.  (default to 1).

=item * error_log - Path to where you want debug and error loggin