Catering API

A RESTful API for managing catering facilities, locations, tags, and employees with JWT authentication and automated email notifications.

🚀 Quick Start

Prerequisites

• Docker & Docker Compose OR
• PHP 8.3+, MySQL 8.0+, Composer
• Resend API key (free tier: 3,000 emails/month)

Installation

Using Docker (Recommended):

# Clone and navigate to project
cd Catering-API

# Copy environment file
cp .env.example .env

# Start containers
docker-compose up -d

# Setup database with sample data
docker exec catering_api_app php sql/database_manager.php setup

# Verify installation
curl http://localhost:8080/health

Using Local Development (XAMPP/MAMP):

# Install dependencies
composer install

# Copy and configure .env
cp .env.example .env

# Setup database
php sql/database_manager.php setup

# Verify installation
curl http://localhost/Catering-API/public/health

📚 Detailed Installation Guide: docs/PROJECT-INSTALLATION.md

---

📖 Documentation

Document	Description
API Documentation	Complete API endpoint reference
Installation Guide	Detailed setup instructions
Testing Guide	How to run tests
Unit Test Strategy	Testing best practices
Refactoring Log	Code improvements history
Project Structure	Codebase organization
Database Management	Database operations

---

🔐 Authentication

The API uses JWT (JSON Web Token) authentication.

1. Configure Environment (.env)

# Generate JWT secret: php -r "echo base64_encode(random_bytes(32));"
JWT_SECRET_KEY=your_secure_jwt_secret

# Hash password: php -r "echo password_hash('yourpass', PASSWORD_BCRYPT);"
LOGIN_USERNAME=admin
LOGIN_PASSWORD=$2y$10$hashed_password_here

# Email Configuration (get free API key from resend.com)
RESEND_API_KEY=re_YOUR_API_KEY_HERE
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME="Your Company Name"

2. Login

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpass"}'

Response:

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

3. Use Token

curl http://localhost:8080/facilities \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

---

🛠️ API Endpoints

Base URLs

• Docker: http://localhost:8080
• Local: http://localhost/Catering-API/public

Health Check

• GET /health - API health status (no auth required)

Authentication

• POST /auth/login - Get JWT token

Facilities

• GET /facilities - List all facilities (pagination supported)
• GET /facilities/{id} - Get facility by ID
• GET /facilities/search - Search facilities with filters
• POST /facilities - Create new facility
• PUT /facilities/{id} - Update facility
• DELETE /facilities/{id} - Delete facility

Locations

• GET /locations - List all locations
• GET /locations/{id} - Get location by ID
• POST /locations - Create new location
• PUT /locations/{id} - Update location
• DELETE /locations/{id} - Delete location

Tags

• GET /tags - List all tags
• GET /tags/{id} - Get tag by ID
• POST /tags - Create new tag
• PUT /tags/{id} - Update tag
• DELETE /tags/{id} - Delete tag

Employees

• GET /employees - List all employees
• GET /employees/{id} - Get employee by ID
• GET /employees/facility/{facility_id} - Get employees by facility
• POST /employees - Create new employee (sends welcome email automatically)
• PUT /employees/{id} - Update employee
• DELETE /employees/{id} - Delete employee

---

📝 API Examples

Create Facility

curl -X POST http://localhost:8080/facilities \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Grand Conference Hall",
    "location_id": 1,
    "tagIds": [1, 2],
    "tagNames": ["Wedding", "Corporate"]
  }'

Search Facilities

# Search with filters and AND operator
curl "http://localhost:8080/facilities/search?query=Conference&filter=city,tag&operator=AND" \
  -H "Authorization: Bearer YOUR_TOKEN"

Pagination

curl "http://localhost:8080/facilities?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Employee (Sends Welcome Email)

curl -X POST http://localhost:8080/employees \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "1234567890",
    "address": "123 Main St",
    "facilityIds": [1, 2]
  }'

---

📧 Email Notifications

Automated email notifications via Resend API (3,000 emails/month free).

Features:

• Welcome email on employee creation
• HTML + plain text templates
• Custom domain ([email protected])
• Non-blocking (employee creation succeeds even if email fails)

Quick Setup:

# .env
RESEND_API_KEY=re_YOUR_KEY_HERE          # Get from resend.com
MAIL_FROM_ADDRESS=[email protected]
MAIL_FROM_NAME="Catering Management"

Monitor: resend.com/emails | docker logs catering_api_app | grep -i email

---

🧪 Testing

# Docker
docker-compose exec app vendor/bin/phpunit
docker-compose exec app vendor/bin/phpunit --testdox

# Local
vendor/bin/phpunit
composer test-unit

# With coverage
composer test-coverage

Current Status: 166/166 tests passing (100%) ✅

📚 Complete Testing Guide: docs/TEST_COMMANDS.md

---

🔧 Database Management

# Docker
docker exec catering_api_app php sql/database_manager.php [command]

# Local
php sql/database_manager.php [command]

Available Commands:

• setup - Fresh installation with sample data
• status - Check database state
• reset - Clear and reload data (dev only)
• clear-data - Remove data, keep structure
• drop-tables - Remove all tables (dangerous!)

📚 Details: sql/README.md

---

📊 Sample Data

After running setup, you get:

• ✅ 25 locations (Dutch cities)
• ✅ 25 catering facilities
• ✅ 7 category tags
• ✅ Realistic relationships

---

🐳 Docker Services

Service	Container	Port	Purpose
Nginx	catering_api_nginx	80, 443	Web server
PHP-FPM	catering_api_app	8080	Application
MySQL	catering_api_db	3307	Database
phpMyAdmin	catering_phpmyadmin	8081	DB management

Useful Commands:

# View logs
docker-compose logs -f app

# Access shell
docker-compose exec app bash

# Stop containers
docker-compose down

# Restart
docker-compose restart

---

📦 Project Structure

Catering-API/
├── App/
│   ├── Controllers/      # HTTP request handlers
│   ├── Services/         # Business logic
│   ├── Repositories/     # Data access layer
│   ├── Models/          # Domain models
│   ├── Domain/
│   │   └── Exceptions/  # Custom exceptions
│   ├── Helpers/         # Utility classes
│   ├── Middleware/      # JWT authentication
│   └── Plugins/         # HTTP, DI, Database
├── docs/                # Documentation
├── sql/                 # Database scripts
├── tests/               # PHPUnit tests
└── public/              # Entry point

📚 Detailed Structure: docs/PROJECT_STRUCTURE.md

---

⚡ Key Features

• ✅ RESTful API design
• ✅ JWT authentication
• ✅ Automated email notifications (Resend API)
• ✅ Custom domain email ([email protected])
• ✅ Domain-driven exception handling
• ✅ Comprehensive input validation
• ✅ Security-focused logging (sensitive data sanitization)
• ✅ Pagination support
• ✅ Advanced search and filtering
• ✅ Docker containerization
• ✅ 100% unit test coverage (166 tests)
• ✅ PSR-4 autoloading

---

🔒 Security Features

• JWT token-based authentication
• Password hashing (bcrypt)
• Input sanitization (XSS protection)
• SQL injection prevention (prepared statements)
• Sensitive data sanitization in logs
• HTTPS support (production ready)

---

🛡️ Error Handling

The API uses standard HTTP status codes:

Code	Meaning
200	Success
201	Created
400	Bad Request (validation errors)
401	Unauthorized (invalid/missing token)
404	Not Found
409	Conflict (resource in use)
422	Unprocessable Entity (business rule violation)
500	Internal Server Error

Example Error Response:

{
  "error": "Facility with ID 999 not found"
}

---

🤝 Contributing

1. Write tests for new features
2. Follow PSR-12 coding standards
3. Update documentation
4. Run tests before committing

---

📄 License

This project is open source and available for educational purposes.

---

📞 Support

For issues or questions, please refer to the documentation in the docs/ directory.