|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is the **seven.io PHP SDK**, an official API client for the seven.io SMS Gateway API. It's a PHP library that provides a clean, object-oriented interface for all seven.io services including SMS, Voice, RCS messaging, number lookup, and analytics. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Testing |
| 12 | +```bash |
| 13 | +# Run all tests with production API key |
| 14 | +SEVEN_API_KEY=your_api_key php vendor/bin/phpunit tests |
| 15 | + |
| 16 | +# Run all tests with sandbox API key (preferred for development) |
| 17 | +SEVEN_API_KEY_SANDBOX=your_sandbox_key php vendor/bin/phpunit tests |
| 18 | + |
| 19 | +# Run specific test file |
| 20 | +php vendor/bin/phpunit tests/SmsTest.php |
| 21 | + |
| 22 | +# Run tests with verbose output |
| 23 | +php vendor/bin/phpunit tests --verbose |
| 24 | +``` |
| 25 | + |
| 26 | +### Documentation Generation |
| 27 | +```bash |
| 28 | +# Generate API documentation (outputs to docs/ directory) |
| 29 | +php vendor/bin/phpdoc |
| 30 | +``` |
| 31 | + |
| 32 | +### Package Management |
| 33 | +```bash |
| 34 | +# Install dependencies |
| 35 | +composer install |
| 36 | + |
| 37 | +# Install without dev dependencies |
| 38 | +composer install --no-dev |
| 39 | + |
| 40 | +# Update dependencies |
| 41 | +composer update |
| 42 | +``` |
| 43 | + |
| 44 | +## Architecture Overview |
| 45 | + |
| 46 | +### Core Components |
| 47 | + |
| 48 | +1. **Client (`src/Client.php`)** - The main HTTP client that handles all API communication |
| 49 | + - Manages authentication via API keys and optional signing secrets |
| 50 | + - Handles all HTTP methods (GET, POST, PATCH, DELETE) |
| 51 | + - Implements request signing for webhook verification |
| 52 | + - Manages error handling and exception throwing |
| 53 | + |
| 54 | +2. **Resources** - Each API endpoint group has its own resource class |
| 55 | + - All extend `src/Resource/Resource.php` abstract class |
| 56 | + - Located in `src/Resource/*/` directories (Analytics, Sms, Voice, etc.) |
| 57 | + - Each resource handles specific API functionality (SMS sending, lookups, etc.) |
| 58 | + |
| 59 | +3. **Parameter Objects** - Type-safe parameter classes for API requests |
| 60 | + - Follow naming pattern: `*Params.php` (e.g., `SmsParams`, `VoiceParams`) |
| 61 | + - Implement validation and provide fluent interfaces |
| 62 | + |
| 63 | +4. **Response Objects** - Structured response classes for API responses |
| 64 | + - Located alongside their respective resources |
| 65 | + - Provide type-safe access to response data |
| 66 | + |
| 67 | +### Directory Structure |
| 68 | + |
| 69 | +``` |
| 70 | +src/ |
| 71 | +├── Client.php # Main HTTP client |
| 72 | +├── Exception/ # Custom exception classes |
| 73 | +├── Library/ # Shared utilities and enums |
| 74 | +└── Resource/ # API resource implementations |
| 75 | + ├── Resource.php # Abstract base class |
| 76 | + ├── Analytics/ # Analytics and reporting |
| 77 | + ├── Balance/ # Account balance |
| 78 | + ├── Contacts/ # Contact management |
| 79 | + ├── Groups/ # Contact groups |
| 80 | + ├── Hooks/ # Webhook management |
| 81 | + ├── Journal/ # Message history |
| 82 | + ├── Lookup/ # Number lookup/validation |
| 83 | + ├── Numbers/ # Phone number management |
| 84 | + ├── Pricing/ # Pricing information |
| 85 | + ├── Rcs/ # RCS messaging |
| 86 | + ├── Sms/ # SMS messaging (primary feature) |
| 87 | + ├── Status/ # Delivery status |
| 88 | + ├── Subaccounts/ # Subaccount management |
| 89 | + ├── ValidateForVoice/ # Voice validation |
| 90 | + └── Voice/ # Voice calls |
| 91 | +``` |
| 92 | + |
| 93 | +### Key Design Patterns |
| 94 | + |
| 95 | +1. **Resource Pattern** - Each API endpoint group is encapsulated in a Resource class |
| 96 | +2. **Parameter Objects** - Request parameters are wrapped in typed parameter objects |
| 97 | +3. **Exception Hierarchy** - Custom exceptions for different API error types |
| 98 | +4. **Client Composition** - Resources receive the Client instance for HTTP operations |
| 99 | + |
| 100 | +## Testing Environment |
| 101 | + |
| 102 | +### Environment Variables |
| 103 | +- `SEVEN_API_KEY` - Production API key for live testing |
| 104 | +- `SEVEN_API_KEY_SANDBOX` - Sandbox API key for safe testing (preferred) |
| 105 | +- `SEVEN_SIGNING_SECRET` - Optional webhook signing secret |
| 106 | + |
| 107 | +### Test Structure |
| 108 | +- All tests extend `tests/BaseTest.php` |
| 109 | +- Uses `tests/Resources.php` as a resource factory for consistent test setup |
| 110 | +- Tests are organized by resource type (SmsTest.php, VoiceTest.php, etc.) |
| 111 | +- Tests can switch between production and sandbox environments |
| 112 | + |
| 113 | +## Common Development Patterns |
| 114 | + |
| 115 | +### Creating a New Resource |
| 116 | +1. Create resource class extending `Resource` in appropriate namespace |
| 117 | +2. Create parameter classes implementing `ParamsInterface` |
| 118 | +3. Create response/data classes for API responses |
| 119 | +4. Add validator classes if complex validation is needed |
| 120 | +5. Add corresponding test class extending `BaseTest` |
| 121 | + |
| 122 | +### Exception Handling |
| 123 | +The client automatically handles API error codes: |
| 124 | +- `900` - Invalid API Key |
| 125 | +- `901` - Signing Hash Verification Failed |
| 126 | +- `902` - Missing Access Rights |
| 127 | +- `903` - Forbidden IP |
| 128 | +- `600` - General API Error |
| 129 | + |
| 130 | +### Request Authentication |
| 131 | +The Client supports two authentication methods: |
| 132 | +1. API Key only (standard) |
| 133 | +2. API Key + Signing Secret (for webhook verification) |
| 134 | + |
| 135 | +## Requirements |
| 136 | + |
| 137 | +- PHP 8.2+ |
| 138 | +- Required extensions: curl, json, mbstring, ctype |
| 139 | +- Development extensions: xdebug, soap, simplexml |
0 commit comments