feat: initialize project

Author: ronald2wing

.gitignore

@@ -0,0 +1,40 @@
+# Composer
+vendor/
+composer.lock
+auth.json
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# IDEs & editors
+.idea/
+.vscode/
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.fleet/
+.nova/
+.zed/
+.phpactor.json
+*.swp
+*.swo
+*~
+*.sublime-*
+*.sublime-project
+*.sublime-workspace
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Testing & static analysis
+.phpunit.cache/
+.phpunit.result.cache
+.phpstan/
+coverage/
+
+# Logs
+*.log

AGENTS.md

@@ -0,0 +1,73 @@
+# Laravel Mailtrap Driver — Agent Guide
+
+## Commands
+
+```bash
+composer run check         # lint → analyse → test (preferred)
+composer run test          # PHPUnit with Clover + HTML coverage → coverage/
+composer run analyse       # PHPStan level 8, --memory-limit=1G
+composer run format        # Pint — modifies files in-place
+composer run lint          # Pint --test — checks formatting without modifying
+```
+
+**Coverage gotcha:** `composer run test` and `composer run check` both require a coverage driver (Xdebug or pcov). Without one, PHPUnit exits with error. For local runs:
+```bash
+vendor/bin/phpunit --no-coverage
+```
+
+## Architecture
+
+Four source files in `src/`, all under namespace `Ronald2Wing\LaravelMailtrap\`:
+
+| File | Role |
+|------|------|
+| `MailtrapServiceProvider.php` | Registers the `mailtrap` transport. Reads from `services.mailtrap` by default; each mailer may override via `'config' => 'services.mailtrap.marketing'`. |
+| `MailtrapTransport.php` | Symfony `AbstractTransport`. POSTs to `apiUrl()` with JSON from `PayloadBuilder`. |
+| `PayloadBuilder.php` | Translates Symfony `Email` + `Envelope` into Mailtrap's JSON payload. Pure, no I/O. |
+| `MailtrapConfig.php` | Readonly value object — token, endpoint, optional inbox id, Guzzle options. Public constants: `SEND_ENDPOINT`, `BULK_ENDPOINT`, `SANDBOX_ENDPOINT`. Factory: `fromArray()`. |
+
+### MailtrapConfig config mapping (`fromArray`)
+
+| Config key (`services.mailtrap.*`) | Property | Notes |
+|------------------------------------|----------|-------|
+| `token` | `apiToken` | Required; must be non-empty |
+| `endpoint` | `endpoint` | Defaults to `SEND_ENDPOINT` |
+| `inbox_id` | `inboxId` | Required when endpoint is `SANDBOX_ENDPOINT` |
+| `http` | `httpOverrides` | Guzzle options; merged over `DEFAULT_HTTP_OPTIONS` (`connect_timeout: 10`, `timeout: 30`) |
+
+### PayloadBuilder header handling
+
+Two constants control Mailtrap-specific headers:
+
+| Constant | Headers mapped | Value handling |
+|----------|---------------|----------------|
+| `MAILTRAP_STRING_HEADERS` | `X-Mailtrap-Category` → `category`, `X-Mailtrap-Template-Uuid` → `template_uuid` | Passed as-is (string) |
+| `MAILTRAP_JSON_HEADERS` | `X-Mailtrap-Template-Variables` → `template_variables`, `X-Mailtrap-Custom-Variables` → `custom_variables` | JSON-decoded to array |
+
+Standard headers are defined in `RFC5322_HEADERS`. Both header constants feed `reservedHeaderNames()`, used by `extractForwardedHeaders()` to filter reserved headers out of the forwarded `headers` block. `extractReplyTo()` handles Reply-To separately. Both are merged in `build()`.
+
+### Adding a new Mailtrap-specific header
+
+1. Add an entry to `PayloadBuilder::MAILTRAP_STRING_HEADERS` or `PayloadBuilder::MAILTRAP_JSON_HEADERS` depending on whether the value needs JSON decoding.
+2. Done. `extractMailtrapHeaders` picks it up, `reservedHeaderNames` strips it from the forwarded headers block.
+
+## Static Analysis
+
+PHPStan runs at **level 8** with **no ignored errors** on both `src/` and `tests/`. Never add baseline entries or `@phpstan-ignore` comments.
+
+## CI
+
+CI (`php.yml`) runs **test → lint → analyse** (different order from `composer check` which is lint → analyse → test). It also runs `composer validate --strict`.
+
+## Testing
+
+- **Base classes**: `Orchestra\Testbench\TestCase` for container-aware tests; `PHPUnit\Framework\TestCase` for pure unit tests.
+- **HTTP mocking**: Guzzle `MockHandler` + `HandlerStack` with a history middleware.
+- **Reflection**: `extractMessageId` (private static) is tested via `invokeProtected` helper in `MailtrapTransportTest`.
+- `getEnvironmentSetUp()` configures `services.mailtrap`, `mail.default`, and `mail.from` for integration tests.
+
+## Conventions
+
+- `declare(strict_types=1)` in every file.
+- `composer.json` has `sort-packages: true` — Composer auto-sorts after `composer require`. Keep it valid for CI.
+- PHPDoc with `@param` array shapes on every public/protected method.

CHANGELOG.md

@@ -0,0 +1,27 @@
+# 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).
+
+## [1.0.0] - 2025-11-11
+
+### Added
+
+- Initial release of Laravel Mailtrap Driver package.
+- Mailtrap Email Sending API transport via Symfony Mailer.
+- Text and HTML email support.
+- Multipart emails (both text and HTML).
+- File attachments (regular and inline).
+- CC and BCC recipients.
+- Custom headers and Reply-To (multiple addresses joined per RFC 5322).
+- Mailtrap categories via `X-Mailtrap-Category` header.
+- Template support via `X-Mailtrap-Template-Uuid`, `X-Mailtrap-Template-Variables`, and `X-Mailtrap-Custom-Variables` headers.
+- Sandbox, Bulk, and Transactional endpoints with `inbox_id` configuration.
+- HTTP client options via `http` config key (defaults: `connect_timeout: 10`, `timeout: 30`).
+- International character support (UTF-8).
+- PHP 8.3+, Laravel 10.x–13.x.
+- PHPStan level 8 with zero ignored errors.
+- Comprehensive test suite.
+- CI via GitHub Actions.

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Ronald Wong <ronald2wing@gmail.com>
+
+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.