README

Ondine is a tiny PHP microframework designed to expose REST endpoints and integrate with frontends (for example, React). This repository now provides the library in src/ and an example application under examples/public/.

Project layout

src/ — core library (PSR-4, exportable as a Composer package)
examples/public/ — example application and test UI that consumes the library
migrations/ — versioned PHP migrations
data/ — default storage for the SQLite database file

Requirements

PHP 7.4+ (PHP 8+ recommended)
Composer (recommended for PSR-4 autoload and tooling)

Quickstart

This repository contains the library under src/ and an example application under examples/public/.

Install dependencies (recommended)

composer install

Using Ondine as a Composer dependency

If you publish the package to Packagist (recommended name: ondine/ondine), you can install it in another project using:

composer require ondine/ondine

For local development you can use a path repository in your project's composer.json:

{
  "repositories": [
    {
      "type": "path",
      "url": "../path/to/Ondine",
      "options": { "symlink": true }
    }
  ]
}

Then run composer require ondine/ondine:@dev in the consuming project.

Configure environment variables for the example app

Copy the example and edit it (example uses config/.env in the repository root):

cp config/.env.example config/.env
# Edit `config/.env` and set DB_DRIVER and secrets as needed

By default Ondine uses SQLite and stores the file at data/database.sqlite in the project root. To use MariaDB set DB_DRIVER=mariadb and update the MYSQL_* variables in the .env file.

Run the example application

Start a local PHP server (from repository root):

php -S 0.0.0.0:8080 -t examples/public

Open http://localhost:8080 to access the example UI and http://localhost:8080/docs for the OpenAPI UI.

Running migrations for the example app (examples use the scripts in examples/scripts/):

php examples/scripts/migrate.php migrate

Rollback (e.g. rollback last migration):

php examples/scripts/migrate.php rollback 1

API documentation (OpenAPI / Swagger)

Open http://localhost:8080/docs to access the interactive API docs. The UI captures the token returned by POST /api/login and applies it automatically as Authorization: Bearer <token> for subsequent requests.

Main endpoints

Authentication
- POST /api/login — body: { username, password } → returns { token, refresh_token }
- POST /api/token/refresh — body: { refresh_token } → returns { token }
- POST /api/logout — body: { refresh_token } → revokes the session
- GET /api/me — requires Authorization: Bearer <token>
Users
- GET /api/users
- GET /api/users/{id}
- POST /api/users
- PUT /api/users/{id}
- PUT /api/users/{id}/change-password — body: { new_password } → requires Authorization: Bearer <token>
- DELETE /api/users/{id}
Profiles
- GET /api/profiles
- GET /api/profiles/{id}
- GET /api/profiles/distinct-permissions — requires Authorization: Bearer <token>
- POST /api/profiles
- PUT /api/profiles/{id}
- DELETE /api/profiles/{id}
User (authenticated user operations)
- PUT /api/user/theme — body: { theme } → requires Authorization: Bearer <token>
- PUT /api/user/profile — body: { first_name?, last_name? } → requires Authorization: Bearer <token>
- PUT /api/user/password — body: { current_password, new_password } → requires Authorization: Bearer <token>

Testing

The test suite uses PHPUnit and an ephemeral SQLite database for each test. Run the tests with:

composer test
# or
./vendor/bin/phpunit --colors=always

Seed variables (used by migrations)

SEED_PROFILE_NAME — default: Administrator
SEED_PROFILE_PERMISSIONS — JSON string, default: {"admin":1,"profiles":1,"users":1}
SEED_ADMIN_USERNAME — default: sysadmin
SEED_ADMIN_PASSWORD — default: SysAdmin8590
SEED_ADMIN_FIRSTNAME — default: Sys
SEED_ADMIN_LASTNAME — default: Admin
SEED_ADMIN_STATE — default: 1

Migrations

Migrations are simple PHP files under migrations/. They are driver-aware (SQLite vs MariaDB) and seed the initial profile and admin user using environment variables so you can customize them at deploy or test time.

Common commands (fish / bash compatible)

Ensure dependencies and environment file:

composer install
cp config/.env.example config/.env
# Edit `config/.env` with your `DB_DRIVER` and connection details if needed

Run all migrations:

php scripts/migrate.php migrate

Rollback the last N migrations (example: rollback 1):

php scripts/migrate.php rollback 1

Set seed variables (example):

env SEED_ADMIN_USERNAME=customadmin SEED_ADMIN_PASSWORD=s3cret php scripts/migrate.php migrate

Skeleton Project

This repository includes a minimal skeleton application that serves as a starting point for building Ondine-based applications. The skeleton is available as a separate repository at pnbarbeito/ondine-skeleton.

Creating a project from the skeleton

Option A — Using Composer create-project (recommended):

# Install stable version
composer create-project pnbarbeito/ondine-skeleton my-app

# Or 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

Option B — Manual copy (for development):

# Copy the skeleton to a new folder
cp -R examples/skeleton my-app
cd my-app
composer install
cp config/.env.example config/.env
# Edit config/.env if needed
php scripts/migrate.php
php -S 0.0.0.0:8000 -t public

The skeleton includes:

Complete project structure with PSR-4 autoloading
JWT authentication with refresh tokens
User management with profiles and permissions
Interactive API documentation (Swagger UI)
Docker configuration for production deployment
PHPUnit test suite
Example controllers and middleware

Security & Notes

Configure JWT_SECRET and REFRESH_TOKEN_SECRET in config/.env and do not commit them to source control.
SQLite is intended for development and testing. For production use MariaDB/MySQL or PostgreSQL.
Consider Redis for rate-limiting in high-concurrency environments.
The framework supports profile-based permissions for fine-grained access control.

Contributing

Contributions are welcome. Please open issues with proposed changes or submit pull requests. For development:

composer install
./vendor/bin/phpunit --colors=always

License

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

pnbarbeito / ondine

Maintainers

Details