337 lines
10 KiB
Markdown
337 lines
10 KiB
Markdown
# MyEP Next Booking System
|
|
|
|
A sophisticated Symfony 6.4 travel booking application that integrates with Bus Pro Net (BPN) XML API for comprehensive travel management. The system handles complex multi-step booking workflows with dynamic participant forms, conditional field logic, and real-time pricing display.
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- PHP 8.1+
|
|
- Composer
|
|
- Node.js & npm
|
|
- DDEV (recommended for local development)
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone [repository-url]
|
|
cd myep-next-booking
|
|
|
|
# Install dependencies
|
|
composer install
|
|
npm install
|
|
|
|
# Start local development environment
|
|
ddev start
|
|
|
|
# Run database migrations
|
|
bin/console doctrine:migrations:migrate
|
|
|
|
# Generate OAuth2 keys
|
|
bin/console app:generate-keys
|
|
|
|
# Compile assets
|
|
npm run dev
|
|
```
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
### Multi-Step Booking Flow
|
|
1. **Step 1**: Room selection with quantities and dates
|
|
2. **Step 2**: Participant details with conditional fields and service selection
|
|
3. **Step 3**: Final confirmation and submission to BPN API
|
|
|
|
### Core Components
|
|
|
|
#### BusProNet Integration (`src/BusProNet/`)
|
|
- **ApiClient**: XML API communication layer
|
|
- **XmlParser/**: Response parsing for travels, hotels, bookings
|
|
- **XmlLoader/**: Data loading with caching
|
|
- **DataProcessor/**: API data transformation
|
|
|
|
#### Advanced Form System (`src/Form/Service/`)
|
|
- **Conditional Field States**: Dynamic field behavior based on participant data
|
|
- **Service Field Handlers**: Modular field processing with dependency resolution
|
|
- **Transportation Services**: Comprehensive pickup, parking, and transportation options
|
|
- **Real-time Updates**: HTMX integration for seamless UX
|
|
|
|
#### Service Architecture (`src/Service/`)
|
|
- **BookingService**: Core booking workflow management
|
|
- **TravelDataService**: Travel data access and caching
|
|
- **BookingPriceCalculatorService**: Real-time pricing calculations
|
|
|
|
## 🎯 Key Features
|
|
|
|
### ✅ Implemented Features
|
|
|
|
#### Multi-Step Booking Workflow
|
|
- Room selection with dynamic pricing display
|
|
- Participant registration with conditional fields
|
|
- Service selection (board, ski passes, courses, rentals)
|
|
- Real-time booking summary with pricing
|
|
|
|
#### Transportation Services
|
|
- **Transportation Selection**: Bus vs. car transport options
|
|
- **Pickup Services**: Location-based pickup with conditional visibility
|
|
- **Parking Services**: Self-organized transport parking options
|
|
- **Direction Mapping**: Outbound/inbound transportation handling
|
|
|
|
#### Advanced Form System
|
|
- **Conditional Field States**: Age-based, value-dependent field visibility
|
|
- **Dynamic Field Options**: Context-aware choice generation
|
|
- **HTMX Integration**: Real-time form updates without page refresh
|
|
- **XSS Protection**: Built-in security measures
|
|
|
|
#### Pricing & Display
|
|
- **Inline Pricing**: Service costs displayed in form options
|
|
- **Real-time Calculations**: Live pricing updates via HTMX
|
|
- **Smart Formatting**: Zero-price services handled gracefully
|
|
- **Unified Summary**: Integrated booking and pricing display
|
|
|
|
#### Service Integration
|
|
- **Field Handler Registry**: Modular field processing system
|
|
- **Service Registration**: Automatic field handler discovery
|
|
- **Dependency Resolution**: Smart field interdependency handling
|
|
|
|
### 🔄 Ongoing Development
|
|
- Age-based field constraints
|
|
- Enhanced pricing features (discounts, taxes)
|
|
- Advanced booking management
|
|
- Extended BPN API integration
|
|
|
|
## 🛠️ Development
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Development workflow
|
|
npm run dev # Development build
|
|
npm run watch # Watch mode
|
|
npm run build # Production build
|
|
|
|
# Testing
|
|
bin/phpunit # All tests
|
|
./vendor/bin/phpunit tests/Service/ # Specific directory
|
|
./vendor/bin/phpunit tests/BusProNet/ # API integration tests
|
|
|
|
# Code quality
|
|
./vendor/bin/php-cs-fixer fix # Fix code style
|
|
|
|
# Cache & debugging
|
|
bin/console cache:clear # Clear cache
|
|
bin/console debug:router # Debug routes
|
|
bin/console debug:container # Debug services
|
|
|
|
# Custom commands
|
|
bin/console app:cleanup-xml-dumps # Clean XML dump files
|
|
bin/console app:generate-keys # Generate OAuth2 keys
|
|
```
|
|
|
|
### Development Standards
|
|
|
|
#### Code Style
|
|
- PSR-12 compliance with `declare(strict_types=1)`
|
|
- PHP 8+ features (typed properties, constructor promotion, match expressions)
|
|
- Explicit comparisons and Yoda conditions
|
|
- Immutable DateTime objects (DateTimeImmutable, CarbonImmutable)
|
|
|
|
#### Architecture Patterns
|
|
- Service layer for business logic
|
|
- DTO pattern for type-safe form data
|
|
- Registry pattern for configurable components
|
|
- Field handler pattern for complex form processing
|
|
- Trait-based code reuse
|
|
|
|
## 🏛️ Technical Stack
|
|
|
|
### Backend
|
|
- **Framework**: Symfony 6.4 LTS
|
|
- **PHP**: 8.1+
|
|
- **Database**: MariaDB with Doctrine ORM
|
|
- **API Integration**: Custom XML client for BPN API
|
|
- **Authentication**: OAuth2 Server Bundle
|
|
|
|
### Frontend
|
|
- **JavaScript**: Stimulus (Hotwired) controllers
|
|
- **Dynamic Updates**: HTMX for seamless interactions
|
|
- **Styling**: TailwindCSS
|
|
- **Build Tool**: Webpack Encore
|
|
- **Templating**: Twig
|
|
|
|
### Development & Operations
|
|
- **Local Environment**: DDEV (PHP 8.2, MariaDB 10.11)
|
|
- **File Operations**: Flysystem with SFTP support
|
|
- **Date Handling**: Carbon for advanced date/time manipulation
|
|
- **Logging**: Monolog with multiple channels
|
|
- **Testing**: PHPUnit with Symfony bridge
|
|
|
|
## 📋 Form System Architecture
|
|
|
|
### Field Handler System
|
|
The application uses a sophisticated field handler system for processing complex participant forms:
|
|
|
|
```php
|
|
// Example field handler
|
|
class ParticipantTransportationOutboundFieldHandler extends AbstractParticipantFieldHandler
|
|
{
|
|
public function processField(/* ... */): void
|
|
{
|
|
// Complex field processing with conditional logic
|
|
}
|
|
|
|
public function getDependencies(): array
|
|
{
|
|
return ['assignedRoomId', 'dateOfBirth']; // Field dependencies
|
|
}
|
|
}
|
|
```
|
|
|
|
### Conditional Field States
|
|
Fields can have dynamic states based on conditions:
|
|
|
|
```php
|
|
// Age-based field state
|
|
$this->fieldStateConditions['advancedServices'] = [
|
|
'hidden' => new AgeRangeCondition(null, 15), // Hide for under 15
|
|
'required' => FieldValueCondition::equals('roomType', 'suite'),
|
|
];
|
|
```
|
|
|
|
### Available Field Handlers
|
|
- **Transportation**: Outbound/inbound transport selection
|
|
- **Pickup Services**: Location-based pickup options
|
|
- **Parking**: Self-organized transport parking
|
|
- **Accommodation**: Board, room assignment
|
|
- **Activities**: Ski passes, courses, rentals
|
|
- **Personal Data**: Age-aware field processing
|
|
|
|
## 💰 Pricing System
|
|
|
|
### Real-time Pricing Display
|
|
- **Inline Pricing**: Costs shown in form options
|
|
- **Live Updates**: HTMX-powered real-time calculations
|
|
- **Smart Formatting**: Zero-price services handled elegantly
|
|
- **Unified Summary**: Integrated pricing in booking summary
|
|
|
|
### Service Integration
|
|
```php
|
|
// Pricing calculation example
|
|
$serviceTotal = $this->bookingService->calculateServiceTotal($bookingDto);
|
|
$roomTotal = $this->bookingService->calculateRoomTotal($bookingDto);
|
|
$grandTotal = $serviceTotal + $roomTotal;
|
|
```
|
|
|
|
## 🔄 BusProNet API Integration
|
|
|
|
### XML Communication
|
|
- **Request Building**: Dynamic XML generation for BPN API
|
|
- **Response Parsing**: Structured XML parsing with validation
|
|
- **Data Caching**: Intelligent caching for performance
|
|
- **Error Handling**: Comprehensive error management
|
|
|
|
### Data Flow
|
|
1. Form submission triggers API request building
|
|
2. XML sent to BPN API endpoints
|
|
3. Response parsed and validated
|
|
4. Data transformed for application use
|
|
5. Results cached for performance
|
|
|
|
## 🧪 Testing Strategy
|
|
|
|
### Test Coverage
|
|
- **Unit Tests**: Service layer and business logic
|
|
- **Integration Tests**: API communication and data processing
|
|
- **Form Tests**: Field handler and validation logic
|
|
- **XML Tests**: API response parsing with fixtures
|
|
|
|
### Running Tests
|
|
```bash
|
|
# All tests
|
|
./vendor/bin/phpunit
|
|
|
|
# Specific test suites
|
|
./vendor/bin/phpunit tests/BusProNet/ # API integration
|
|
./vendor/bin/phpunit tests/Service/ # Service layer
|
|
./vendor/bin/phpunit tests/Form/ # Form processing
|
|
```
|
|
|
|
## 📚 Documentation
|
|
|
|
### Available Documentation
|
|
- **[PROJECT_OVERVIEW.md](PROJECT_OVERVIEW.md)**: Comprehensive architecture and implementation guide
|
|
- **[CLAUDE.md](../CLAUDE.md)**: Development guidelines for AI assistance (root level)
|
|
|
|
### Architecture Documentation
|
|
Each major system component has detailed documentation covering:
|
|
- Implementation patterns
|
|
- Usage examples
|
|
- Extension guidelines
|
|
- Testing strategies
|
|
|
|
## 🔒 Security & Configuration
|
|
|
|
### Environment Setup
|
|
- BPN API credentials in `.env.local`
|
|
- OAuth2 encryption keys via custom command
|
|
- SFTP configuration for deployment
|
|
- Logging channels for monitoring
|
|
|
|
### Security Features
|
|
- XSS protection in form processing
|
|
- OAuth2 authentication
|
|
- Secure API communication
|
|
- Input validation and sanitization
|
|
|
|
## 🚀 Deployment
|
|
|
|
### Production Requirements
|
|
- PHP 8.1+ with required extensions
|
|
- MariaDB 10.11+
|
|
- Web server (Apache/Nginx)
|
|
- SFTP access for file operations
|
|
- BPN API credentials
|
|
|
|
### Deployment Steps
|
|
1. Install dependencies (`composer install --no-dev`)
|
|
2. Generate OAuth2 keys (`bin/console app:generate-keys`)
|
|
3. Run database migrations (`bin/console doctrine:migrations:migrate`)
|
|
4. Build production assets (`npm run build`)
|
|
5. Configure environment variables
|
|
6. Set up SFTP access for XML exports
|
|
|
|
## 🤝 Contributing
|
|
|
|
### Development Workflow
|
|
1. Follow PSR-12 coding standards
|
|
2. Use type declarations consistently
|
|
3. Write comprehensive tests for new features
|
|
4. Update documentation for architectural changes
|
|
5. Use the field handler pattern for form extensions
|
|
|
|
### Key Patterns
|
|
- **Service Layer**: Business logic separation
|
|
- **DTO Pattern**: Type-safe data transfer
|
|
- **Registry Pattern**: Component discovery
|
|
- **Field Handlers**: Modular form processing
|
|
|
|
## 📞 Support
|
|
|
|
### Logging Channels
|
|
- **app**: General application logs
|
|
- **bpn**: BusProNet API interactions
|
|
- **security**: Authentication/authorization
|
|
- **db**: Database-related logs
|
|
|
|
### Debugging
|
|
- Use `bin/console debug:router` for route inspection
|
|
- Use `bin/console debug:container` for service inspection
|
|
- Check logs in `var/log/` for troubleshooting
|
|
- Use DDEV for consistent development environment
|
|
|
|
---
|
|
|
|
**Version**: 2.0
|
|
**Symfony**: 6.4 LTS
|
|
**PHP**: 8.1+
|
|
**Status**: Production Ready
|
|
**Last Updated**: 2025-01-XX |