README

FredoBase is a lightweight plain-PHP API micro framework by Fredoware for quickly creating database-backed CRUD APIs.

It is intentionally small, readable, and easy to copy for future Fredoware projects.

FredoBase gives you:

• one bootstrap file
• reusable request/response/database helpers
• model factory functions
• file-based API endpoints
• SQL migrations
• module generator

Structure

api/                 Public API endpoint files
app/Core/            Core request, response, database, repository classes
app/Modules/         Controllers, repositories, and validators by module
app/Support/         Shared helpers, model factories, mail helper
database/            Schema and migration SQL files
docs/                Tutorials
routes/api.php       Module route definitions
fredobase            FredoBase CLI
.env.example         Environment template

Install With Composer

After the package is published on Packagist, create an application with:

composer create-project fredoware/fredobase my-api
cd my-api

Composer installs the dependencies and runs php fredobase install. The installer creates .env, generates a unique APP_KEY, and never overwrites an existing environment file.

Before the package is on Packagist, it can be tested directly from GitHub:

composer create-project fredoware/fredobase my-api dev-main --repository='{"type":"vcs","url":"https://github.com/fredoware/fredobaseapi"}'

Manual Setup

1. Install dependencies and prepare the project:

composer install
php fredobase install

1. Check your database settings in .env:

DB_HOST=localhost
DB_DATABASE=appbase.db
DB_USERNAME=root
DB_PASSWORD=

1. Run migrations:

php fredobase migrate

1. Test the health endpoint:

http://localhost/appbase-api/api/health.php

Expected response:

{
  "status": "success",
  "message": "FredoBase API is running."
}

CLI Commands

Show help:

php fredobase help

Prepare a new checkout (safe to run more than once):

php fredobase install

Create a CRUD module:

php fredobase make:module product

Run migrations:

php fredobase migrate

After adding a field to a module model, generate and apply its migration:

php fredobase make:migration product
php fredobase migrate

The module generator creates:

app/Modules/Product/ProductController.php
app/Modules/Product/ProductModel.php
app/Modules/Product/ProductRepository.php
app/Modules/Product/ProductValidator.php
database/migrations/YYYY_MM_DD_HHMMSS_create_product_table.sql

It also registers REST routes inside routes/api.php.

Starter Endpoints

• api/health.php - API and database health check
• api/authLogin.php - basic account login
• api/authLogout.php - revoke the current bearer token
• api/index.php - dispatch routed module requests

Starter Tables

• account - minimal user/account table
• auth_token - hashed, expiring bearer tokens
• sample_item - generic CRUD example table

Creating A New Module

Read the full tutorial:

docs/creating-a-module.md

Quick version:

php fredobase make:module product
php fredobase migrate

Then test:

GET    http://localhost/appbase-api/api/products
GET    http://localhost/appbase-api/api/products/1
POST   http://localhost/appbase-api/api/products
PUT    http://localhost/appbase-api/api/products/1
DELETE http://localhost/appbase-api/api/products/1

Write routes require a bearer token by default. Existing file-based endpoints remain supported for backward compatibility.

Authentication

Run migrations and create the first administrator:

php fredobase migrate
php fredobase make:admin admin@example.com change-this-password Admin User

Login with a JSON POST request to api/authLogin.php. A successful response contains a bearer token. Send it to protected endpoints with:

Authorization: Bearer YOUR_TOKEN

Protect an endpoint and access the authenticated account with:

$user = requireAuth();

Require one or more roles with:

$admin = requireRole('Admin');
$staff = requireRole(['Admin', 'Staff']);

Revoke the current token by sending an authenticated POST request to api/authLogout.php. Token lifetime defaults to 24 hours and can be changed with AUTH_TOKEN_TTL in .env.

GitHub Notes

Commit .env.example, but do not commit .env.

The .gitignore already excludes .env, logs, temporary files, and uploaded media.

fredobaseapi