166 lines
3.5 KiB
Markdown
166 lines
3.5 KiB
Markdown
# Distributing Carriers Application
|
|
|
|
A production-ready event-sourced application built with DDD, CQRS, and Event Sourcing patterns using PHP 8+ and Apache Cassandra.
|
|
|
|
## Features
|
|
|
|
- **Domain-Driven Design (DDD)**: Clean separation of domain, application, and infrastructure layers
|
|
- **Event Sourcing**: All state changes captured as immutable events in Cassandra
|
|
- **CQRS**: Command-Query Responsibility Segregation with command bus
|
|
- **Production-Ready**: Comprehensive error handling, logging, validation, and monitoring
|
|
- **Optimistic Concurrency Control**: Version-based conflict detection
|
|
- **Retry Logic**: Automatic retry with exponential backoff for transient failures
|
|
- **Structured Logging**: JSON-formatted logs with Monolog
|
|
- **Input Validation**: Multi-layer validation with detailed error messages
|
|
- **Type Safety**: Strict types and value objects for domain integrity
|
|
|
|
## Requirements
|
|
|
|
- PHP 8.0 or higher
|
|
- Cassandra PHP extension
|
|
- Docker & Docker Compose
|
|
- Composer
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository
|
|
2. Copy environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Install dependencies:
|
|
```bash
|
|
composer install
|
|
```
|
|
|
|
4. Start services:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
5. Initialize Cassandra schema:
|
|
```bash
|
|
docker exec -it cassandra cqlsh -e "
|
|
CREATE KEYSPACE IF NOT EXISTS event_store
|
|
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
|
|
|
|
USE event_store;
|
|
|
|
CREATE TABLE IF NOT EXISTS events (
|
|
aggregate_id text,
|
|
version int,
|
|
event_type text,
|
|
payload text,
|
|
created_at timestamp,
|
|
PRIMARY KEY (aggregate_id, version)
|
|
) WITH CLUSTERING ORDER BY (version ASC);
|
|
"
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Register Carrier
|
|
|
|
**POST** `/register-carrier`
|
|
|
|
Request:
|
|
```json
|
|
{
|
|
"name": "FedEx",
|
|
"email": "contact@fedex.com"
|
|
}
|
|
```
|
|
|
|
Success Response (201):
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"message": "Carrier registered successfully",
|
|
"carrier_id": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
}
|
|
```
|
|
|
|
Error Response (422):
|
|
```json
|
|
{
|
|
"success": false,
|
|
"error": {
|
|
"message": "Validation failed",
|
|
"code": 422,
|
|
"details": {
|
|
"email": "The email must be a valid email address"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Layers
|
|
|
|
- **Domain**: Core business logic, aggregates, events, value objects
|
|
- **Application**: Use cases, command handlers, DTOs
|
|
- **Infrastructure**: Technical implementations (Cassandra, logging, routing)
|
|
|
|
### Key Components
|
|
|
|
- **AggregateRoot**: Base class for domain aggregates with event sourcing
|
|
- **CommandBus**: Routes commands to appropriate handlers
|
|
- **EventStore**: Persists and retrieves domain events from Cassandra
|
|
- **Logger**: Structured logging with rotation and JSON formatting
|
|
- **Validator**: Input validation with detailed error messages
|
|
|
|
## Configuration
|
|
|
|
Edit `.env` file:
|
|
|
|
```env
|
|
APP_ENV=production
|
|
APP_DEBUG=false
|
|
APP_LOG_LEVEL=info
|
|
|
|
CASSANDRA_HOST=cassandra
|
|
CASSANDRA_PORT=9042
|
|
CASSANDRA_KEYSPACE=event_store
|
|
|
|
MAX_REQUEST_SIZE=1048576
|
|
REQUEST_TIMEOUT=30
|
|
```
|
|
|
|
## Logging
|
|
|
|
Logs are written to `logs/app.log` in JSON format with automatic rotation (30 days).
|
|
|
|
Log levels: debug, info, warning, error, critical
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
composer test
|
|
```
|
|
|
|
## Development
|
|
|
|
For development mode, set in `.env`:
|
|
```env
|
|
APP_ENV=development
|
|
APP_DEBUG=true
|
|
APP_LOG_LEVEL=debug
|
|
```
|
|
|
|
## Production Deployment
|
|
|
|
1. Set production environment variables
|
|
2. Ensure proper Cassandra replication factor
|
|
3. Configure log rotation
|
|
4. Set up monitoring and alerting
|
|
5. Use a reverse proxy (nginx) for SSL termination
|
|
6. Enable PHP OPcache
|
|
|
|
## License
|
|
|
|
MIT
|