Laravel Chilkat Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require honlapbirodalom/laravel-chilkat
   php artisan vendor:publish --tag="chilkat-config"
   

   Publish the config file to config/chilkat.php and update credentials (e.g., Chilkat license key).

2. First Use Case: Use the Chilkat facade to interact with Chilkat's core functionality:

   use HonlapBirodalom\LaravelChilkat\Facades\Chilkat;
   
   $chilkat = new Chilkat();
   $success = $chilkat->UnlockComponent("Anything for 30-day trial");
   if (!$success) {
       throw new \RuntimeException("Failed to unlock: " . $chilkat->LastErrorText);
   }
   

3. Key Entry Points:

   • Check config/chilkat.php for default settings (e.g., timeout, debug).
   • Review the Chilkat PHP API docs for available classes (e.g., CkHttp, CkFtp2, CkZip).

Implementation Patterns

Common Workflows

1. HTTP Requests: Use CkHttp for REST APIs, file downloads, or uploads:

   $http = Chilkat::http();
   $response = $http->QuickGetStr("https://api.example.com/data");
   if ($http->get_LastMethodSuccess() !== true) {
       throw new \RuntimeException($http->LastErrorText);
   }
   

2. SFTP/FTPS: Leverage CkSsh or CkFtp2 for secure file transfers:

   $ftp = Chilkat::ftp2();
   $ftp->Hostname = "sftp.example.com";
   $ftp->Username = "user";
   $ftp->Password = "pass";
   $success = $ftp->Connect();
   if (!$success) {
       throw new \RuntimeException($ftp->LastErrorText);
   }
   $ftp->PutFile("local.txt", "remote.txt");
   

3. Email Handling: Use CkMailMan or CkMime for SMTP/IMAP operations:

   $mailman = Chilkat::mailMan();
   $mailman->SmtpHost = "smtp.example.com";
   $mailman->SmtpUsername = "user";
   $mailman->SmtpPassword = "pass";
   $success = $mailman->SendEmail("to@example.com", "subject", "body");
   

4. Zip/Compression: Compress/decompress files with CkZip:

   $zip = Chilkat::zip();
   $zip->NewZip("archive.zip");
   $zip->AppendFile("archive.zip", "file.txt", false);
   $zip->WriteZipAndClose();
   

Integration Tips

• Service Providers: Bind Chilkat classes to Laravel's container for dependency injection:

  $this->app->bind('chilkat.http', function () {
      return Chilkat::http();
  });
  

• Jobs/Queues: Offload long-running tasks (e.g., large file transfers) to Laravel queues.
• Events: Trigger custom events (e.g., Chilkat\Events\TransferCompleted) after operations.
• Logging: Enable debug mode in config/chilkat.php to log errors:

  'debug' => env('CHILKAT_DEBUG', false),
  

Gotchas and Tips

Pitfalls

1. License Management:

   • Chilkat requires a license for production use. Trial keys expire after 30 days.
   • Store licenses securely (e.g., Laravel's .env or a secrets manager).

2. Error Handling:

   • Always check LastMethodSuccess or LastErrorText after operations:

     if (!$chilkat->get_LastMethodSuccess()) {
         \Log::error($chilkat->LastErrorText);
         throw new \RuntimeException("Chilkat operation failed");
     }
     

   • Chilkat errors may not extend Laravel’s exception hierarchy—wrap them explicitly.

3. Memory Leaks:

   • Chilkat PHP objects are not garbage-collected automatically. Manually release resources:

     $http->Dispose();
     

   • Use try-finally blocks for critical operations:

     try {
         $http->QuickGetStr("https://example.com");
     } finally {
         $http->Dispose();
     }
     

4. Thread Safety:

   • Chilkat PHP is not thread-safe. Avoid sharing instances across requests (e.g., in Laravel’s singleton container). Create new instances per request or use a factory pattern.

5. Configuration Quirks:

   • Timeouts (e.g., connectTimeout, readTimeout) are in milliseconds by default. Adjust in config/chilkat.php:

     'timeouts' => [
         'connect' => 30000, // 30 seconds
         'read'    => 60000, // 60 seconds
     ],
     

Debugging Tips

1. Enable Debug Mode: Set 'debug' => true in config/chilkat.php to log Chilkat’s internal messages to Laravel’s log.

2. Verify Chilkat Version: Check compatibility with your Laravel version (see README compatibility table). Mismatches may cause crashes.

3. Common Issues:

   • SSL/TLS Errors: Ensure CkHttp has SslProtocols set (e.g., TLS1.2):

     $http->SslProtocols = "tls1.2";
     

   • Proxy Settings: Configure via HttpProxyHost, HttpProxyPort, etc., if behind a proxy.
   • File Paths: Use absolute paths for file operations to avoid permission issues.

Extension Points

1. Custom Facades: Extend the Chilkat facade to add domain-specific methods:

   namespace App\Facades;
   
   use Illuminate\Support\Facades\Facade;
   
   class CustomChilkat extends Facade {
       protected static function getFacadeAccessor() { return 'chilkat'; }
   
       public static function sendSftpFile($localPath, $remotePath) {
           $ftp = app('chilkat.ftp2');
           // Custom logic...
           return $ftp->PutFile($localPath, $remotePath);
       }
   }
   

2. Middleware: Add middleware to validate Chilkat operations (e.g., license checks):

   namespace App\Http\Middleware;
   
   use Closure;
   use HonlapBirodalom\LaravelChilkat\Facades\Chilkat;
   
   class ChilkatLicenseCheck {
       public function handle($request, Closure $next) {
           $chilkat = new Chilkat();
           if (!$chilkat->UnlockComponent(env('CHILKAT_LICENSE'))) {
               abort(503, "Chilkat license invalid");
           }
           return $next($request);
       }
   }
   

3. Testing: Mock Chilkat in tests using Laravel’s partialMock:

   $mockHttp = $this->partialMock(CkHttp::class, ['QuickGetStr']);
   $mockHttp->shouldReceive('QuickGetStr')->andReturn("mocked response");
   $this->app->instance('chilkat.http', $mockHttp);