diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0c109c5..c541c40 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -69,6 +69,37 @@ jobs:
- name: Run tests
run: go test -v ./...
+ test-php:
+ name: Test PHP SDK
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: packages/php-sdk
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up PHP 8.1
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: '8.1'
+ extensions: json, fileinfo, dom, xml, mbstring, curl
+ coverage: none
+
+ - name: Validate composer.json
+ run: composer validate --strict
+
+ - name: Install dependencies
+ run: composer install --prefer-dist --no-progress
+
+ - name: Run tests
+ run: composer test
+
+ - name: Run PHPStan
+ run: composer phpstan
+
+ - name: Check code style
+ run: composer cs-fix -- --dry-run --diff
+
test-java:
name: Test Java SDK
runs-on: ubuntu-latest
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
deleted file mode 100644
index 8452b0f..0000000
--- a/.github/workflows/claude-code-review.yml
+++ /dev/null
@@ -1,57 +0,0 @@
-name: Claude Code Review
-
-on:
- pull_request:
- types: [opened, synchronize]
- # Optional: Only run on specific file changes
- # paths:
- # - "src/**/*.ts"
- # - "src/**/*.tsx"
- # - "src/**/*.js"
- # - "src/**/*.jsx"
-
-jobs:
- claude-review:
- # Optional: Filter by PR author
- # if: |
- # github.event.pull_request.user.login == 'external-contributor' ||
- # github.event.pull_request.user.login == 'new-developer' ||
- # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
- runs-on: ubuntu-latest
- permissions:
- contents: read
- pull-requests: read
- issues: read
- id-token: write
-
- steps:
- - name: Checkout repository
- uses: actions/checkout@v4
- with:
- fetch-depth: 1
-
- - name: Run Claude Code Review
- id: claude-review
- uses: anthropics/claude-code-action@v1
- with:
- claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
- prompt: |
- REPO: ${{ github.repository }}
- PR NUMBER: ${{ github.event.pull_request.number }}
-
- Please review this pull request and provide feedback on:
- - Code quality and best practices
- - Potential bugs or issues
- - Performance considerations
- - Security concerns
- - Test coverage
-
- Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
-
- Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
-
- # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
- # or https://code.claude.com/docs/en/cli-reference for available options
- claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
-
diff --git a/.github/workflows/publish-php.yml b/.github/workflows/publish-php.yml
new file mode 100644
index 0000000..2ab16d0
--- /dev/null
+++ b/.github/workflows/publish-php.yml
@@ -0,0 +1,48 @@
+name: Publish PHP SDK
+
+on:
+ release:
+ types: [created]
+
+jobs:
+ validate:
+ runs-on: ubuntu-latest
+ if: startsWith(github.event.release.tag_name, 'php-sdk-v')
+ defaults:
+ run:
+ working-directory: packages/php-sdk
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up PHP 8.1
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: '8.1'
+ extensions: json, fileinfo, dom, xml, mbstring, curl
+ coverage: none
+
+ - name: Validate composer.json
+ run: composer validate --strict
+
+ - name: Install dependencies
+ run: composer install --prefer-dist --no-progress
+
+ - name: Run tests
+ run: composer test
+
+ - name: Run PHPStan
+ run: composer phpstan
+
+ - name: Check code style
+ run: composer cs-fix -- --dry-run --diff
+
+ notify-packagist:
+ needs: validate
+ runs-on: ubuntu-latest
+ if: startsWith(github.event.release.tag_name, 'php-sdk-v')
+ steps:
+ - name: Notify Packagist
+ run: |
+ echo "✅ PHP SDK validated and ready"
+ echo "📦 Packagist will automatically detect the new tag and publish the package"
+ echo "🔗 Check status at: https://packagist.org/packages/turbodocx/sdk"
diff --git a/README.md b/README.md
index cf27a78..2603846 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,7 @@ Comprehensive SDKs, detailed documentation, and responsive support. Ship faster
|:---------|:--------|:--------|:-----|
| 
**JavaScript/TypeScript** | [@turbodocx/sdk](./packages/js-sdk) | `npm install @turbodocx/sdk` | [View →](./packages/js-sdk#readme) |
| 
**Python** | [turbodocx-sdk](./packages/py-sdk) | `pip install turbodocx-sdk` | [View →](./packages/py-sdk#readme) |
+| 
**PHP** | [turbodocx/sdk](./packages/php-sdk) | `composer require turbodocx/sdk` | [View →](./packages/php-sdk#readme) |
| 
**Go** | [turbodocx-sdk](./packages/go-sdk) | `go get github.com/turbodocx/sdk` | [View →](./packages/go-sdk#readme) |
| 
**Java** | [com.turbodocx:sdk](./packages/java-sdk) | [Maven Central](https://search.maven.org/artifact/com.turbodocx/sdk) | [View →](./packages/java-sdk#readme) |
@@ -68,9 +69,13 @@ Comprehensive SDKs, detailed documentation, and responsive support. Ship faster
| 
**Ruby** | 🚧 In Progress |
| 
**PowerShell** | 🚧 In Progress |
-> 🔌 **Low-code?** Check out our [n8n community node](https://www.npmjs.com/package/@turbodocx/n8n-nodes-turbodocx) for no-code/low-code workflows!
->
-> 📝 **Microsoft Word?** Get [TurboDocx Writer](https://appsource.microsoft.com/en-us/product/office/WA200007397) from the Microsoft AppSource marketplace!
+## 🌐 Explore the TurboDocx Ecosystem
+
+| Package | Links | Description |
+|---------|-------|-------------|
+| @turbodocx/html-to-docx | [](https://www.npmjs.com/package/@turbodocx/html-to-docx) [](https://github.com/turbodocx/html-to-docx) | Convert HTML to DOCX with the fastest JavaScript library |
+| n8n-nodes-turbodocx | [](https://www.npmjs.com/package/@turbodocx/n8n-nodes-turbodocx) [](https://github.com/turbodocx/n8n-nodes-turbodocx) | n8n community node for TurboDocx API & TurboSign |
+| TurboDocx Writer | [](https://appsource.microsoft.com/en-us/product/office/WA200007397) | Official Microsoft Word add-in for document automation |
---
@@ -114,6 +119,14 @@ go get github.com/turbodocx/sdk
```
+
+PHP
+
+```bash
+composer require turbodocx/sdk
+```
+
+
Java
@@ -291,6 +304,7 @@ await TurboSign.resend(documentId, ['recipient-uuid']);
|:----|:----------------|
| JavaScript/TypeScript | Node.js 16+ |
| Python | Python 3.9+ |
+| PHP | PHP 8.1+ |
| Go | Go 1.21+ |
| Java | Java 11+ |
@@ -322,30 +336,24 @@ We're looking for community maintainers for each SDK. Interested? [Open an issue
diff --git a/packages/php-sdk/.gitignore b/packages/php-sdk/.gitignore
new file mode 100644
index 0000000..fec9932
--- /dev/null
+++ b/packages/php-sdk/.gitignore
@@ -0,0 +1,29 @@
+# Composer
+/vendor/
+composer.lock
+
+# PHPUnit
+/coverage/
+.phpunit.result.cache
+
+# PHPStan
+/phpstan.result
+
+# PHP CS Fixer
+.php-cs-fixer.cache
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Build
+/build/
+/dist/
+
+# Environment
+.env
+.env.local
diff --git a/packages/php-sdk/.php-cs-fixer.dist.php b/packages/php-sdk/.php-cs-fixer.dist.php
new file mode 100644
index 0000000..00c6824
--- /dev/null
+++ b/packages/php-sdk/.php-cs-fixer.dist.php
@@ -0,0 +1,30 @@
+setParallelConfig(ParallelConfigFactory::detect()) // @TODO 4.0 no need to call this manually
+ ->setRiskyAllowed(false)
+ ->setRules([
+ '@auto' => true
+ ])
+ // 💡 by default, Fixer looks for `*.php` files excluding `./vendor/` - here, you can groom this config
+ ->setFinder(
+ (new Finder())
+ // 💡 root folder to check
+ ->in(__DIR__)
+ // 💡 additional files, eg bin entry file
+ // ->append([__DIR__.'/bin-entry-file'])
+ // 💡 folders to exclude, if any
+ // ->exclude([/* ... */])
+ // 💡 path patterns to exclude, if any
+ // ->notPath([/* ... */])
+ // 💡 extra configs
+ // ->ignoreDotFiles(false) // true by default in v3, false in v4 or future mode
+ // ->ignoreVCS(true) // true by default
+ )
+;
diff --git a/packages/php-sdk/CHANGELOG.md b/packages/php-sdk/CHANGELOG.md
new file mode 100644
index 0000000..bca0621
--- /dev/null
+++ b/packages/php-sdk/CHANGELOG.md
@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-17
+
+### Added
+- Initial PHP SDK implementation with TypeScript-equivalent strong typing
+- TurboSign module with 8 methods for digital signatures
+- Support for coordinate-based and template anchor-based field positioning
+- Strong typing with PHP 8.1+ enums and typed properties
+- Comprehensive exception hierarchy for error handling (6 exception types)
+- Automatic file type detection using magic bytes (PDF/DOCX/PPTX)
+- PHPStan level 8 static analysis support (zero errors)
+- PSR-4 autoloading and PSR-12 code formatting
+- Industry-standard dependencies (Guzzle 7.8, PHPUnit 10.5)
+
+### Features
+- `TurboSign::configure()` - Configure SDK with API credentials
+- `TurboSign::sendSignature()` - Send signature request and immediately send emails
+- `TurboSign::createSignatureReviewLink()` - Create review link without sending emails
+- `TurboSign::getStatus()` - Get document status
+- `TurboSign::download()` - Download signed document
+- `TurboSign::void()` - Void a document
+- `TurboSign::resend()` - Resend signature request emails
+- `TurboSign::getAuditTrail()` - Get audit trail for a document
+
+### Type System
+- 4 backed enums: `SignatureFieldType`, `DocumentStatus`, `RecipientStatus`, `FieldPlacement`
+- 10 immutable DTOs: `Recipient`, `Field`, `TemplateConfig`, Request/Response classes
+- 6 custom exceptions with typed properties
+
+### Testing & Quality
+- 31 unit tests with 82 assertions (100% passing)
+- PHPStan level 8 static analysis (0 errors)
+- PSR-12 code formatting compliance
+- Comprehensive test coverage for all core components
+
+### Documentation
+- Complete README with API reference and examples
+- 3 working example files (simple, basic, advanced)
+- PHPDoc annotations for all classes and methods
+- TypeScript → PHP equivalents mapping
+
+[Unreleased]: https://github.com/TurboDocx/SDK/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/TurboDocx/SDK/releases/tag/v0.1.0
diff --git a/packages/php-sdk/LICENSE b/packages/php-sdk/LICENSE
new file mode 100644
index 0000000..f89599a
--- /dev/null
+++ b/packages/php-sdk/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TurboDocx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/php-sdk/README.md b/packages/php-sdk/README.md
new file mode 100644
index 0000000..d1f3d32
--- /dev/null
+++ b/packages/php-sdk/README.md
@@ -0,0 +1,616 @@
+# TurboDocx PHP SDK
+
+**Official PHP SDK for TurboDocx - Digital signatures, document generation, and AI-powered workflows**
+
+[](https://packagist.org/packages/turbodocx/sdk)
+[](https://packagist.org/packages/turbodocx/sdk)
+[](./LICENSE)
+
+[Documentation](https://www.turbodocx.com/docs) • [API Reference](https://www.turbodocx.com/docs/api) • [Examples](#examples) • [Discord](https://discord.gg/NYKwz4BcpX)
+
+---
+
+## Features
+
+- 🚀 **Production-Ready** — Battle-tested, processing thousands of documents daily
+- 📝 **Strong Typing** — PHP 8.1+ enums and typed properties with PHPStan level 8
+- ⚡ **Modern PHP** — Readonly classes, named parameters, match expressions
+- 🔄 **Industry Standard** — Guzzle HTTP client, PSR standards compliance
+- 🛡️ **Type-safe** — Catch errors at development time with static analysis
+- 🤖 **100% n8n Parity** — Same operations as our n8n community nodes
+
+---
+
+## Requirements
+
+- PHP 8.1 or higher
+- Composer
+- ext-json
+- ext-fileinfo
+
+---
+
+## Installation
+
+```bash
+composer require turbodocx/sdk
+```
+
+---
+
+## Quick Start
+
+```php
+ 100, 'height' => 30]
+ )
+ )
+ ],
+ file: file_get_contents('contract.pdf'),
+ documentName: 'Partnership Agreement'
+ )
+);
+
+echo "Document ID: {$result->documentId}\n";
+```
+
+---
+
+## Configuration
+
+```php
+use TurboDocx\TurboSign;
+use TurboDocx\Config\HttpClientConfig;
+
+// Basic configuration (REQUIRED)
+TurboSign::configure(new HttpClientConfig(
+ apiKey: 'your-api-key', // REQUIRED
+ orgId: 'your-org-id', // REQUIRED
+ senderEmail: 'you@company.com', // REQUIRED - reply-to address for signature requests
+ senderName: 'Your Company' // OPTIONAL but strongly recommended
+));
+
+// With custom options
+TurboSign::configure(new HttpClientConfig(
+ apiKey: 'your-api-key',
+ orgId: 'your-org-id',
+ senderEmail: 'you@company.com',
+ senderName: 'Your Company',
+ baseUrl: 'https://custom-api.example.com' // Optional: custom API endpoint
+));
+```
+
+**Important:** `senderEmail` is **REQUIRED**. This email will be used as the reply-to address for signature request emails. Without it, emails will default to "API Service User via TurboSign". The `senderName` is optional but strongly recommended for a professional appearance.
+
+### Environment Variables
+
+We recommend using environment variables for your configuration:
+
+```bash
+# .env
+TURBODOCX_API_KEY=your-api-key
+TURBODOCX_ORG_ID=your-org-id
+TURBODOCX_SENDER_EMAIL=you@company.com
+TURBODOCX_SENDER_NAME=Your Company Name
+```
+
+```php
+TurboSign::configure(new HttpClientConfig(
+ apiKey: getenv('TURBODOCX_API_KEY'),
+ orgId: getenv('TURBODOCX_ORG_ID'),
+ senderEmail: getenv('TURBODOCX_SENDER_EMAIL'),
+ senderName: getenv('TURBODOCX_SENDER_NAME')
+));
+
+// Or use auto-configuration from environment
+TurboSign::configure(HttpClientConfig::fromEnvironment());
+```
+
+---
+
+## API Reference
+
+### TurboSign
+
+#### `createSignatureReviewLink()`
+
+Upload a document for review without sending signature emails. Returns a preview URL.
+
+```php
+use TurboDocx\Types\Requests\CreateSignatureReviewLinkRequest;
+
+$result = TurboSign::createSignatureReviewLink(
+ new CreateSignatureReviewLinkRequest(
+ recipients: [
+ new Recipient('John Doe', 'john@example.com', 1)
+ ],
+ fields: [
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 500,
+ width: 200,
+ height: 50
+ )
+ ],
+ fileLink: 'https://example.com/contract.pdf', // Or use file: for upload
+ documentName: 'Service Agreement', // Optional
+ documentDescription: 'Q4 Contract', // Optional
+ ccEmails: ['legal@acme.com'] // Optional
+ )
+);
+
+echo "Preview URL: {$result->previewUrl}\n";
+echo "Document ID: {$result->documentId}\n";
+```
+
+#### `sendSignature()`
+
+Upload a document and immediately send signature request emails.
+
+```php
+use TurboDocx\Types\Requests\SendSignatureRequest;
+
+$result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ recipients: [
+ new Recipient('Alice', 'alice@example.com', 1),
+ new Recipient('Bob', 'bob@example.com', 2) // Signs after Alice
+ ],
+ fields: [
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'alice@example.com',
+ page: 1,
+ x: 100,
+ y: 500,
+ width: 200,
+ height: 50
+ ),
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'bob@example.com',
+ page: 1,
+ x: 100,
+ y: 600,
+ width: 200,
+ height: 50
+ )
+ ],
+ file: file_get_contents('contract.pdf')
+ )
+);
+
+// Get recipient sign URLs
+$status = TurboSign::getStatus($result->documentId);
+foreach ($status->recipients as $recipient) {
+ echo "{$recipient->name}: {$recipient->signUrl}\n";
+}
+```
+
+#### `getStatus()`
+
+Check the current status of a document.
+
+```php
+$status = TurboSign::getStatus('doc-uuid-here');
+
+echo "Document Status: {$status->status->value}\n"; // 'pending', 'completed', 'voided'
+echo "Recipients:\n";
+
+// Check individual recipient status
+foreach ($status->recipients as $recipient) {
+ echo " {$recipient->name}: {$recipient->status->value}\n";
+ if ($recipient->signedAt) {
+ echo " Signed at: {$recipient->signedAt}\n";
+ }
+}
+```
+
+#### `download()`
+
+Download the signed PDF document.
+
+```php
+$pdfContent = TurboSign::download('doc-uuid-here');
+
+// Save to file
+file_put_contents('signed-contract.pdf', $pdfContent);
+
+// Or send as HTTP response
+header('Content-Type: application/pdf');
+header('Content-Disposition: attachment; filename="signed.pdf"');
+echo $pdfContent;
+```
+
+#### `void()`
+
+Cancel a signature request that hasn't been completed.
+
+```php
+use TurboDocx\Types\Responses\VoidDocumentResponse;
+
+$result = TurboSign::void('doc-uuid-here', 'Document needs to be revised');
+
+echo "Status: {$result->status}\n";
+echo "Voided at: {$result->voidedAt}\n";
+```
+
+#### `resend()`
+
+Resend signature request emails to specific recipients (or all).
+
+```php
+// Resend to specific recipients
+$result = TurboSign::resend('doc-uuid-here', ['recipient-id-1', 'recipient-id-2']);
+
+// Resend to all recipients
+$result = TurboSign::resend('doc-uuid-here', []);
+
+echo "Message: {$result->message}\n";
+```
+
+#### `getAuditTrail()`
+
+Get the complete audit trail for a document.
+
+```php
+$audit = TurboSign::getAuditTrail('doc-uuid-here');
+
+echo "Audit Trail:\n";
+foreach ($audit->entries as $entry) {
+ echo " {$entry->timestamp} - {$entry->event} by {$entry->actor}\n";
+ if ($entry->ipAddress) {
+ echo " IP: {$entry->ipAddress}\n";
+ }
+}
+```
+
+---
+
+## Field Types
+
+TurboSign supports 11 different field types:
+
+```php
+use TurboDocx\Types\SignatureFieldType;
+
+SignatureFieldType::SIGNATURE // Signature field
+SignatureFieldType::INITIAL // Initial field
+SignatureFieldType::DATE // Date stamp (auto-filled when signed)
+SignatureFieldType::TEXT // Free text input
+SignatureFieldType::FULL_NAME // Full name (auto-filled from recipient)
+SignatureFieldType::FIRST_NAME // First name
+SignatureFieldType::LAST_NAME // Last name
+SignatureFieldType::EMAIL // Email address
+SignatureFieldType::TITLE // Job title
+SignatureFieldType::COMPANY // Company name
+SignatureFieldType::CHECKBOX // Checkbox field
+```
+
+### Field Positioning
+
+TurboSign supports two ways to position fields:
+
+#### 1. Coordinate-based (Pixel Perfect)
+
+```php
+new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ page: 1, // Page number (1-indexed)
+ x: 100, // X coordinate
+ y: 500, // Y coordinate
+ width: 200, // Width in pixels
+ height: 50 // Height in pixels
+)
+```
+
+#### 2. Template Anchors (Dynamic)
+
+```php
+new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{signature1}', // Text to find in PDF
+ placement: FieldPlacement::REPLACE, // How to place the field
+ size: ['width' => 100, 'height' => 30]
+ )
+)
+```
+
+**Placement Options:**
+- `FieldPlacement::REPLACE` - Replace the anchor text
+- `FieldPlacement::BEFORE` - Place before the anchor
+- `FieldPlacement::AFTER` - Place after the anchor
+- `FieldPlacement::ABOVE` - Place above the anchor
+- `FieldPlacement::BELOW` - Place below the anchor
+
+### Advanced Field Options
+
+```php
+// Checkbox (pre-checked, readonly)
+new Field(
+ type: SignatureFieldType::CHECKBOX,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 600,
+ width: 20,
+ height: 20,
+ defaultValue: 'true', // Pre-checked
+ isReadonly: true // Cannot be unchecked
+)
+
+// Multiline text field
+new Field(
+ type: SignatureFieldType::TEXT,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 200,
+ width: 400,
+ height: 100,
+ isMultiline: true, // Allow multiple lines
+ required: true, // Field is required
+ backgroundColor: '#f0f0f0' // Background color
+)
+
+// Readonly text (pre-filled, non-editable)
+new Field(
+ type: SignatureFieldType::TEXT,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 300,
+ width: 300,
+ height: 30,
+ defaultValue: 'This text is pre-filled',
+ isReadonly: true
+)
+```
+
+---
+
+## File Input Methods
+
+TurboSign supports three ways to provide the document:
+
+### 1. Direct File Upload
+
+```php
+$result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ file: file_get_contents('contract.pdf'),
+ fileName: 'contract.pdf', // Optional
+ // ...
+ )
+);
+```
+
+### 2. File URL
+
+```php
+$result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ fileLink: 'https://example.com/contract.pdf',
+ // ...
+ )
+);
+```
+
+### 3. TurboDocx Deliverable ID
+
+```php
+$result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ deliverableId: 'deliverable-uuid-from-turbodocx',
+ // ...
+ )
+);
+```
+
+---
+
+## Examples
+
+### Example 1: Simple Template Anchors
+
+```php
+$result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ recipients: [
+ new Recipient('John Doe', 'john@example.com', 1)
+ ],
+ fields: [
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{signature1}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ )
+ )
+ ],
+ file: file_get_contents('contract.pdf')
+ )
+);
+```
+
+### Example 2: Sequential Signing
+
+```php
+$result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ recipients: [
+ new Recipient('Alice', 'alice@example.com', 1), // Signs first
+ new Recipient('Bob', 'bob@example.com', 2), // Signs after Alice
+ new Recipient('Carol', 'carol@example.com', 3) // Signs last
+ ],
+ fields: [
+ // Fields for each recipient...
+ ],
+ file: file_get_contents('contract.pdf')
+ )
+);
+```
+
+### Example 3: Status Polling
+
+```php
+$result = TurboSign::sendSignature(/* ... */);
+
+// Poll for completion
+while (true) {
+ sleep(2);
+ $status = TurboSign::getStatus($result->documentId);
+
+ if ($status->status === 'completed') {
+ echo "Document completed!\n";
+
+ // Download signed document
+ $signedPdf = TurboSign::download($result->documentId);
+ file_put_contents('signed.pdf', $signedPdf);
+ break;
+ }
+
+ echo "Status: {$status->status}\n";
+}
+```
+
+For more examples, see the [`examples/`](./examples) directory.
+
+---
+
+## Error Handling
+
+The SDK provides typed exceptions for different error scenarios:
+
+```php
+use TurboDocx\Exceptions\AuthenticationException;
+use TurboDocx\Exceptions\ValidationException;
+use TurboDocx\Exceptions\NotFoundException;
+use TurboDocx\Exceptions\RateLimitException;
+use TurboDocx\Exceptions\NetworkException;
+
+try {
+ $result = TurboSign::sendSignature(/* ... */);
+} catch (AuthenticationException $e) {
+ // 401 - Invalid API key or access token
+ echo "Authentication failed: {$e->getMessage()}\n";
+} catch (ValidationException $e) {
+ // 400 - Invalid request data
+ echo "Validation error: {$e->getMessage()}\n";
+} catch (NotFoundException $e) {
+ // 404 - Document not found
+ echo "Not found: {$e->getMessage()}\n";
+} catch (RateLimitException $e) {
+ // 429 - Rate limit exceeded
+ echo "Rate limit: {$e->getMessage()}\n";
+} catch (NetworkException $e) {
+ // Network/connection error
+ echo "Network error: {$e->getMessage()}\n";
+}
+```
+
+All exceptions extend `TurboDocxException` and include:
+- `statusCode` (HTTP status code, if applicable)
+- `errorCode` (Error code string, e.g., 'AUTHENTICATION_ERROR')
+- `message` (Human-readable error message)
+
+---
+
+## Testing
+
+The SDK includes comprehensive tests and static analysis:
+
+```bash
+# Run unit tests
+composer test
+
+# Run with coverage
+composer test:coverage
+
+# Run static analysis (PHPStan level 8)
+composer phpstan
+
+# Fix code style (PSR-12)
+composer cs-fix
+```
+
+### Quality Metrics
+
+- ✅ **31 unit tests** with 82 assertions (100% passing)
+- ✅ **PHPStan level 8** - Zero errors
+- ✅ **PSR-12 compliant** - Enforced via PHP-CS-Fixer
+- ✅ **PHP 8.1+ compatible** - Modern PHP features with backward compatibility
+
+---
+
+## TypeScript → PHP Equivalents
+
+| TypeScript | PHP 8.1+ Equivalent |
+|------------|---------------------|
+| `type FieldType = 'signature' \| 'date'` | `enum SignatureFieldType: string { case SIGNATURE = 'signature'; }` |
+| `interface Recipient { name: string }` | `final readonly class Recipient { public function __construct(public string $name) {} }` |
+| `optional?: string` | `public ?string $optional = null` |
+| `static configure(config)` | `public static function configure(HttpClientConfig $config): void` |
+| `Promise` | No promises in PHP, uses synchronous calls with exceptions |
+
+---
+
+## License
+
+MIT
+
+---
+
+## Support
+
+- 📚 [Documentation](https://www.turbodocx.com/docs)
+- 💬 [Discord Community](https://discord.gg/NYKwz4BcpX)
+- 🐛 [GitHub Issues](https://github.com/TurboDocx/SDK/issues)
+- 📧 Email: support@turbodocx.com
+
+---
+
+## Related Packages
+
+- [@turbodocx/html-to-docx](https://github.com/turbodocx/html-to-docx) - Convert HTML to DOCX
+- [@turbodocx/n8n-nodes-turbodocx](https://github.com/turbodocx/n8n-nodes-turbodocx) - n8n integration
+- [TurboDocx Writer](https://appsource.microsoft.com/product/office/WA200007397) - Microsoft Word add-in
diff --git a/packages/php-sdk/composer.json b/packages/php-sdk/composer.json
new file mode 100644
index 0000000..32f440b
--- /dev/null
+++ b/packages/php-sdk/composer.json
@@ -0,0 +1,66 @@
+{
+ "name": "turbodocx/sdk",
+ "description": "TurboDocx PHP SDK - Digital signatures, document generation, and AI-powered workflows",
+ "type": "library",
+ "license": "MIT",
+ "keywords": [
+ "turbodocx",
+ "document",
+ "generation",
+ "api",
+ "sdk",
+ "signature",
+ "turbosign",
+ "esignature",
+ "digital-signature",
+ "document-automation"
+ ],
+ "authors": [
+ {
+ "name": "TurboDocx",
+ "homepage": "https://www.turbodocx.com"
+ }
+ ],
+ "homepage": "https://www.turbodocx.com",
+ "support": {
+ "issues": "https://github.com/TurboDocx/SDK/issues",
+ "source": "https://github.com/TurboDocx/SDK"
+ },
+ "require": {
+ "php": "^8.1",
+ "ext-json": "*",
+ "ext-fileinfo": "*",
+ "guzzlehttp/guzzle": "^7.8",
+ "psr/http-client": "^1.0",
+ "psr/http-message": "^2.0"
+ },
+ "require-dev": {
+ "phpunit/phpunit": "^10.5",
+ "phpstan/phpstan": "^1.10",
+ "phpstan/phpstan-strict-rules": "^1.5",
+ "friendsofphp/php-cs-fixer": "^3.48"
+ },
+ "autoload": {
+ "psr-4": {
+ "TurboDocx\\": "src/"
+ }
+ },
+ "autoload-dev": {
+ "psr-4": {
+ "TurboDocx\\Tests\\": "tests/"
+ }
+ },
+ "scripts": {
+ "test": "phpunit",
+ "test:coverage": "phpunit --coverage-html coverage",
+ "phpstan": "phpstan analyse src tests --level=8",
+ "cs-fix": "php-cs-fixer fix"
+ },
+ "config": {
+ "sort-packages": true,
+ "optimize-autoloader": true,
+ "preferred-install": "dist"
+ },
+ "minimum-stability": "stable",
+ "prefer-stable": true
+}
diff --git a/packages/php-sdk/examples/turbosign-advanced.php b/packages/php-sdk/examples/turbosign-advanced.php
new file mode 100644
index 0000000..a9400c6
--- /dev/null
+++ b/packages/php-sdk/examples/turbosign-advanced.php
@@ -0,0 +1,158 @@
+ 100, 'height' => 30]
+ )
+ ),
+
+ // Date field
+ new Field(
+ type: SignatureFieldType::DATE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{date}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 75, 'height' => 30]
+ )
+ ),
+
+ // Full name field
+ new Field(
+ type: SignatureFieldType::FULL_NAME,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{printed_name}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 20]
+ )
+ ),
+
+ // Readonly field with default value (pre-filled)
+ new Field(
+ type: SignatureFieldType::COMPANY,
+ recipientEmail: 'john@example.com',
+ defaultValue: 'TurboDocx',
+ isReadonly: true,
+ template: new TemplateConfig(
+ anchor: '{company}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 20]
+ )
+ ),
+
+ // Required checkbox with default checked
+ new Field(
+ type: SignatureFieldType::CHECKBOX,
+ recipientEmail: 'john@example.com',
+ defaultValue: 'true',
+ required: true,
+ template: new TemplateConfig(
+ anchor: '{terms_checkbox}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 20, 'height' => 20]
+ )
+ ),
+
+ // Title field
+ new Field(
+ type: SignatureFieldType::TITLE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{title}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 75, 'height' => 30]
+ )
+ ),
+
+ // Multiline text field
+ new Field(
+ type: SignatureFieldType::TEXT,
+ recipientEmail: 'john@example.com',
+ isMultiline: true,
+ template: new TemplateConfig(
+ anchor: '{notes}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 200, 'height' => 50]
+ )
+ ),
+ ],
+ file: $pdfFile,
+ documentName: 'Advanced Contract',
+ documentDescription: 'Contract with advanced signature field features'
+ )
+ );
+
+ echo "✅ Review link created!\n\n";
+ echo "Document ID: {$result->documentId}\n";
+ echo "Status: {$result->status}\n";
+ echo "Preview URL: {$result->previewUrl}\n";
+
+ if ($result->recipients !== null) {
+ echo "\nRecipients:\n";
+ foreach ($result->recipients as $recipient) {
+ echo " {$recipient['name']} ({$recipient['email']}) - {$recipient['status']}\n";
+ }
+ }
+
+ echo "\nNext steps:\n";
+ echo "1. Review the document at the preview URL\n";
+ echo "2. Send to recipients: TurboSign::send(documentId);\n";
+
+ } catch (Exception $error) {
+ echo "Error: {$error->getMessage()}\n";
+ }
+}
+
+// Run the example
+advancedFieldsExample();
diff --git a/packages/php-sdk/examples/turbosign-basic.php b/packages/php-sdk/examples/turbosign-basic.php
new file mode 100644
index 0000000..01f59ee
--- /dev/null
+++ b/packages/php-sdk/examples/turbosign-basic.php
@@ -0,0 +1,131 @@
+ 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{signature1}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::DATE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{date1}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 75, 'height' => 30]
+ )
+ ),
+ // Second recipient
+ new Field(
+ type: SignatureFieldType::FULL_NAME,
+ recipientEmail: 'jane@example.com',
+ template: new TemplateConfig(
+ anchor: '{name2}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'jane@example.com',
+ template: new TemplateConfig(
+ anchor: '{signature2}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::DATE,
+ recipientEmail: 'jane@example.com',
+ template: new TemplateConfig(
+ anchor: '{date2}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 75, 'height' => 30]
+ )
+ ),
+ ],
+ file: $pdfFile,
+ documentName: 'Contract Agreement',
+ documentDescription: 'This document requires electronic signatures from both parties.'
+ )
+ );
+
+ echo "✅ Review link created!\n";
+ echo "Document ID: {$result->documentId}\n";
+ echo "Status: {$result->status}\n";
+ echo "Preview URL: {$result->previewUrl}\n";
+
+ if ($result->recipients !== null) {
+ echo "\nRecipients:\n";
+ foreach ($result->recipients as $recipient) {
+ echo " {$recipient['name']} ({$recipient['email']}) - {$recipient['status']}\n";
+ }
+ }
+
+ echo "\nYou can now:\n";
+ echo "1. Review the document at the preview URL\n";
+ echo "2. Send to recipients using: TurboSign::send(documentId);\n";
+
+ } catch (Exception $error) {
+ echo "Error: {$error->getMessage()}\n";
+ }
+}
+
+// Run the example
+reviewLinkExample();
diff --git a/packages/php-sdk/examples/turbosign-send-simple.php b/packages/php-sdk/examples/turbosign-send-simple.php
new file mode 100644
index 0000000..cf2c2ad
--- /dev/null
+++ b/packages/php-sdk/examples/turbosign-send-simple.php
@@ -0,0 +1,132 @@
+ 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{signature1}', // Text in your PDF to replace
+ placement: FieldPlacement::REPLACE, // Replace the anchor text
+ size: ['width' => 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::DATE,
+ recipientEmail: 'john@example.com',
+ template: new TemplateConfig(
+ anchor: '{date1}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 75, 'height' => 30]
+ )
+ ),
+ // Second recipient's fields
+ new Field(
+ type: SignatureFieldType::FULL_NAME,
+ recipientEmail: 'jane@example.com',
+ template: new TemplateConfig(
+ anchor: '{name2}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'jane@example.com',
+ template: new TemplateConfig(
+ anchor: '{signature2}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ )
+ ),
+ new Field(
+ type: SignatureFieldType::DATE,
+ recipientEmail: 'jane@example.com',
+ template: new TemplateConfig(
+ anchor: '{date2}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 75, 'height' => 30]
+ )
+ ),
+ ],
+ file: $pdfFile,
+ documentName: 'Partnership Agreement',
+ documentDescription: 'Q1 2025 Partnership Agreement - Please review and sign'
+ )
+ );
+
+ echo "✅ Document sent successfully!\n\n";
+ echo "Document ID: {$result->documentId}\n";
+ echo "Message: {$result->message}\n";
+
+ // To get sign URLs and recipient details, use getStatus
+ try {
+ $status = TurboSign::getStatus($result->documentId);
+ if (!empty($status->recipients)) {
+ echo "\nSign URLs:\n";
+ foreach ($status->recipients as $recipient) {
+ echo " {$recipient->name}: {$recipient->signUrl}\n";
+ }
+ }
+ } catch (Exception $statusError) {
+ echo "\nNote: Could not fetch recipient sign URLs\n";
+ }
+
+ } catch (Exception $error) {
+ echo "Error: {$error->getMessage()}\n";
+ }
+}
+
+// Run the example
+sendDirectlyExample();
diff --git a/packages/php-sdk/manual_test.php b/packages/php-sdk/manual_test.php
new file mode 100644
index 0000000..cdda633
--- /dev/null
+++ b/packages/php-sdk/manual_test.php
@@ -0,0 +1,277 @@
+documentId;
+}
+
+/**
+ * Test 2: Prepare document for signing and send emails
+ */
+function testSendSignature(): string
+{
+ echo "\n--- Test 2: sendSignature (using file buffer with template fields) ---\n";
+
+ $pdfBytes = file_get_contents(TEST_PDF_PATH);
+ if ($pdfBytes === false) {
+ throw new \RuntimeException('Failed to read test PDF file');
+ }
+
+ $result = TurboSign::sendSignature(
+ new SendSignatureRequest(
+ recipients: [
+ new Recipient('Test User', TEST_EMAIL, 1),
+ ],
+ fields: [
+ // Template-based field using anchor text
+ new Field(
+ type: SignatureFieldType::TEXT,
+ recipientEmail: TEST_EMAIL,
+ template: new TemplateConfig(
+ anchor: '{placeholder}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 200, 'height' => 80],
+ offset: ['x' => 0, 'y' => 0],
+ caseSensitive: true,
+ useRegex: false
+ ),
+ defaultValue: 'Sample Text',
+ isMultiline: true,
+ required: true
+ ),
+ // Coordinate-based field (traditional approach)
+ new Field(
+ type: SignatureFieldType::LAST_NAME,
+ recipientEmail: TEST_EMAIL,
+ page: 1,
+ x: 100,
+ y: 650,
+ width: 200,
+ height: 50,
+ defaultValue: 'Doe'
+ ),
+ ],
+ file: $pdfBytes,
+ documentName: 'Signing Test Document (Template Fields)',
+ documentDescription: 'Testing template-based field positioning',
+ ccEmails: ['cc@example.com']
+ )
+ );
+
+ echo "Result: " . json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";
+ return $result->documentId;
+}
+
+/**
+ * Test 3: Get document status
+ */
+function testGetStatus(string $documentId): void
+{
+ echo "\n--- Test 3: getStatus ---\n";
+
+ $result = TurboSign::getStatus($documentId);
+ echo "Result: " . json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";
+}
+
+/**
+ * Test 4: Download signed document
+ */
+function testDownload(string $documentId): void
+{
+ echo "\n--- Test 4: download ---\n";
+
+ $result = TurboSign::download($documentId);
+ echo "Result: PDF received, size: " . strlen($result) . " bytes\n";
+
+ // Save to file
+ $outputPath = './downloaded-document.pdf';
+ file_put_contents($outputPath, $result);
+ echo "File saved to: $outputPath\n";
+}
+
+/**
+ * Test 5: Resend signature emails
+ * @param array $recipientIds
+ */
+function testResend(string $documentId, array $recipientIds): void
+{
+ echo "\n--- Test 5: resend ---\n";
+
+ $result = TurboSign::resend($documentId, $recipientIds);
+ echo "Result: " . json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";
+}
+
+/**
+ * Test 6: Void document
+ */
+function testVoid(string $documentId): void
+{
+ echo "\n--- Test 6: void ---\n";
+
+ $result = TurboSign::void($documentId, 'Testing void functionality');
+ echo "Result: " . json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";
+}
+
+/**
+ * Test 7: Get audit trail
+ */
+function testGetAuditTrail(string $documentId): void
+{
+ echo "\n--- Test 7: getAuditTrail ---\n";
+
+ $result = TurboSign::getAuditTrail($documentId);
+ echo "Result: " . json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . "\n";
+}
+
+// =============================================
+// MAIN TEST RUNNER
+// =============================================
+
+function main(): void
+{
+ echo "==============================================\n";
+ echo "TurboSign PHP SDK - Manual Test Suite\n";
+ echo "==============================================\n";
+
+ // Check if test PDF exists
+ if (!file_exists(TEST_PDF_PATH)) {
+ echo "\nError: Test PDF not found at " . TEST_PDF_PATH . "\n";
+ echo "Please add a test PDF file and update TEST_PDF_PATH.\n";
+ exit(1);
+ }
+
+ try {
+ // Uncomment and run tests as needed:
+
+ // Test 1: Prepare for Review (uses fileLink, doesn't need PDF file)
+ // $reviewDocId = testCreateSignatureReviewLink();
+
+ // Test 2: Prepare for Signing (creates a new document)
+ // $signDocId = testSendSignature();
+
+ // Test 3: Get Status (replace with actual document ID)
+ // testGetStatus('document-uuid-here');
+
+ // Test 4: Download (replace with actual document ID)
+ // testDownload('document-uuid-here');
+
+ // Test 5: Resend (replace with actual document ID and recipient ID)
+ // testResend('document-uuid-here', ['recipient-uuid-here']);
+
+ // Test 6: Void (do this last as it cancels the document)
+ // testVoid('document-uuid-here');
+
+ // Test 7: Get Audit Trail (replace with actual document ID)
+ // testGetAuditTrail('document-uuid-here');
+
+ echo "\n==============================================\n";
+ echo "All tests completed successfully!\n";
+ echo "==============================================\n";
+
+ } catch (TurboDocxException $e) {
+ echo "\n==============================================\n";
+ echo "TEST FAILED\n";
+ echo "==============================================\n";
+ echo "Error: " . $e->getMessage() . "\n";
+ if ($e->getStatusCode() !== null) {
+ echo "Status Code: " . $e->getStatusCode() . "\n";
+ }
+ if ($e->getErrorCode() !== null) {
+ echo "Error Code: " . $e->getErrorCode() . "\n";
+ }
+ exit(1);
+ } catch (\Exception $e) {
+ echo "\n==============================================\n";
+ echo "TEST FAILED\n";
+ echo "==============================================\n";
+ echo "Error: " . $e->getMessage() . "\n";
+ exit(1);
+ }
+}
+
+// Run the tests
+main();
diff --git a/packages/php-sdk/phpstan.neon b/packages/php-sdk/phpstan.neon
new file mode 100644
index 0000000..1cd333b
--- /dev/null
+++ b/packages/php-sdk/phpstan.neon
@@ -0,0 +1,5 @@
+parameters:
+ level: 8
+ paths:
+ - src
+ - tests
diff --git a/packages/php-sdk/phpunit.xml b/packages/php-sdk/phpunit.xml
new file mode 100644
index 0000000..0ad2569
--- /dev/null
+++ b/packages/php-sdk/phpunit.xml
@@ -0,0 +1,18 @@
+
+
+
+
+ tests/Unit
+
+
+
+
+ src
+
+
+
diff --git a/packages/php-sdk/src/Config/HttpClientConfig.php b/packages/php-sdk/src/Config/HttpClientConfig.php
new file mode 100644
index 0000000..0307708
--- /dev/null
+++ b/packages/php-sdk/src/Config/HttpClientConfig.php
@@ -0,0 +1,60 @@
+apiKey) && empty($this->accessToken)) {
+ throw new AuthenticationException('API key or access token is required');
+ }
+
+ if (empty($this->senderEmail)) {
+ throw new ValidationException(
+ 'senderEmail is required. This email will be used as the reply-to address for signature requests. '
+ . 'Without it, emails will default to "API Service User via TurboSign".'
+ );
+ }
+ }
+
+ /**
+ * Create configuration from environment variables
+ *
+ * @return self
+ */
+ public static function fromEnvironment(): self
+ {
+ return new self(
+ apiKey: getenv('TURBODOCX_API_KEY') ?: null,
+ accessToken: getenv('TURBODOCX_ACCESS_TOKEN') ?: null,
+ baseUrl: getenv('TURBODOCX_BASE_URL') ?: 'https://api.turbodocx.com',
+ orgId: getenv('TURBODOCX_ORG_ID') ?: null,
+ senderEmail: getenv('TURBODOCX_SENDER_EMAIL') ?: null,
+ senderName: getenv('TURBODOCX_SENDER_NAME') ?: null,
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Exceptions/AuthenticationException.php b/packages/php-sdk/src/Exceptions/AuthenticationException.php
new file mode 100644
index 0000000..49e37a3
--- /dev/null
+++ b/packages/php-sdk/src/Exceptions/AuthenticationException.php
@@ -0,0 +1,16 @@
+senderEmail = $config->senderEmail;
+ $this->senderName = $config->senderName;
+
+ // Create Guzzle client
+ $this->client = new Client([
+ 'base_uri' => $config->baseUrl,
+ 'headers' => $this->getHeaders($config),
+ 'timeout' => 30.0,
+ ]);
+ }
+
+ /**
+ * Get sender email and name configuration
+ *
+ * @return array{sender_email: ?string, sender_name: ?string}
+ */
+ public function getSenderConfig(): array
+ {
+ return [
+ 'sender_email' => $this->senderEmail,
+ 'sender_name' => $this->senderName,
+ ];
+ }
+
+ /**
+ * Smart unwrap response data
+ * If response has ONLY "data" key, extract it
+ *
+ * @param array $data
+ * @return array
+ */
+ private function smartUnwrap(array $data): array
+ {
+ if (count($data) === 1 && isset($data['data'])) {
+ return $data['data'];
+ }
+ return $data;
+ }
+
+ /**
+ * Generic GET request
+ *
+ * @param string $path
+ * @param array $params
+ * @return array
+ */
+ public function get(string $path, array $params = []): mixed
+ {
+ try {
+ $response = $this->client->get($path, [
+ 'query' => $params,
+ ]);
+
+ return $this->smartUnwrap($this->parseResponse($response));
+ } catch (GuzzleException $e) {
+ $this->handleException($e);
+ }
+ }
+
+ /**
+ * Generic POST request
+ *
+ * @param string $path
+ * @param array|null $data
+ * @return array
+ */
+ public function post(string $path, ?array $data = null): mixed
+ {
+ try {
+ $response = $this->client->post($path, [
+ 'json' => $data,
+ ]);
+
+ return $this->smartUnwrap($this->parseResponse($response));
+ } catch (GuzzleException $e) {
+ $this->handleException($e);
+ }
+ }
+
+ /**
+ * Upload file with multipart form data
+ *
+ * @param string $path
+ * @param string $file File content (bytes)
+ * @param string $fieldName Form field name
+ * @param array $additionalData Extra form fields
+ * @return array
+ */
+ public function uploadFile(
+ string $path,
+ string $file,
+ string $fieldName = 'file',
+ array $additionalData = []
+ ): mixed {
+ // Detect file type using magic bytes
+ $fileType = FileTypeDetector::detect($file);
+ $fileName = $additionalData['fileName'] ?? "document.{$fileType['extension']}";
+ unset($additionalData['fileName']);
+
+ // Build multipart form data
+ $multipart = [
+ [
+ 'name' => $fieldName,
+ 'contents' => $file,
+ 'filename' => $fileName,
+ 'headers' => [
+ 'Content-Type' => $fileType['mimetype'],
+ ],
+ ],
+ ];
+
+ // Add additional fields
+ foreach ($additionalData as $key => $value) {
+ $multipart[] = [
+ 'name' => $key,
+ 'contents' => is_array($value) ? json_encode($value) : (string) $value,
+ ];
+ }
+
+ try {
+ $response = $this->client->post($path, [
+ 'multipart' => $multipart,
+ ]);
+
+ return $this->smartUnwrap($this->parseResponse($response));
+ } catch (GuzzleException $e) {
+ $this->handleException($e);
+ }
+ }
+
+ /**
+ * Handle Guzzle exceptions and map to custom exceptions
+ *
+ * @throws TurboDocxException
+ * @return never
+ */
+ private function handleException(GuzzleException $e): never
+ {
+ if ($e instanceof RequestException && $e->hasResponse()) {
+ $response = $e->getResponse();
+ if ($response !== null) {
+ $statusCode = $response->getStatusCode();
+ $body = json_decode($response->getBody()->getContents(), true);
+ $message = $body['message'] ?? $body['error'] ?? $e->getMessage();
+
+ throw match ($statusCode) {
+ 400 => new ValidationException($message),
+ 401 => new AuthenticationException($message),
+ 404 => new NotFoundException($message),
+ 429 => new RateLimitException($message),
+ default => new TurboDocxException($message, $statusCode),
+ };
+ }
+ }
+
+ throw new NetworkException("Network request failed: {$e->getMessage()}");
+ }
+
+ /**
+ * Parse JSON response
+ *
+ * @param ResponseInterface $response
+ * @return array
+ */
+ private function parseResponse(ResponseInterface $response): array
+ {
+ return json_decode($response->getBody()->getContents(), true);
+ }
+
+ /**
+ * Get headers for requests
+ *
+ * @param HttpClientConfig $config
+ * @return array
+ */
+ private function getHeaders(HttpClientConfig $config): array
+ {
+ $headers = [
+ 'Content-Type' => 'application/json',
+ 'Accept' => 'application/json',
+ ];
+
+ // Authorization
+ if (!empty($config->accessToken)) {
+ $headers['Authorization'] = "Bearer {$config->accessToken}";
+ } elseif (!empty($config->apiKey)) {
+ $headers['Authorization'] = "Bearer {$config->apiKey}";
+ }
+
+ // Organization ID
+ if (!empty($config->orgId)) {
+ $headers['x-rapiddocx-org-id'] = $config->orgId;
+ }
+
+ return $headers;
+ }
+}
diff --git a/packages/php-sdk/src/TurboSign.php b/packages/php-sdk/src/TurboSign.php
new file mode 100644
index 0000000..1ff6767
--- /dev/null
+++ b/packages/php-sdk/src/TurboSign.php
@@ -0,0 +1,364 @@
+getSenderConfig();
+
+ // Serialize recipients and fields to JSON strings (as backend expects)
+ $recipientsJson = json_encode(array_map(fn($r) => $r->toArray(), $request->recipients));
+ $fieldsJson = json_encode(array_map(fn($f) => $f->toArray(), $request->fields));
+
+ // Build form data
+ $formData = [
+ 'recipients' => $recipientsJson,
+ 'fields' => $fieldsJson,
+ ];
+
+ // Add optional fields
+ if ($request->documentName !== null) {
+ $formData['documentName'] = $request->documentName;
+ }
+ if ($request->documentDescription !== null) {
+ $formData['documentDescription'] = $request->documentDescription;
+ }
+
+ // Use request senderEmail/senderName if provided, otherwise fall back to configured values
+ $formData['senderEmail'] = $request->senderEmail ?? $senderConfig['sender_email'];
+ if ($request->senderName !== null || $senderConfig['sender_name'] !== null) {
+ $formData['senderName'] = $request->senderName ?? $senderConfig['sender_name'];
+ }
+
+ if ($request->ccEmails !== null) {
+ $formData['ccEmails'] = json_encode($request->ccEmails);
+ }
+
+ // Handle different file input methods
+ if ($request->file !== null) {
+ // File upload - use multipart form
+ $response = $client->uploadFile(
+ '/turbosign/single/prepare-for-review',
+ $request->file,
+ 'file',
+ $formData
+ );
+ return CreateSignatureReviewLinkResponse::fromArray($response);
+ } else {
+ // URL, deliverable, or template - use JSON body
+ if ($request->fileLink !== null) {
+ $formData['fileLink'] = $request->fileLink;
+ }
+ if ($request->deliverableId !== null) {
+ $formData['deliverableId'] = $request->deliverableId;
+ }
+ if ($request->templateId !== null) {
+ $formData['templateId'] = $request->templateId;
+ }
+
+ $response = $client->post(
+ '/turbosign/single/prepare-for-review',
+ $formData
+ );
+ return CreateSignatureReviewLinkResponse::fromArray($response);
+ }
+ }
+
+ /**
+ * Send signature request and immediately send emails
+ *
+ * This method uploads a document with signature fields and recipients,
+ * then immediately sends signature request emails to all recipients.
+ *
+ * @param SendSignatureRequest $request Document, recipients, and fields configuration
+ * @return SendSignatureResponse
+ *
+ * @example
+ * ```php
+ * $result = TurboSign::sendSignature(
+ * new SendSignatureRequest(
+ * recipients: [new Recipient('John Doe', 'john@example.com', 1)],
+ * fields: [new Field(SignatureFieldType::SIGNATURE, 'john@example.com', page: 1, x: 100, y: 500, width: 200, height: 50)],
+ * file: file_get_contents('contract.pdf')
+ * )
+ * );
+ * ```
+ */
+ public static function sendSignature(
+ SendSignatureRequest $request
+ ): SendSignatureResponse {
+ $client = self::getClient();
+ $senderConfig = $client->getSenderConfig();
+
+ // Serialize recipients and fields to JSON strings (as backend expects)
+ $recipientsJson = json_encode(array_map(fn($r) => $r->toArray(), $request->recipients));
+ $fieldsJson = json_encode(array_map(fn($f) => $f->toArray(), $request->fields));
+
+ // Build form data
+ $formData = [
+ 'recipients' => $recipientsJson,
+ 'fields' => $fieldsJson,
+ ];
+
+ // Add optional fields
+ if ($request->documentName !== null) {
+ $formData['documentName'] = $request->documentName;
+ }
+ if ($request->documentDescription !== null) {
+ $formData['documentDescription'] = $request->documentDescription;
+ }
+
+ // Use request senderEmail/senderName if provided, otherwise fall back to configured values
+ $formData['senderEmail'] = $request->senderEmail ?? $senderConfig['sender_email'];
+ if ($request->senderName !== null || $senderConfig['sender_name'] !== null) {
+ $formData['senderName'] = $request->senderName ?? $senderConfig['sender_name'];
+ }
+
+ if ($request->ccEmails !== null) {
+ $formData['ccEmails'] = json_encode($request->ccEmails);
+ }
+
+ // Handle different file input methods
+ if ($request->file !== null) {
+ // File upload - use multipart form
+ $response = $client->uploadFile(
+ '/turbosign/single/prepare-for-signing',
+ $request->file,
+ 'file',
+ $formData
+ );
+ return SendSignatureResponse::fromArray($response);
+ } else {
+ // URL, deliverable, or template - use JSON body
+ if ($request->fileLink !== null) {
+ $formData['fileLink'] = $request->fileLink;
+ }
+ if ($request->deliverableId !== null) {
+ $formData['deliverableId'] = $request->deliverableId;
+ }
+ if ($request->templateId !== null) {
+ $formData['templateId'] = $request->templateId;
+ }
+
+ $response = $client->post(
+ '/turbosign/single/prepare-for-signing',
+ $formData
+ );
+ return SendSignatureResponse::fromArray($response);
+ }
+ }
+
+ /**
+ * Get the status of a document
+ *
+ * @param string $documentId ID of the document
+ * @return DocumentStatusResponse
+ *
+ * @example
+ * ```php
+ * $status = TurboSign::getStatus($documentId);
+ * echo $status->status->value; // 'completed', 'pending', etc.
+ * ```
+ */
+ public static function getStatus(string $documentId): DocumentStatusResponse
+ {
+ $client = self::getClient();
+ $response = $client->get("/turbosign/documents/{$documentId}/status");
+ return DocumentStatusResponse::fromArray($response);
+ }
+
+ /**
+ * Download the signed document
+ *
+ * The backend returns a presigned S3 URL. This method fetches
+ * that URL and then downloads the actual file from S3.
+ *
+ * @param string $documentId ID of the document
+ * @return string PDF file content as bytes
+ *
+ * @example
+ * ```php
+ * $pdfContent = TurboSign::download($documentId);
+ * file_put_contents('signed.pdf', $pdfContent);
+ * ```
+ */
+ public static function download(string $documentId): string
+ {
+ $client = self::getClient();
+
+ // Step 1: Get the presigned URL from the API
+ $response = $client->get("/turbosign/documents/{$documentId}/download");
+
+ // Step 2: Fetch the actual file from S3
+ $downloadUrl = $response['downloadUrl'] ?? null;
+ if ($downloadUrl === null) {
+ throw new \RuntimeException('No download URL in response');
+ }
+
+ // Use Guzzle to download the file
+ $guzzle = new GuzzleClient();
+ $fileResponse = $guzzle->get($downloadUrl);
+
+ return $fileResponse->getBody()->getContents();
+ }
+
+ /**
+ * Void a document (cancel signature request)
+ *
+ * @param string $documentId ID of the document to void
+ * @param string $reason Reason for voiding the document
+ * @return VoidDocumentResponse
+ *
+ * @example
+ * ```php
+ * TurboSign::void($documentId, 'Document needs to be revised');
+ * ```
+ */
+ public static function void(string $documentId, string $reason): VoidDocumentResponse
+ {
+ $client = self::getClient();
+ // Backend returns empty data on success, so we just make the call
+ // and return a success response if no exception is thrown
+ $client->post(
+ "/turbosign/documents/{$documentId}/void",
+ ['reason' => $reason]
+ );
+
+ // If we get here without exception, the void was successful
+ return new VoidDocumentResponse(
+ success: true,
+ message: 'Document has been voided successfully'
+ );
+ }
+
+ /**
+ * Resend signature request email to recipients
+ *
+ * @param string $documentId ID of the document
+ * @param array $recipientIds Array of recipient IDs to resend emails to (empty array = all recipients)
+ * @return ResendEmailResponse
+ *
+ * @example
+ * ```php
+ * // Resend to specific recipients
+ * TurboSign::resend($documentId, [$recipientId1, $recipientId2]);
+ *
+ * // Resend to all recipients
+ * TurboSign::resend($documentId, []);
+ * ```
+ */
+ public static function resend(
+ string $documentId,
+ array $recipientIds
+ ): ResendEmailResponse {
+ $client = self::getClient();
+ $response = $client->post(
+ "/turbosign/documents/{$documentId}/resend-email",
+ ['recipientIds' => $recipientIds]
+ );
+ return ResendEmailResponse::fromArray($response);
+ }
+
+ /**
+ * Get audit trail for a document
+ *
+ * @param string $documentId ID of the document
+ * @return AuditTrailResponse
+ *
+ * @example
+ * ```php
+ * $audit = TurboSign::getAuditTrail($documentId);
+ * foreach ($audit->entries as $entry) {
+ * echo "{$entry->event} - {$entry->actor} - {$entry->timestamp}\n";
+ * }
+ * ```
+ */
+ public static function getAuditTrail(string $documentId): AuditTrailResponse
+ {
+ $client = self::getClient();
+ $response = $client->get("/turbosign/documents/{$documentId}/audit-trail");
+ return AuditTrailResponse::fromArray($response);
+ }
+}
diff --git a/packages/php-sdk/src/Types/DocumentStatus.php b/packages/php-sdk/src/Types/DocumentStatus.php
new file mode 100644
index 0000000..9ae7b92
--- /dev/null
+++ b/packages/php-sdk/src/Types/DocumentStatus.php
@@ -0,0 +1,18 @@
+
+ */
+ public function toArray(): array
+ {
+ $data = [
+ 'type' => $this->type->value,
+ 'recipientEmail' => $this->recipientEmail,
+ ];
+
+ // Add coordinate positioning if provided
+ if ($this->page !== null) {
+ $data['page'] = $this->page;
+ }
+ if ($this->x !== null) {
+ $data['x'] = $this->x;
+ }
+ if ($this->y !== null) {
+ $data['y'] = $this->y;
+ }
+ if ($this->width !== null) {
+ $data['width'] = $this->width;
+ }
+ if ($this->height !== null) {
+ $data['height'] = $this->height;
+ }
+
+ // Add template configuration
+ if ($this->template !== null) {
+ $data['template'] = $this->template->toArray();
+ }
+
+ // Add optional properties
+ if ($this->defaultValue !== null) {
+ $data['defaultValue'] = $this->defaultValue;
+ }
+ if ($this->isMultiline) {
+ $data['isMultiline'] = true;
+ }
+ if ($this->isReadonly) {
+ $data['isReadonly'] = true;
+ }
+ if ($this->required) {
+ $data['required'] = true;
+ }
+ if ($this->backgroundColor !== null) {
+ $data['backgroundColor'] = $this->backgroundColor;
+ }
+
+ return $data;
+ }
+}
diff --git a/packages/php-sdk/src/Types/FieldPlacement.php b/packages/php-sdk/src/Types/FieldPlacement.php
new file mode 100644
index 0000000..ea030ec
--- /dev/null
+++ b/packages/php-sdk/src/Types/FieldPlacement.php
@@ -0,0 +1,17 @@
+= 1');
+ }
+ }
+
+ /**
+ * Convert to array for JSON serialization
+ *
+ * @return array{name: string, email: string, signingOrder: int}
+ */
+ public function toArray(): array
+ {
+ return [
+ 'name' => $this->name,
+ 'email' => $this->email,
+ 'signingOrder' => $this->signingOrder,
+ ];
+ }
+}
diff --git a/packages/php-sdk/src/Types/Requests/CreateSignatureReviewLinkRequest.php b/packages/php-sdk/src/Types/Requests/CreateSignatureReviewLinkRequest.php
new file mode 100644
index 0000000..7e3d81b
--- /dev/null
+++ b/packages/php-sdk/src/Types/Requests/CreateSignatureReviewLinkRequest.php
@@ -0,0 +1,43 @@
+ $recipients Recipients who will sign
+ * @param array $fields Signature fields configuration
+ * @param string|null $file PDF file content as bytes
+ * @param string|null $fileName Original filename (used when file is provided)
+ * @param string|null $fileLink URL to document file
+ * @param string|null $deliverableId TurboDocx deliverable ID
+ * @param string|null $templateId TurboDocx template ID
+ * @param string|null $documentName Document name
+ * @param string|null $documentDescription Document description
+ * @param string|null $senderName Sender name (overrides configured value)
+ * @param string|null $senderEmail Sender email (overrides configured value)
+ * @param array|null $ccEmails CC emails
+ */
+ public function __construct(
+ public array $recipients,
+ public array $fields,
+ public ?string $file = null,
+ public ?string $fileName = null,
+ public ?string $fileLink = null,
+ public ?string $deliverableId = null,
+ public ?string $templateId = null,
+ public ?string $documentName = null,
+ public ?string $documentDescription = null,
+ public ?string $senderName = null,
+ public ?string $senderEmail = null,
+ public ?array $ccEmails = null,
+ ) {}
+}
diff --git a/packages/php-sdk/src/Types/Requests/SendSignatureRequest.php b/packages/php-sdk/src/Types/Requests/SendSignatureRequest.php
new file mode 100644
index 0000000..cee261c
--- /dev/null
+++ b/packages/php-sdk/src/Types/Requests/SendSignatureRequest.php
@@ -0,0 +1,43 @@
+ $recipients Recipients who will sign
+ * @param array $fields Signature fields configuration
+ * @param string|null $file PDF file content as bytes
+ * @param string|null $fileName Original filename (used when file is provided)
+ * @param string|null $fileLink URL to document file
+ * @param string|null $deliverableId TurboDocx deliverable ID
+ * @param string|null $templateId TurboDocx template ID
+ * @param string|null $documentName Document name
+ * @param string|null $documentDescription Document description
+ * @param string|null $senderName Sender name (overrides configured value)
+ * @param string|null $senderEmail Sender email (overrides configured value)
+ * @param array|null $ccEmails CC emails
+ */
+ public function __construct(
+ public array $recipients,
+ public array $fields,
+ public ?string $file = null,
+ public ?string $fileName = null,
+ public ?string $fileLink = null,
+ public ?string $deliverableId = null,
+ public ?string $templateId = null,
+ public ?string $documentName = null,
+ public ?string $documentDescription = null,
+ public ?string $senderName = null,
+ public ?string $senderEmail = null,
+ public ?array $ccEmails = null,
+ ) {}
+}
diff --git a/packages/php-sdk/src/Types/Responses/AuditTrailDocument.php b/packages/php-sdk/src/Types/Responses/AuditTrailDocument.php
new file mode 100644
index 0000000..5b6102e
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/AuditTrailDocument.php
@@ -0,0 +1,30 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ id: $data['id'] ?? '',
+ name: $data['name'] ?? '',
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/AuditTrailEntry.php b/packages/php-sdk/src/Types/Responses/AuditTrailEntry.php
new file mode 100644
index 0000000..fc6b23a
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/AuditTrailEntry.php
@@ -0,0 +1,64 @@
+|null $details Additional details
+ * @param AuditTrailUser|null $user User who performed the action
+ * @param string|null $userId User ID
+ * @param AuditTrailUser|null $recipient Recipient info
+ * @param string|null $recipientId Recipient ID
+ */
+ public function __construct(
+ public string $id,
+ public string $documentId,
+ public string $actionType,
+ public string $timestamp,
+ public ?string $previousHash,
+ public ?string $currentHash,
+ public ?string $createdOn,
+ public ?array $details,
+ public ?AuditTrailUser $user,
+ public ?string $userId,
+ public ?AuditTrailUser $recipient,
+ public ?string $recipientId,
+ ) {}
+
+ /**
+ * Create from array
+ *
+ * @param array $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ id: $data['id'] ?? '',
+ documentId: $data['documentId'] ?? '',
+ actionType: $data['actionType'] ?? '',
+ timestamp: $data['timestamp'] ?? '',
+ previousHash: $data['previousHash'] ?? null,
+ currentHash: $data['currentHash'] ?? null,
+ createdOn: $data['createdOn'] ?? null,
+ details: $data['details'] ?? null,
+ user: isset($data['user']) ? AuditTrailUser::fromArray($data['user']) : null,
+ userId: $data['userId'] ?? null,
+ recipient: isset($data['recipient']) ? AuditTrailUser::fromArray($data['recipient']) : null,
+ recipientId: $data['recipientId'] ?? null,
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/AuditTrailResponse.php b/packages/php-sdk/src/Types/Responses/AuditTrailResponse.php
new file mode 100644
index 0000000..feef22a
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/AuditTrailResponse.php
@@ -0,0 +1,41 @@
+ $auditTrail
+ */
+ public function __construct(
+ public AuditTrailDocument $document,
+ public array $auditTrail,
+ ) {}
+
+ /**
+ * Create from array
+ *
+ * @param array $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ $document = AuditTrailDocument::fromArray($data['document'] ?? []);
+
+ $auditTrail = array_map(
+ fn(array $e) => AuditTrailEntry::fromArray($e),
+ $data['auditTrail'] ?? []
+ );
+
+ return new self(
+ document: $document,
+ auditTrail: $auditTrail,
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/AuditTrailUser.php b/packages/php-sdk/src/Types/Responses/AuditTrailUser.php
new file mode 100644
index 0000000..5d002d7
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/AuditTrailUser.php
@@ -0,0 +1,30 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ name: $data['name'] ?? '',
+ email: $data['email'] ?? '',
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/CreateSignatureReviewLinkResponse.php b/packages/php-sdk/src/Types/Responses/CreateSignatureReviewLinkResponse.php
new file mode 100644
index 0000000..a630672
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/CreateSignatureReviewLinkResponse.php
@@ -0,0 +1,46 @@
+|null $recipients
+ * @param string $message
+ */
+ public function __construct(
+ public bool $success,
+ public string $documentId,
+ public string $status,
+ public ?string $previewUrl,
+ public ?array $recipients,
+ public string $message,
+ ) {}
+
+ /**
+ * Create from array
+ *
+ * @param array $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ success: $data['success'] ?? false,
+ documentId: $data['documentId'] ?? '',
+ status: $data['status'] ?? '',
+ previewUrl: $data['previewUrl'] ?? null,
+ recipients: $data['recipients'] ?? null,
+ message: $data['message'] ?? '',
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/DocumentStatusResponse.php b/packages/php-sdk/src/Types/Responses/DocumentStatusResponse.php
new file mode 100644
index 0000000..7243db2
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/DocumentStatusResponse.php
@@ -0,0 +1,33 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ status: $data['status'] ?? '',
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/RecipientResponse.php b/packages/php-sdk/src/Types/Responses/RecipientResponse.php
new file mode 100644
index 0000000..5fe03b0
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/RecipientResponse.php
@@ -0,0 +1,38 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ id: $data['id'] ?? '',
+ email: $data['email'] ?? '',
+ name: $data['name'] ?? '',
+ signUrl: $data['signUrl'] ?? null,
+ signedAt: $data['signedAt'] ?? null,
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/ResendEmailResponse.php b/packages/php-sdk/src/Types/Responses/ResendEmailResponse.php
new file mode 100644
index 0000000..7612d24
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/ResendEmailResponse.php
@@ -0,0 +1,30 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ success: $data['success'] ?? true,
+ recipientCount: $data['recipientCount'] ?? 0,
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/SendSignatureResponse.php b/packages/php-sdk/src/Types/Responses/SendSignatureResponse.php
new file mode 100644
index 0000000..f1464eb
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/SendSignatureResponse.php
@@ -0,0 +1,32 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ success: $data['success'] ?? false,
+ documentId: $data['documentId'] ?? '',
+ message: $data['message'] ?? '',
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/Responses/VoidDocumentResponse.php b/packages/php-sdk/src/Types/Responses/VoidDocumentResponse.php
new file mode 100644
index 0000000..ee518ef
--- /dev/null
+++ b/packages/php-sdk/src/Types/Responses/VoidDocumentResponse.php
@@ -0,0 +1,30 @@
+ $data
+ * @return self
+ */
+ public static function fromArray(array $data): self
+ {
+ return new self(
+ success: $data['success'] ?? true,
+ message: $data['message'] ?? '',
+ );
+ }
+}
diff --git a/packages/php-sdk/src/Types/SignatureFieldType.php b/packages/php-sdk/src/Types/SignatureFieldType.php
new file mode 100644
index 0000000..72581e5
--- /dev/null
+++ b/packages/php-sdk/src/Types/SignatureFieldType.php
@@ -0,0 +1,23 @@
+
+ */
+ public function toArray(): array
+ {
+ $data = [];
+
+ if ($this->anchor !== null) {
+ $data['anchor'] = $this->anchor;
+ }
+ if ($this->searchText !== null) {
+ $data['searchText'] = $this->searchText;
+ }
+ if ($this->placement !== null) {
+ $data['placement'] = $this->placement->value;
+ }
+ if ($this->size !== null) {
+ $data['size'] = $this->size;
+ }
+ if ($this->offset !== null) {
+ $data['offset'] = $this->offset;
+ }
+ if ($this->caseSensitive) {
+ $data['caseSensitive'] = true;
+ }
+ if ($this->useRegex) {
+ $data['useRegex'] = true;
+ }
+
+ return $data;
+ }
+}
diff --git a/packages/php-sdk/src/Utils/FileTypeDetector.php b/packages/php-sdk/src/Utils/FileTypeDetector.php
new file mode 100644
index 0000000..2798a5f
--- /dev/null
+++ b/packages/php-sdk/src/Utils/FileTypeDetector.php
@@ -0,0 +1,62 @@
+ 'application/pdf',
+ 'extension' => 'pdf',
+ ];
+ }
+
+ // ZIP-based formats (DOCX, PPTX): starts with PK
+ if (str_starts_with($content, 'PK')) {
+ // Check first 2000 bytes for format markers
+ $first2000 = substr($content, 0, min(strlen($content), 2000));
+
+ // PPTX contains 'ppt/' in ZIP structure
+ if (str_contains($first2000, 'ppt/')) {
+ return [
+ 'mimetype' => 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+ 'extension' => 'pptx',
+ ];
+ }
+
+ // DOCX contains 'word/' in ZIP structure
+ if (str_contains($first2000, 'word/')) {
+ return [
+ 'mimetype' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+ 'extension' => 'docx',
+ ];
+ }
+
+ // Default to DOCX if it's a ZIP but can't determine type
+ return [
+ 'mimetype' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+ 'extension' => 'docx',
+ ];
+ }
+
+ // Unknown file type
+ return [
+ 'mimetype' => 'application/octet-stream',
+ 'extension' => 'bin',
+ ];
+ }
+}
diff --git a/packages/php-sdk/tests/Unit/ExceptionTest.php b/packages/php-sdk/tests/Unit/ExceptionTest.php
new file mode 100644
index 0000000..e4dbb10
--- /dev/null
+++ b/packages/php-sdk/tests/Unit/ExceptionTest.php
@@ -0,0 +1,91 @@
+assertEquals('Test message', $exception->getMessage());
+ $this->assertEquals(500, $exception->statusCode);
+ $this->assertEquals('TEST_ERROR', $exception->errorCode);
+ }
+
+ public function testAuthenticationException(): void
+ {
+ $exception = new AuthenticationException('Custom auth message');
+
+ $this->assertEquals('Custom auth message', $exception->getMessage());
+ $this->assertEquals(401, $exception->statusCode);
+ $this->assertEquals('AUTHENTICATION_ERROR', $exception->errorCode);
+ }
+
+ public function testAuthenticationExceptionDefaultMessage(): void
+ {
+ $exception = new AuthenticationException();
+
+ $this->assertEquals('Authentication failed', $exception->getMessage());
+ }
+
+ public function testValidationException(): void
+ {
+ $exception = new ValidationException('Invalid data');
+
+ $this->assertEquals('Invalid data', $exception->getMessage());
+ $this->assertEquals(400, $exception->statusCode);
+ $this->assertEquals('VALIDATION_ERROR', $exception->errorCode);
+ }
+
+ public function testNotFoundException(): void
+ {
+ $exception = new NotFoundException('Custom not found message');
+
+ $this->assertEquals('Custom not found message', $exception->getMessage());
+ $this->assertEquals(404, $exception->statusCode);
+ $this->assertEquals('NOT_FOUND', $exception->errorCode);
+ }
+
+ public function testNotFoundExceptionDefaultMessage(): void
+ {
+ $exception = new NotFoundException();
+
+ $this->assertEquals('Resource not found', $exception->getMessage());
+ }
+
+ public function testRateLimitException(): void
+ {
+ $exception = new RateLimitException('Custom rate limit message');
+
+ $this->assertEquals('Custom rate limit message', $exception->getMessage());
+ $this->assertEquals(429, $exception->statusCode);
+ $this->assertEquals('RATE_LIMIT_EXCEEDED', $exception->errorCode);
+ }
+
+ public function testRateLimitExceptionDefaultMessage(): void
+ {
+ $exception = new RateLimitException();
+
+ $this->assertEquals('Rate limit exceeded', $exception->getMessage());
+ }
+
+ public function testNetworkException(): void
+ {
+ $exception = new NetworkException('Connection failed');
+
+ $this->assertEquals('Connection failed', $exception->getMessage());
+ $this->assertNull($exception->statusCode);
+ $this->assertEquals('NETWORK_ERROR', $exception->errorCode);
+ }
+}
diff --git a/packages/php-sdk/tests/Unit/FieldTest.php b/packages/php-sdk/tests/Unit/FieldTest.php
new file mode 100644
index 0000000..70b81e8
--- /dev/null
+++ b/packages/php-sdk/tests/Unit/FieldTest.php
@@ -0,0 +1,147 @@
+assertEquals(SignatureFieldType::SIGNATURE, $field->type);
+ $this->assertEquals('john@example.com', $field->recipientEmail);
+ $this->assertEquals(1, $field->page);
+ $this->assertEquals(100, $field->x);
+ $this->assertEquals(500, $field->y);
+ $this->assertEquals(200, $field->width);
+ $this->assertEquals(50, $field->height);
+ }
+
+ public function testCreateFieldWithTemplate(): void
+ {
+ $template = new TemplateConfig(
+ anchor: '{signature1}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ );
+
+ $field = new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ template: $template
+ );
+
+ $this->assertEquals($template, $field->template);
+ }
+
+ public function testToArrayWithCoordinates(): void
+ {
+ $field = new Field(
+ type: SignatureFieldType::DATE,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 500,
+ width: 150,
+ height: 30
+ );
+
+ $array = $field->toArray();
+
+ $this->assertEquals([
+ 'type' => 'date',
+ 'recipientEmail' => 'john@example.com',
+ 'page' => 1,
+ 'x' => 100,
+ 'y' => 500,
+ 'width' => 150,
+ 'height' => 30,
+ ], $array);
+ }
+
+ public function testToArrayWithTemplate(): void
+ {
+ $template = new TemplateConfig(
+ anchor: '{signature1}',
+ placement: FieldPlacement::REPLACE,
+ size: ['width' => 100, 'height' => 30]
+ );
+
+ $field = new Field(
+ type: SignatureFieldType::SIGNATURE,
+ recipientEmail: 'john@example.com',
+ template: $template
+ );
+
+ $array = $field->toArray();
+
+ $this->assertEquals('signature', $array['type']);
+ $this->assertEquals('john@example.com', $array['recipientEmail']);
+ $this->assertArrayHasKey('template', $array);
+ $this->assertEquals('{signature1}', $array['template']['anchor']);
+ $this->assertEquals('replace', $array['template']['placement']);
+ }
+
+ public function testToArrayWithOptionalProperties(): void
+ {
+ $field = new Field(
+ type: SignatureFieldType::CHECKBOX,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 600,
+ width: 20,
+ height: 20,
+ defaultValue: 'true',
+ isReadonly: true,
+ required: true,
+ backgroundColor: '#f0f0f0'
+ );
+
+ $array = $field->toArray();
+
+ $this->assertEquals('checkbox', $array['type']);
+ $this->assertEquals('true', $array['defaultValue']);
+ $this->assertTrue($array['isReadonly']);
+ $this->assertTrue($array['required']);
+ $this->assertEquals('#f0f0f0', $array['backgroundColor']);
+ }
+
+ public function testToArrayExcludesNullOptionalProperties(): void
+ {
+ $field = new Field(
+ type: SignatureFieldType::TEXT,
+ recipientEmail: 'john@example.com',
+ page: 1,
+ x: 100,
+ y: 200,
+ width: 300,
+ height: 30
+ );
+
+ $array = $field->toArray();
+
+ $this->assertArrayNotHasKey('defaultValue', $array);
+ $this->assertArrayNotHasKey('isMultiline', $array);
+ $this->assertArrayNotHasKey('isReadonly', $array);
+ $this->assertArrayNotHasKey('required', $array);
+ $this->assertArrayNotHasKey('backgroundColor', $array);
+ $this->assertArrayNotHasKey('template', $array);
+ }
+}
diff --git a/packages/php-sdk/tests/Unit/FileTypeDetectorTest.php b/packages/php-sdk/tests/Unit/FileTypeDetectorTest.php
new file mode 100644
index 0000000..333085e
--- /dev/null
+++ b/packages/php-sdk/tests/Unit/FileTypeDetectorTest.php
@@ -0,0 +1,56 @@
+assertEquals('application/pdf', $result['mimetype']);
+ $this->assertEquals('pdf', $result['extension']);
+ }
+
+ public function testDetectDocx(): void
+ {
+ $docxContent = 'PK' . str_repeat("\x00", 100) . 'word/document.xml';
+ $result = FileTypeDetector::detect($docxContent);
+
+ $this->assertEquals('application/vnd.openxmlformats-officedocument.wordprocessingml.document', $result['mimetype']);
+ $this->assertEquals('docx', $result['extension']);
+ }
+
+ public function testDetectPptx(): void
+ {
+ $pptxContent = 'PK' . str_repeat("\x00", 100) . 'ppt/presentation.xml';
+ $result = FileTypeDetector::detect($pptxContent);
+
+ $this->assertEquals('application/vnd.openxmlformats-officedocument.presentationml.presentation', $result['mimetype']);
+ $this->assertEquals('pptx', $result['extension']);
+ }
+
+ public function testDetectUnknownZipDefaultsToDocx(): void
+ {
+ $zipContent = 'PK' . str_repeat("\x00", 100) . 'some/other/file.xml';
+ $result = FileTypeDetector::detect($zipContent);
+
+ $this->assertEquals('application/vnd.openxmlformats-officedocument.wordprocessingml.document', $result['mimetype']);
+ $this->assertEquals('docx', $result['extension']);
+ }
+
+ public function testDetectUnknownFormat(): void
+ {
+ $unknownContent = 'UNKNOWN FORMAT';
+ $result = FileTypeDetector::detect($unknownContent);
+
+ $this->assertEquals('application/octet-stream', $result['mimetype']);
+ $this->assertEquals('bin', $result['extension']);
+ }
+}
diff --git a/packages/php-sdk/tests/Unit/HttpClientConfigTest.php b/packages/php-sdk/tests/Unit/HttpClientConfigTest.php
new file mode 100644
index 0000000..35aca93
--- /dev/null
+++ b/packages/php-sdk/tests/Unit/HttpClientConfigTest.php
@@ -0,0 +1,100 @@
+assertEquals('test-api-key', $config->apiKey);
+ $this->assertEquals('test-org-id', $config->orgId);
+ $this->assertEquals('test@example.com', $config->senderEmail);
+ $this->assertEquals('Test Company', $config->senderName);
+ $this->assertEquals('https://api.turbodocx.com', $config->baseUrl);
+ }
+
+ public function testCreateConfigWithAccessToken(): void
+ {
+ $config = new HttpClientConfig(
+ accessToken: 'test-access-token',
+ orgId: 'test-org-id',
+ senderEmail: 'test@example.com'
+ );
+
+ $this->assertEquals('test-access-token', $config->accessToken);
+ $this->assertNull($config->apiKey);
+ }
+
+ public function testCreateConfigWithCustomBaseUrl(): void
+ {
+ $config = new HttpClientConfig(
+ apiKey: 'test-api-key',
+ orgId: 'test-org-id',
+ senderEmail: 'test@example.com',
+ baseUrl: 'https://custom.example.com'
+ );
+
+ $this->assertEquals('https://custom.example.com', $config->baseUrl);
+ }
+
+ public function testMissingAuthenticationThrowsException(): void
+ {
+ $this->expectException(AuthenticationException::class);
+ $this->expectExceptionMessage('API key or access token is required');
+
+ new HttpClientConfig(
+ orgId: 'test-org-id',
+ senderEmail: 'test@example.com'
+ );
+ }
+
+ public function testMissingSenderEmailThrowsException(): void
+ {
+ $this->expectException(ValidationException::class);
+ $this->expectExceptionMessage('senderEmail is required');
+
+ new HttpClientConfig(
+ apiKey: 'test-api-key',
+ orgId: 'test-org-id'
+ );
+ }
+
+ public function testFromEnvironment(): void
+ {
+ // Set environment variables
+ putenv('TURBODOCX_API_KEY=env-api-key');
+ putenv('TURBODOCX_ORG_ID=env-org-id');
+ putenv('TURBODOCX_SENDER_EMAIL=env@example.com');
+ putenv('TURBODOCX_SENDER_NAME=Env Company');
+ putenv('TURBODOCX_BASE_URL=https://env.example.com');
+
+ $config = HttpClientConfig::fromEnvironment();
+
+ $this->assertEquals('env-api-key', $config->apiKey);
+ $this->assertEquals('env-org-id', $config->orgId);
+ $this->assertEquals('env@example.com', $config->senderEmail);
+ $this->assertEquals('Env Company', $config->senderName);
+ $this->assertEquals('https://env.example.com', $config->baseUrl);
+
+ // Cleanup
+ putenv('TURBODOCX_API_KEY');
+ putenv('TURBODOCX_ORG_ID');
+ putenv('TURBODOCX_SENDER_EMAIL');
+ putenv('TURBODOCX_SENDER_NAME');
+ putenv('TURBODOCX_BASE_URL');
+ }
+}
diff --git a/packages/php-sdk/tests/Unit/RecipientTest.php b/packages/php-sdk/tests/Unit/RecipientTest.php
new file mode 100644
index 0000000..59cfec9
--- /dev/null
+++ b/packages/php-sdk/tests/Unit/RecipientTest.php
@@ -0,0 +1,56 @@
+assertEquals('John Doe', $recipient->name);
+ $this->assertEquals('john@example.com', $recipient->email);
+ $this->assertEquals(1, $recipient->signingOrder);
+ }
+
+ public function testToArray(): void
+ {
+ $recipient = new Recipient('Jane Smith', 'jane@example.com', 2);
+ $array = $recipient->toArray();
+
+ $this->assertEquals([
+ 'name' => 'Jane Smith',
+ 'email' => 'jane@example.com',
+ 'signingOrder' => 2,
+ ], $array);
+ }
+
+ public function testInvalidEmailThrowsException(): void
+ {
+ $this->expectException(ValidationException::class);
+ $this->expectExceptionMessage('Invalid email address: invalid-email');
+
+ new Recipient('John Doe', 'invalid-email', 1);
+ }
+
+ public function testSigningOrderLessThanOneThrowsException(): void
+ {
+ $this->expectException(ValidationException::class);
+ $this->expectExceptionMessage('Signing order must be >= 1');
+
+ new Recipient('John Doe', 'john@example.com', 0);
+ }
+
+ public function testNegativeSigningOrderThrowsException(): void
+ {
+ $this->expectException(ValidationException::class);
+
+ new Recipient('John Doe', 'john@example.com', -1);
+ }
+}
diff --git a/packages/php-sdk/tests/Unit/TurboSignSenderNameTest.php b/packages/php-sdk/tests/Unit/TurboSignSenderNameTest.php
new file mode 100644
index 0000000..15a63d3
--- /dev/null
+++ b/packages/php-sdk/tests/Unit/TurboSignSenderNameTest.php
@@ -0,0 +1,107 @@
+ $senderConfig
+ * @return array
+ */
+ private function buildFormDataForReviewLink(CreateSignatureReviewLinkRequest $request, array $senderConfig): array
+ {
+ // This mirrors the logic in TurboSign::createSignatureReviewLink()
+ // We're testing the form data building logic directly
+
+ $formData = [];
+ $formData['documentName'] = $request->documentName;
+
+ if ($request->documentDescription !== null) {
+ $formData['documentDescription'] = $request->documentDescription;
+ }
+
+ // Use request senderEmail/senderName if provided, otherwise fall back to configured values
+ $formData['senderEmail'] = $request->senderEmail ?? $senderConfig['sender_email'];
+ if ($request->senderName !== null || $senderConfig['sender_name'] !== null) {
+ // FIXED: Use $request->senderName, not $request->senderEmail
+ $formData['senderName'] = $request->senderName ?? $senderConfig['sender_name'];
+ }
+
+ return $formData;
+ }
+
+ public function testSenderNameUsesCorrectFieldFromRequest(): void
+ {
+ // Arrange: Create a request with custom sender name and email
+ $request = new CreateSignatureReviewLinkRequest(
+ recipients: [],
+ fields: [],
+ documentName: 'Test Document',
+ documentDescription: 'Test Description',
+ senderEmail: 'sender@example.com',
+ senderName: 'John Doe' // This should be used, not the email
+ );
+
+ $senderConfig = [
+ 'sender_email' => 'default@example.com',
+ 'sender_name' => 'Default Name',
+ ];
+
+ // Act: Build form data (simulating what TurboSign does)
+ $formData = $this->buildFormDataForReviewLink($request, $senderConfig);
+
+ // Assert: senderName should be 'John Doe', NOT 'sender@example.com'
+ $this->assertEquals(
+ 'John Doe',
+ $formData['senderName'],
+ 'senderName should use request->senderName, not request->senderEmail'
+ );
+ $this->assertEquals(
+ 'sender@example.com',
+ $formData['senderEmail'],
+ 'senderEmail should use request->senderEmail'
+ );
+ }
+
+ public function testSenderNameFallsBackToConfigWhenNotProvided(): void
+ {
+ // Arrange: Create a request without custom sender name
+ $request = new CreateSignatureReviewLinkRequest(
+ recipients: [],
+ fields: [],
+ documentName: 'Test Document',
+ senderEmail: 'sender@example.com'
+ // senderName is null
+ );
+
+ $senderConfig = [
+ 'sender_email' => 'default@example.com',
+ 'sender_name' => 'Default Name',
+ ];
+
+ // Act
+ $formData = $this->buildFormDataForReviewLink($request, $senderConfig);
+
+ // Assert: Should fall back to config sender name
+ $this->assertEquals(
+ 'Default Name',
+ $formData['senderName'],
+ 'senderName should fall back to config sender_name when request->senderName is null'
+ );
+ }
+}
diff --git a/packages/php-sdk/tests/bootstrap.php b/packages/php-sdk/tests/bootstrap.php
new file mode 100644
index 0000000..c038fe3
--- /dev/null
+++ b/packages/php-sdk/tests/bootstrap.php
@@ -0,0 +1,6 @@
+ 
