Download the PHP package marcuwynu23/narciso without Composer

Lightweight PHP web library. Routing, middleware, CORS, rate limiting, security headers, and database — no framework required. ➡️ **[Read the full user guide →](USER-GUIDE.md)**

Table of Contents

• What Is Narciso?
• Use Cases
• Benefits
• Advantages Over Other Tools
• User Guide
• Installation
• Quick Start
• API Reference
• Configuration
• Example Output
• CI/CD Integration
• Development
• Architecture
• Contributing
• License

What Is Narciso?

Narciso is a lightweight PHP web library built on top of native PHP, inspired by FastAPI and Flask. It gives you a simple, expressive API for routing, middlewares, CORS, rate limiting, security headers, and database access — so you can build APIs and web apps quickly without a heavy framework.

What It Does

• Route — Map HTTP methods and URL patterns (including path parameters like /users/:id) to handler callbacks
• Protect — Add security headers, CORS, and rate limiting with one-line method calls
• Connect — Configure MySQL or SQLite in a single config array; $app->db is ready in every route
• Respond — Return JSON, XML (auto-detected from query/header), or render PHP views
• Obfuscate — Hide or fake the X-Powered-By header to keep the server technology private
• Extend — Add custom middleware via a callable or the MiddlewareInterface
• Session — Start PHP sessions with handleSession()

Why Use It?

The Philosophy

1. Minimal setup, maximum value. A working API server in 10 lines of code.
2. Your process stays yours. No forced directory structure, no service container, no DI. Just PHP.
3. Native-first. Built on mysqli, SQLite3, and native PHP sessions — no runtime dependencies.

Use Cases

Benefits for Developers

• ~10 second setup — composer require marcuwynu23/narciso
• No runtime dependencies — Zero Composer dependencies at runtime
• Familiar API — Inspired by Flask and FastAPI; route handlers receive ($app, $params)
• Path parameters — /users/:id syntax like Express.js
• Middleware onion — Add as many middlewares as needed; they wrap in order
• JSON/XML auto-detection — sendAPI() reads Accept header or ?format= query param
• Built-in security — Security headers, CORS, rate limiting ship with the library
• Technology obfuscation — Remove or fake X-Powered-By with setPoweredBy()
• PHP 7.4+ compatible — Works on legacy and modern PHP
• Fully tested — PHPUnit suite with 36+ tests covering routing, middleware, database, and API

Advantages Over Other Tools

Installation

Requires PHP 7.4+ and the json extension. For MySQL use, install php-mysql. For SQLite, install php-sqlite3.

Verify:

Quick Start

Create index.php:

Run it:

Test it:

API Reference

route(string $method, string $path, callable $handler)

Register a route handler.

use($middleware)

Add a middleware to the pipeline.

useSecurityHeaders(?array $headers = null)

useCors(array $origins, array $methods, array $headers, bool $credentials, int $maxAge)

useRateLimit(int $maxRequests, int $windowSeconds)

sendAPI($data, array $options)

setPoweredBy($value)

handleDatabase(array $config)

Configuration

Narciso uses method calls, not config files. Configuration precedence:

1. Method arguments (highest)
2. Built-in defaults (lowest)

Example Output

JSON Response

XML Response

Rate Limited Response

CI/CD Integration

GitHub Actions

Development

Project Structure

Architecture

1. Application is the central class — it holds routes, middleware config, database config, and session state
2. Routes are registered as (method, pattern, handler) tuples. Path parameters (:param) are converted to regex with named groups
3. Middleware pipeline is an onion-wrapped array. Each middleware calls $next() to pass control inward
4. Request dispatch happens in run(): middleware stack executes first, then route matching, then the matched handler
5. Database connections are lazy — created on first access via $app->db magic getter
6. API format detection checks ?format= query param first, then Accept header, then defaults to JSON

Contributing

See CONTRIBUTING.md for full details — coding standards, commit conventions, PR process, and more.

License

Narciso is open source under the Apache License, Version 2.0.