EchoAPI – Lightweight PHP Microstack for REST APIs

EchoAPI is a minimalist microstack designed for developers who want to build RESTful APIs in PHP with speed, clean structure, and low coupling. Rather than being a full-stack framework, EchoAPI acts as a backend toolbox — delivering only the essential components needed for routing, validation, authentication, caching, logging, and external integrations.

Ideal for developers seeking a functional, lightweight, and maintainable API architecture without the overhead of complex frameworks.

---

📄 System Requirements

• PHP >= 8.1

• Composer >= 2.x

• MySQL 8+ or MariaDB

• Redis (optional, for caching)

• PHP Extensions:

  • pdo_mysql
  • mbstring
  • openssl
  • curl
  • json

---

✅ Key Features

• Routing with AltoRouter

• Lightweight ORM using Medoo

• Data validation with Respect\Validation

• Structured logging via Monolog

• Multiple authentication layers:

  • API Key
  • JWT (JSON Web Tokens)
  • OAuth 2.0 (Google, Microsoft, LinkedIn, etc.)

• Flexible caching via Symfony Cache (Filesystem, Redis, APCu)

• Native email support with PHPMailer

• Real-time error alerts through Telegram

---

🛠️ Technologies Used

• PHP 8.x
• Medoo (PDO wrapper)
• AltoRouter (Routing)
• Monolog (Logging)
• Respect\Validation (Validation)
• Symfony Console (CLI scripts)
• Symfony Cache (Multi-driver caching)
• Predis (Redis integration)
• PHPMailer (SMTP email)
• Firebase PHP-JWT (JWT support)
• TheNetworg OAuth2 Azure (Azure AD)
• League OAuth2 Client (Google, LinkedIn)
• vlucas/phpdotenv (Environment config)

---

📁 Project Structure

project-root/
├── app/                 # Swagger/OpenAPI docs
├── Bootstrap           # App bootstrap process
├── config/              # Configuration files
├── core/                # Kernel, helpers, services
├── storage/             # Cache & logs
├── middleware/          # HTTP middlewares
├── routes/              # Route definitions
├── app/                 # App logic (MVC)
├── .env                 # Environment settings
├── composer.json        # Dependencies & scripts
└── README.md

---

🗃 Database Initialization

EchoAPI comes with a default database structure and initial data available in:

core/Migration/auth-migrations.sql

This script creates the basic authentication tables: users, roles, user_tokens, and password_resets.

Default user

• Email: master@echoapi.local
• Password: master!123@

⚠️ The password is hashed in the database. Use this user only for first login or local development.

Automatic migration with Docker

If you're using Docker, set the following in your .env:

AUTO_MIGRATE=true

This will automatically import the auth-migrations.sql during container startup.

🔐 After successful migration, it is strongly recommended to set AUTO_MIGRATE=false to prevent re-imports and protect data integrity.

---

📦 Install via Composer

To start a new project with EchoAPI, run:

composer create-project jandersongarcia/echoapi echoapi-example

More details: https://packagist.org/packages/jandersongarcia/echoapi

---

🚀 Manual Installation

git clone https://github.com/jandersongarcia/EchoAPI.git
cd EchoAPI
composer install
cp .env.example .env
chmod -R 775 storage

Configure your .env with DB, Redis, email, and Telegram.

---

🚧 Docker Support

EchoAPI supports Docker for rapid onboarding.

docker compose up --build -d
docker compose exec app composer install

Access: http://localhost:8080

---

🚡 Request Lifecycle

1. Entry via public/index.php
2. Middlewares (API key, CORS, Auth)
3. Routes resolved via AltoRouter
4. Controller invoked
5. JSON response returned

---

🔐 Authentication Methods

API Key

• Set API_KEY=your_token in .env
• Send in header: Authorization: Bearer YOUR_KEY

Generate:

composer generate:key

JWT Auth

Generate system:

composer make:auth

Includes login, register, password reset, logout endpoints.

OAuth 2.0

Supports Google, LinkedIn, Azure, Facebook, GitHub.

composer make:oauth google linkedin

---

📧 Email Support

Uses PHPMailer configured via config/php_mailer.php.

$mail = new MailHelper();
$mail->send('to@example.com', 'Subject', '<p>Body</p>');

---

🔎 Caching

Configured via .env:

CACHE_DRIVER=redis
REDIS_HOST=redis

Fallbacks to filesystem if not available.

---

📃 Swagger Documentation

composer swagger:build

Output: app/docs/openapi.json (for Swagger UI or Redoc).

⚠️ When APP_ENV=production, access to /v1/docs/swagger.json is disabled for security reasons.

Access the interactive Swagger UI at the /docs/ endpoint of your deployed application. For example:

http://localhost:8080/docs/     (local development)

---

💬 Telegram Notifications

Enable in .env:

TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_CHAT_ID=xxx
ERROR_NOTIFY_CATEGORIES=critical,error,alert

---

🗒 Logging

• Logs in storage/logs/
• app.log: info+
• error.log: error+
• Rotated daily

Test:

composer log:test

---

⚙️ Available Scripts

Command	Description
make:module	Create controller/service/model
delete:module	Remove a module
make:crud	CRUD generator
delete:crud	Delete CRUD set
list:crud	List registered CRUDs
make:auth	JWT authentication scaffold
delete:auth	Remove JWT files
make:oauth	OAuth provider integration
delete:oauth	Remove OAuth config
generate:key	Generate API Key
log:test	Generate sample logs
telegram:test	Test Telegram alert
swagger:build	Build OpenAPI spec

---

📜 Sample .env

APP_ENV=development
APP_DEBUG=true
API_KEY=your_api_key

DB_HOST=db
DB_PORT=3306
DB_NAME=echoapi
DB_USER=root
DB_PASS=root

CACHE_DRIVER=redis
REDIS_HOST=redis

TELEGRAM_BOT_TOKEN=xxx
TELEGRAM_CHAT_ID=xxx
ERROR_NOTIFY_CATEGORIES=critical,error,alert

---

🧹 Limpeza de Arquivos Temporários (clear:storage)

Para facilitar a manutenção da aplicação, o EchoStack oferece um comando para limpar os diretórios de cache, logs e lixeira (trash).

🔧 Uso

composer clear:storage [--only=cache|logs|trash] [--keep-days=N] [--dry-run]

⚙️ Opções

Opção	Descrição
--only=cache	Limpa apenas a pasta storage/cache
--only=logs	Limpa apenas os arquivos da pasta storage/logs
--only=trash	Limpa apenas a pasta storage/trash
--keep-days=7	Mantém arquivos modificados nos últimos N dias
--dry-run	Apenas simula a exclusão, exibindo os arquivos que seriam removidos

📦 Exemplos

# Limpa todos os diretórios (cache, logs e trash)
composer clear:storage

# Limpa apenas o cache
composer clear:storage --only=cache

# Limpa logs mais antigos que 3 dias
composer clear:storage --only=logs --keep-days=3

# Simula a limpeza da lixeira sem excluir
composer clear:storage --only=trash --dry-run

Os arquivos excluídos são listados diretamente no terminal. Diretórios vazios também são removidos automaticamente.

---

⚠️ Error Reference

Code	Description	Details
E001	.env not found	The .env file is missing. Rename .env.example to .env.
E002	Missing environment variable	One or more required environment variables are missing or empty.

Example: E001 Response

{
  "error": "Environment file not found",
  "message": "The \".env\" file is required. Please rename \".env.example\" to \".env\" and configure your environment variables.",
  "code": "E001"
}

Example: E002 Response

{
  "error": "Missing environment variable",
  "message": "The environment variable 'DB_HOST' is missing or empty in your .env file.",
  "code": "E002"
}

---

📊 Changelog

v2.1.1 (2025-07)

• PHP 8.3 support
• OAuth providers expanded
• Docker support enhanced
• Cache abstraction with fallback

v2.1.0 (2025-06)

• JWT authentication module
• Telegram alerts with full trace
• Restructure of CLI commands

---

📋 License

MIT License Developed by Janderson Garcia