|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Testing |
| 8 | +- `composer test` - Run tests using TestBench without coverage |
| 9 | +- `composer test-coverage` - Run PHPUnit with HTML coverage report |
| 10 | +- `./vendor/bin/testbench package:test --no-coverage` - Direct TestBench command |
| 11 | + |
| 12 | +### Code Quality |
| 13 | +- `composer analyse` - Run PHPStan static analysis (level 4) |
| 14 | +- `composer format` - Format code using Laravel Pint with custom ruleset |
| 15 | +- `vendor/bin/pint` - Direct Pint formatting command |
| 16 | +- `vendor/bin/phpstan analyse` - Direct PHPStan command |
| 17 | + |
| 18 | +### Package Development |
| 19 | +- `php artisan vendor:publish --provider="palPalani\SqsQueueReader\SqsQueueReaderServiceProvider" --tag="config"` - Publish configuration file |
| 20 | + |
| 21 | +## Architecture Overview |
| 22 | + |
| 23 | +This is a Laravel package that extends SQS queue functionality to handle raw JSON payloads from external sources (webhooks, third-party APIs) without requiring Laravel's specific job format. |
| 24 | + |
| 25 | +### Core Components |
| 26 | + |
| 27 | +**Queue Driver (`sqs-json`)** |
| 28 | +- Custom SQS connector (`src/Sqs/Connector.php`) extends Laravel's SqsConnector |
| 29 | +- Custom queue implementation (`src/Sqs/Queue.php`) extends Laravel's SqsQueue |
| 30 | +- Handles both single and batch message processing |
| 31 | +- Automatically formats raw JSON messages into Laravel job format |
| 32 | + |
| 33 | +**Service Provider (`src/SqsQueueReaderServiceProvider.php`)** |
| 34 | +- Registers the `sqs-json` queue driver |
| 35 | +- Handles automatic message deletion after processing |
| 36 | +- Manages batch message cleanup via SQS API |
| 37 | + |
| 38 | +**Dispatcher Job (`src/Jobs/DispatcherJob.php`)** |
| 39 | +- Utility for dispatching plain JSON or Laravel-formatted messages |
| 40 | +- Supports both structured (`setPlain(false)`) and plain JSON (`setPlain(true)`) modes |
| 41 | + |
| 42 | +### Configuration System |
| 43 | + |
| 44 | +**Queue Handlers (`config/sqs-queue-reader.php`)** |
| 45 | +- Maps queue names to handler classes and message counts |
| 46 | +- Supports multiple queues with different handlers |
| 47 | +- Falls back to default handler for unmapped queues |
| 48 | +- Configurable message batch sizes (1-10 messages per poll) |
| 49 | + |
| 50 | +**Queue Connection Setup** |
| 51 | +- Add `sqs-json` driver to `config/queue.php` |
| 52 | +- Use standard AWS SQS configuration (key, secret, region, prefix, queue) |
| 53 | +- Set `QUEUE_DRIVER=sqs-json` in environment |
| 54 | + |
| 55 | +### Message Processing Flow |
| 56 | + |
| 57 | +1. **Incoming Messages**: Raw JSON from external sources (Stripe, Mailgun, etc.) |
| 58 | +2. **Queue Processing**: `Queue::pop()` retrieves and formats messages |
| 59 | +3. **Handler Mapping**: Uses queue name to determine handler class and batch size |
| 60 | +4. **Job Creation**: Wraps raw payload in Laravel job format with UUID |
| 61 | +5. **Batch Handling**: Multiple messages processed together when count > 1 |
| 62 | +6. **Cleanup**: Automatic SQS message deletion after successful processing |
| 63 | + |
| 64 | +### Testing Framework |
| 65 | + |
| 66 | +- Uses Orchestra Testbench for Laravel package testing |
| 67 | +- Configured for strict testing (warnings/notices as failures) |
| 68 | +- Coverage reports generated in `build/coverage/` |
| 69 | +- Test files in `tests/` directory |
| 70 | + |
| 71 | +### Code Standards |
| 72 | + |
| 73 | +- PHP 8.3+ with strict types declared |
| 74 | +- Laravel Pint formatting with custom rules (PER-CS, PHP 8.3 migration) |
| 75 | +- PHPStan level 4 analysis with Octane compatibility checks |
| 76 | +- PSR-4 autoloading: `palPalani\SqsQueueReader\` |
| 77 | + |
| 78 | +### Key Features |
| 79 | + |
| 80 | +- **Multi-message Processing**: Configurable batch sizes for high-throughput scenarios |
| 81 | +- **Handler Flexibility**: Different job classes per queue |
| 82 | +- **AWS Integration**: Direct SQS API usage for batch operations |
| 83 | +- **Laravel Compatibility**: Works with Laravel 11-12, PHP 8.3+ |
| 84 | +- **Plain JSON Support**: Handles raw webhook payloads without Laravel job wrapper |
0 commit comments