Hellosign Php Sdk Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require hellosign/hellosign-php-sdk:^3.8.0

Verify the package loads in composer.json under require with the updated version constraint.

2. First Use Case: Sending a Signature Request (PHP 8.1 Compatible)

   use HelloSign\Client;
   use HelloSign\Configuration;
   
   $config = Configuration::getDefaultConfiguration()
       ->setApiKey('YOUR_API_KEY'); // From HelloSign Dashboard
   
   $client = new Client($config);
   
   $request = new \HelloSign\Model\SignRequest();
   $request->setTitle('Laravel Contract')
           ->setRequesterEmail('user@example.com')
           ->addSigner((new \HelloSign\Model\Signer())
               ->setEmail('signer@example.com')
               ->setName('John Doe')
           )
           ->addDocument((new \HelloSign\Model\Document())
               ->setFileUrl('https://example.com/contract.pdf')
               ->setName('Contract.pdf')
           );
   
   $response = $client->getSignRequestsApi()->createSignRequest($request);
   

3. Where to Look First

   • API Docs: HelloSign API Reference (cross-check with SDK methods).
   • SDK Source: Browse src/Api for available endpoints.
   • Next-Gen SDK Preview: Explore the OpenAPI-based preview for future migrations.
   • Examples: Check the examples folder (if available).

Implementation Patterns

Workflows

1. Signature Request Lifecycle (Updated for PHP 8.1)

   • Create: Use createSignRequest() with a SignRequest object (now compatible with PHP 8.1).
   • Track Status: Poll getSignRequest() with the signRequestId to check completion.

     $request = $client->getSignRequestsApi()->getSignRequest('SIGN_REQUEST_ID');
     if ($request->getStatus() === 'completed') {
         $file = $client->getSignRequestsApi()->getDocument('SIGN_REQUEST_ID', 'DOCUMENT_ID');
     }
     

   • Webhooks: Configure via HelloSign Dashboard (not SDK-managed) to avoid polling.

2. Document Handling (PHP 8.1 Compatible)

   • Upload files via fileUrl (public URL) or base64-encoded content:

     $document = (new \HelloSign\Model\Document())
         ->setFileUrl('https://example.com/file.pdf');
     // OR
     $document->setFileBase64('base64_encoded_string');
     

3. Template Reuse (PHP 8.1 Compatible)

   • Save a SignRequest as a template:

     $template = $client->getTemplatesApi()->createTemplate($request);
     // Later, reuse with:
     $client->getTemplatesApi()->signTemplate('TEMPLATE_ID', ['signer_emails' => [...]]);
     

Integration Tips

• Laravel Service Provider (PHP 8.1) Bind the client to the container for dependency injection:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(Client::class, function ($app) {
          $config = Configuration::getDefaultConfiguration()
              ->setApiKey(config('services.hellosign.key'));
          return new Client($config);
      });
  }
  

  Configure API key in .env:

  HELLOSIGN_KEY=your_api_key_here
  

• Queue Delayed Actions (PHP 8.1) Use Laravel Queues to defer status checks or webhook processing:

  // Dispatch a job to check status later
  CheckSignRequestStatus::dispatch($signRequestId)->delay(now()->addMinutes(5));
  

• Error Handling (PHP 8.1) Wrap API calls in try-catch:

  try {
      $response = $client->getSignRequestsApi()->createSignRequest($request);
  } catch (\HelloSign\ApiException $e) {
      Log::error('HelloSign API Error: ' . $e->getMessage());
      return back()->with('error', 'Failed to send signature request.');
  }
  

Gotchas and Tips

Pitfalls

1. Deprecated Endpoints (Critical)

   • This is likely the last major update for this SDK. Plan for migration to the next-gen OpenAPI SDK after this release.
   • Verify endpoints against HelloSign’s current API. Example:
     • getSignRequest() may not support all status fields in newer API versions.

2. PHP Version Compatibility

   • PHP 7.4 support dropped. Ensure your Laravel app uses PHP 8.0 or 8.1 (or upgrade).
   • Test thoroughly with PHP 8.1 due to strict typing changes.

3. Rate Limiting

   • HelloSign enforces rate limits. Cache responses aggressively:

     $request = Cache::remember("hellosign_request_{$id}", now()->addMinutes(5), fn() =>
         $client->getSignRequestsApi()->getSignRequest($id)
     );
     

4. File Size Limits

   • Documents > 50MB may fail silently. Validate file sizes before upload:

     if ($file->getSize() > 50 * 1024 * 1024) {
         throw new \Exception('File too large. Max 50MB allowed.');
     }
     

5. Webhook Delays

   • Webhooks may arrive late or not at all. Implement a fallback polling mechanism.

Debugging

• Enable SDK Debugging (PHP 8.1)

  $config->setDebug(true); // Logs HTTP requests/responses
  

  Check logs for HelloSign entries.

• Validate API Key Test with a dummy request first:

  $client->getAccountsApi()->getAccount(); // Should return account details
  

• PHP 8.1 Strict Typing Ensure all model properties are type-hinted correctly. Example:

  $signer = new \HelloSign\Model\Signer();
  $signer->setEmail('user@example.com'); // Ensure no type mismatches
  

Extension Points

1. Custom Signer Fields (PHP 8.1) Extend the Signer model to add custom fields:

   $signer = new \HelloSign\Model\Signer();
   $signer->setEmail('user@example.com')
          ->setName('Custom Name')
          ->setCustomFields(['department' => 'Engineering']); // Use metadata
   

2. PDF Annotations (PHP 8.1) Use SignHere tags in documents:

   $document->setSignHereTags([
       (new \HelloSign\Model\SignHere())
           ->setAnchorX(100)
           ->setAnchorY(200)
           ->setAnchorUnit('px')
           ->setAnchorType('corner')
           ->setPageNumber(1)
   ]);
   

3. Laravel Notifications (PHP 8.1) Integrate with Laravel Notifications for signer reminders:

   use Illuminate\Notifications\Notification;
   
   class SignatureReminder extends Notification
   {
       public function via($notifiable)
       {
           return ['mail'];
       }
   
       public function toMail($notifiable)
       {
           return (new MailMessage)
               ->subject('Please Sign Your Document')
               ->line('Your document is awaiting your signature.');
       }
   }
   

Config Quirks

• Base Path (Sandbox/Production) Override the API base path for sandbox testing:

  $config->setHost('https://api.sandbox.hellosign.com'); // Sandbox
  

• Timeouts (PHP 8.1) Increase timeout for large files:

  $config->setConnectTimeout(30); // 30 seconds
  $config->setReadTimeout(60);    // 60 seconds
  

• Migration Reminder Add a comment in your AppServiceProvider to track migration status:

  // TODO: Migrate to hellosign/hellosign-php-sdk (OpenAPI branch) after deprecation
  

Migration Path

• Preview Next-Gen SDK: Test the [OpenAPI-based preview](https://github.com/hellosign/hellosign-php