Skip to content

Commit a094398

Browse files
PalbahngmiyinePalbahngmiyine
committed
Add documentation files for SOLAPI PHP SDK
- Introduced AGENTS.md for detailed SDK structure, usage, and conventions. - Added CLAUDE.md to provide guidance for code usage and architecture overview.
1 parent b68825d commit a094398

2 files changed

Lines changed: 173 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# SOLAPI PHP SDK
2+
3+
**Generated:** 2026-01-21
4+
**Commit:** b68825d
5+
**Branch:** master
6+
7+
## OVERVIEW
8+
9+
PHP SDK for SOLAPI messaging API (SMS, LMS, MMS, Kakao Alimtalk, Voice, Fax) targeting Korean telecom. Zero external dependencies, PHP 7.1+.
10+
11+
## STRUCTURE
12+
13+
```
14+
solapi-php/
15+
├── src/
16+
│ ├── Services/ # Entry point (SolapiMessageService)
17+
│ ├── Libraries/ # HTTP client, auth, utilities
18+
│ ├── Models/
19+
│ │ ├── Request/ # API request DTOs (7 files)
20+
│ │ ├── Response/ # API response DTOs (17 files)
21+
│ │ ├── Kakao/ # Kakao message options
22+
│ │ ├── Voice/ # Voice message options
23+
│ │ └── Fax/ # Fax message options
24+
│ └── Exceptions/ # Custom exceptions (4 files)
25+
├── composer.json # PSR-4: Nurigo\Solapi\ → src/
26+
└── README.md
27+
```
28+
29+
## WHERE TO LOOK
30+
31+
| Task | Location | Notes |
32+
|------|----------|-------|
33+
| Send messages | `Services/SolapiMessageService.php` | Main entry point, all public methods |
34+
| Build message | `Models/Message.php` | Fluent builder, extends BaseMessage |
35+
| HTTP requests | `Libraries/Fetcher.php` | Singleton, CURL-based |
36+
| Auth header | `Libraries/Authenticator.php` | HMAC-SHA256, static method |
37+
| Kakao options | `Models/Kakao/KakaoOption.php` | pfId, templateId, buttons, bms |
38+
| Voice options | `Models/Voice/VoiceOption.php` | voiceType, headerMessage, tailMessage |
39+
| Error handling | `Exceptions/` | BaseException, CurlException, MessageNotReceivedException |
40+
| Request params | `Models/Request/` | SendRequest, GetMessagesRequest, etc. |
41+
| Response parsing | `Models/Response/` | SendResponse, GroupMessageResponse, etc. |
42+
43+
## CODE MAP
44+
45+
**Entry Point:**
46+
```php
47+
$service = new SolapiMessageService($apiKey, $apiSecret);
48+
$response = $service->send($message);
49+
```
50+
51+
**Call Flow:**
52+
```
53+
SolapiMessageService → Fetcher (singleton) → Authenticator (static)
54+
→ CURL → api.solapi.com
55+
→ Response DTOs
56+
```
57+
58+
**Key Classes:**
59+
| Class | Type | Role |
60+
|-------|------|------|
61+
| `SolapiMessageService` | Service | Primary API (send, uploadFile, getMessages, getGroups, getBalance) |
62+
| `Message` | Model | Message builder with fluent setters |
63+
| `Fetcher` | Library | HTTP client singleton, handles all API requests |
64+
| `Authenticator` | Library | Generates HMAC-SHA256 auth headers |
65+
| `NullEliminator` | Library | Removes null values before JSON serialization |
66+
67+
## CONVENTIONS
68+
69+
**Namespace:** `Nurigo\Solapi\*` (PSR-4 from `src/`)
70+
71+
**Patterns:**
72+
- Fluent builder: `$msg->setTo("...")->setFrom("...")->setText("...")`
73+
- Singleton: `Fetcher::getInstance($key, $secret)`
74+
- Public properties with getters/setters on models
75+
- Korean PHPDoc comments (domain-specific)
76+
77+
**Type Safety:**
78+
- Full type hints on method params/returns
79+
- PHPDoc `@var`, `@param`, `@return`, `@throws` annotations
80+
81+
## ANTI-PATTERNS
82+
83+
- **Avoid catch-all nulls:** Many get* methods return `null` on any exception — check response validity
84+
- **Singleton state:** Fetcher singleton retains credentials — don't mix different API keys in same process
85+
- **No interfaces:** Service/Fetcher have no contracts — mocking requires concrete class extension
86+
- **SSL verification disabled:** `CURLOPT_SSL_VERIFYPEER = false` in Fetcher
87+
88+
## UNIQUE STYLES
89+
90+
- **Korean comments:** PHPDoc descriptions in Korean (수신번호, 발신번호, 메시지 내용)
91+
- **Default country:** `"82"` (Korea) hardcoded in BaseMessage
92+
- **Timezone:** `Asia/Seoul` set in Authenticator
93+
94+
## COMMANDS
95+
96+
```bash
97+
# Install
98+
composer require solapi/sdk
99+
100+
# No local tests — see solapi-php-examples repo
101+
```
102+
103+
## NOTES
104+
105+
- **Examples:** External repo at `github.com/solapi/solapi-php-examples`
106+
- **API docs:** `developers.solapi.com`
107+
- **PHP requirement:** 7.1+ (ext-curl, ext-json required)
108+
- **TODO in README:** Missing documentation link (line 19)

‎CLAUDE.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
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+
SOLAPI PHP SDK - A zero-dependency messaging SDK for Korean telecommunications (SMS, LMS, MMS, Kakao Alimtalk, Voice, Fax). Version 5.0.6, requires PHP 7.1+ with curl and json extensions.
8+
9+
## Commands
10+
11+
```bash
12+
# Install dependencies (none required, autoloader only)
13+
composer install
14+
15+
# There are no local tests - see https://github.com/solapi/solapi-php-examples for usage examples
16+
```
17+
18+
## Architecture
19+
20+
**Entry Point:** `SolapiMessageService` in `src/Services/` - all public API methods
21+
22+
**Call Flow:**
23+
```
24+
SolapiMessageService → Fetcher (singleton) → Authenticator (static) → CURL → api.solapi.com
25+
```
26+
27+
**Key Classes:**
28+
- `SolapiMessageService` - Primary API: send(), uploadFile(), getMessages(), getGroups(), getBalance()
29+
- `Message` (`Models/Message.php`) - Fluent builder for message construction
30+
- `Fetcher` (`Libraries/Fetcher.php`) - Singleton HTTP client
31+
- `Authenticator` (`Libraries/Authenticator.php`) - HMAC-SHA256 auth header generation
32+
33+
**Models Structure:**
34+
- `Models/Request/` - 7 request DTOs (SendRequest, GetMessagesRequest, etc.)
35+
- `Models/Response/` - 17 response DTOs (SendResponse, GroupMessageResponse, etc.)
36+
- `Models/Kakao/` - Kakao message options (pfId, templateId, buttons)
37+
- `Models/Voice/` - Voice message options
38+
- `Models/Fax/` - Fax message options
39+
40+
## Code Conventions
41+
42+
**Namespace:** `Nurigo\Solapi\*` (PSR-4 autoload from `src/`)
43+
44+
**Patterns:**
45+
- Fluent builder: `$msg->setTo("...")->setFrom("...")->setText("...")`
46+
- Singleton: `Fetcher::getInstance($apiKey, $apiSecret)`
47+
- Public properties with getters/setters on all model classes
48+
- Full type hints on method params/returns with PHPDoc annotations
49+
50+
**Language Notes:**
51+
- PHPDoc comments are in Korean (수신번호, 발신번호, 메시지 내용)
52+
- Default country code is "82" (Korea) in BaseMessage
53+
- Timezone hardcoded to Asia/Seoul in Authenticator
54+
55+
## Important Behaviors
56+
57+
- **Singleton State:** Fetcher singleton retains credentials - don't mix different API keys in the same process
58+
- **Null Returns:** Many get* methods return `null` on any exception instead of throwing - always check response validity
59+
- **No Interfaces:** Service/Fetcher lack contracts - mocking requires concrete class extension
60+
- **SSL Verification:** Disabled in Fetcher (`CURLOPT_SSL_VERIFYPEER = false`)
61+
62+
## External Resources
63+
64+
- API Documentation: https://developers.solapi.com
65+
- Examples Repository: https://github.com/solapi/solapi-php-examples

0 commit comments

Comments
 (0)