Cpanel Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ap/cpanel-bundle 'dev-master'
   

   Note: Use dev-master as the latest stable release is outdated (2015).

2. Enable Bundle Register in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3-):

   return [
       // ...
       Ap\CpanelBundle\ApCpanelBundle::class => ['all' => true],
   ];
   

3. Configuration Add to config/packages/ap_cpanel.yaml (Symfony 4+) or config.yml:

   ap_cpanel:
       domain: 'yourdomain.com'
       whmusername: 'your_whm_username'
       whmhash: 'your_whm_api_hash'
   

4. First Use Case Inject the API service in a controller/service:

   use Ap\CpanelBundle\Service\CpanelApi;
   
   public function listAccounts(CpanelApi $cpanel)
   {
       $response = $cpanel->listaccts()->exec();
       $accounts = json_decode($response, true);
       return $this->render('accounts/index.html.twig', ['accounts' => $accounts]);
   }
   

Implementation Patterns

Core Workflows

1. API Method Chaining Chain methods for complex requests (e.g., filtering accounts):

   $cpanel->listaccts()
           ->withParam('sortby', 'totalquota')
           ->withParam('sortorder', 'desc')
           ->exec();
   

2. Parameter Handling Use withParam() for dynamic inputs:

   $cpanel->addpop()
           ->withParam('domain', $domain)
           ->withParam('email', $email)
           ->withParam('password', $password)
           ->exec();
   

3. Response Processing Decode JSON responses consistently:

   $rawResponse = $cpanel->showuser()->exec();
   $userData = json_decode($rawResponse, true);
   

4. Error Handling Wrap API calls in try-catch blocks:

   try {
       $result = $cpanel->someMethod()->exec();
   } catch (\Exception $e) {
       $this->addFlash('error', 'Cpanel API Error: ' . $e->getMessage());
   }
   

Integration Tips

• Dependency Injection Prefer constructor injection for services:

  public function __construct(private CpanelApi $cpanel) {}
  

• Command-Line Usage Create a console command for bulk operations:

  use Symfony\Component\Console\Command\Command;
  use Symfony\Component\Console\Input\InputInterface;
  use Symfony\Component\Console\Output\OutputInterface;
  
  class SuspendAccountsCommand extends Command
  {
      protected static $defaultName = 'cpanel:suspend-accounts';
  
      public function __construct(private CpanelApi $cpanel) {}
  
      protected function execute(InputInterface $input, OutputInterface $output): int
      {
          $accounts = $this->cpanel->listaccts()->exec();
          // Suspend logic here
      }
  }
  

• Event Listeners Trigger actions on account changes (e.g., post-creation):

  use Ap\CpanelBundle\Event\CpanelEvent;
  
  public function onAccountCreated(CpanelEvent $event)
  {
      $account = $event->getData();
      // Send welcome email, etc.
  }
  

Gotchas and Tips

Common Pitfalls

1. Deprecated Methods The bundle is outdated (2015). Some WHM API methods may no longer exist or require updates. Verify against cPanel API docs.

2. Authentication Failures

   • Ensure whmhash is correct (use WHM’s API hash generator).
   • Test credentials manually via curl first:

     curl -k https://yourdomain.com:2087/json-api/cpanel?cpanel_jsonapi_user=USER&cpanel_jsonapi_apiversion=2&cpanel_jsonapi_module=UserAdmin&cpanel_jsonapi_func=listaccts
     

3. SSL/TLS Issues The bundle may not handle self-signed certificates. Add this to config/packages/monolog.yaml:

   handlers:
       cpanel:
           type: stream
           path: php://stdout
           level: debug
           channels: ["cpanel"]
   

4. Rate Limiting WHM may throttle requests. Implement retries with exponential backoff:

   use Symfony\Component\Stopwatch\Stopwatch;
   
   $stopwatch = new Stopwatch();
   $event = $stopwatch->start('cpanel_request');
   
   try {
       $response = $cpanel->someMethod()->exec();
   } catch (\Exception $e) {
       if ($stopwatch->getEvent('cpanel_request')->getDuration() < 1000) {
           sleep(1); // Retry after 1 second
           retry();
       }
   }
   

Debugging Tips

1. Enable Verbose Logging Add to config/packages/dev/monolog.yaml:

   handlers:
       cpanel:
           type: stream
           path: "%kernel.logs_dir%/cpanel.log"
           level: debug
           channels: ["cpanel"]
   

2. Raw Response Inspection Log raw responses to debug:

   $rawResponse = $cpanel->someMethod()->exec();
   file_put_contents(
       'debug/cpanel_raw_response.log',
       print_r($rawResponse, true)
   );
   

3. Parameter Validation Validate inputs before passing to the API:

   if (empty($domain) || !filter_var($domain, FILTER_VALIDATE_DOMAIN)) {
       throw new \InvalidArgumentException('Invalid domain');
   }
   

Extension Points

1. Custom API Methods Extend the bundle by creating a decorator:

   use Ap\CpanelBundle\Service\CpanelApi;
   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class CustomCpanelApi extends CpanelApi
   {
       public function customMethod()
       {
           return $this->callApi('UserAdmin', 'custom_func', []);
       }
   }
   

   Register as a service in config/services.yaml:

   services:
       App\Service\CustomCpanelApi:
           decorates: 'ap_cpanel.api'
           arguments: ['@App\Service\CustomCpanelApi.inner']
   

2. Event Dispatching Listen for built-in events (e.g., cpanel.account.created):

   use Ap\CpanelBundle\Event\CpanelEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class AccountEventSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'cpanel.account.created' => 'onAccountCreated',
           ];
       }
   
       public function onAccountCreated(CpanelEvent $event)
       {
           // Handle event
       }
   }
   

3. Configuration Overrides Override settings per environment:

   # config/packages/ap_cpanel_test.yaml
   ap_cpanel:
       domain: '%env(CPANEL_TEST_DOMAIN)%'
       whmhash: '%env(CPANEL_TEST_HASH)%'