README

A minimal application skeleton for quickly bootstrapping new projects with the Ondine PHP microframework. Get a fully functional REST API with authentication up and running in minutes.

✨ Features

🚀 Rapid Setup: Working API in under 5 minutes
🔐 JWT Authentication: Secure login with refresh tokens
👥 User Management: Full CRUD for users and profiles
📚 Interactive Docs: Built-in Swagger UI at /docs
🗄️ Database Ready: SQLite (dev) or MariaDB/MySQL (prod)
🧩 Extensible: Easy to add controllers, routes, and middleware

📦 Installation

Via Composer Create-Project

# Recommended: Install stable version (when available)
composer create-project pnbarbeito/ondine-skeleton my-app

# Alternative: Install development version
composer create-project pnbarbeito/ondine-skeleton my-app dev-main

# Or with dev stability
composer create-project pnbarbeito/ondine-skeleton my-app --stability dev

🚀 Quick Start

Install dependencies:
```
composer install
```

Configure environment:

cp config/.env.example config/.env
# Edit config/.env with your settings

Run migrations:
```
php scripts/migrate.php
```
Start the server:
```
php -S 0.0.0.0:8000 -t public
```
Test it:
- Frontend: http://localhost:8000
- API Docs: http://localhost:8000/docs

� Production Deployment

The skeleton includes a complete Docker-based production setup in the docker/ folder:

docker-compose.prod.yml: Production-ready container orchestration with Nginx, PHP-FPM, and MariaDB
Dockerfile: Multi-stage build for optimized PHP container
nginx.conf: Nginx configuration with FastCGI proxy and static file serving
Environment setup: Pre-configured for production with proper security settings

Quick Production Setup

Navigate to docker folder:
```
cd docker
```

Configure environment:

cp .env.example .env
# Edit .env with your production settings (database, secrets, etc.)

Deploy:

docker compose -f docker-compose.prod.yml up -d

Run migrations:

docker compose -f docker-compose.prod.yml exec app php scripts/migrate.php

The application will be available at http://localhost (or your configured domain).

📖 Full documentation: See docker/README.md and docker/README.es.md for detailed production deployment guides in English and Spanish.

�📋 API Endpoints

The skeleton provides ready-to-use REST endpoints under /api:

Authentication

POST /api/login - User login
POST /api/refresh - Refresh JWT token
POST /api/logout - Logout user
GET /api/me - Get current user info

Users (CRUD)

GET /api/users - List users
GET /api/users/{id} - Get user by ID
POST /api/users - Create user
PUT /api/users/{id} - Update user
DELETE /api/users/{id} - Delete user

Profiles

GET /api/profiles - List profiles
GET /api/profiles/{id} - Get profile by ID

Example Usage

curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"sysadmin","password":"SecureAdmin2025"}'

Use the token for authenticated requests:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8000/api/me

📁 Project Structure

my-app/
├── config/          # Environment configuration (.env)
├── data/            # Database files (SQLite)
├── migrations/      # Database migrations
├── public/          # Web root (index.php, docs/)
├── scripts/         # Utility scripts (migrate.php)
├── src/             # Application code
│   ├── Controllers/ # API controllers
│   ├── Middleware/  # Custom middleware
│   └── ...          # Models, services, etc.
├── tests/           # PHPUnit tests
└── vendor/          # Composer dependencies

⚙️ Configuration

Environment Variables

Copy config/.env.example to config/.env and configure:

# Database
DB_DRIVER=sqlite  # or mariadb
DB_SQLITE_PATH=./data/database.sqlite

# JWT Secret (CHANGE IN PRODUCTION!)
JWT_SECRET=your_secure_jwt_secret_here

# Admin User Seeds
SEED_ADMIN_USERNAME=sysadmin
SEED_ADMIN_PASSWORD=SecureAdmin2025

Database

SQLite (Default - Development):

File: data/database.sqlite
No additional setup required

MariaDB/MySQL (Production):

DB_DRIVER=mariadb
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_DATABASE=ondine
MYSQL_USER=your_user
MYSQL_PASSWORD=your_password

🛠️ Development

Running Tests

composer install --dev  # Install development dependencies
composer test
# or
./vendor/bin/phpunit --colors=always

Test Coverage

composer test-coverage
# View coverage report in coverage/index.html

Migrations

# Run all migrations
php scripts/migrate.php migrate

# Rollback last migration
php scripts/migrate.php rollback 1

# Custom seed values
env SEED_ADMIN_USERNAME=custom php scripts/migrate.php migrate

Adding New Features

Controllers: Add to src/Controllers/
Routes: Register in public/index.php
Middleware: Add to src/Middleware/
Migrations: Create in migrations/

🔧 API Documentation

Interactive Swagger UI available at http://localhost:8000/docs

Automatically captures JWT tokens from login responses
Test all endpoints directly from the browser
View request/response schemas

🐛 Troubleshooting

Permission Errors in Docker

Use named volumes for persistent storage or run migrations locally.

Database Connection Issues

Verify .env configuration
Ensure database server is running
Check user permissions

Port Conflicts

Change the port in the PHP server command:

php -S 0.0.0.0:8081 -t public

🤝 Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

Ondine Framework - Main framework repository
Packagist - Composer package
Documentation - Full documentation

Built with ❤️ using the Ondine microframework.

pnbarbeito / ondine-skeleton

Maintainers

Details