Download the PHP package andrewthecoder/arcmvc without Composer

Arc

A lightweight, modern PHP MVC framework. Small core, batteries included, built for PHP 8.4+.

Principles

• No hidden magic. Request flow is traceable from public/index.php to response.
• Decoupled core: uses a dedicated DI container for service management.
• Secure defaults: CSRF protection, XSS escaping, SQL injection prevention, security headers.
• Fast startup, low memory by default.
• One canonical way to do common things.
• First-party modules for the common website stack, each optional and independently replaceable.

Requirements

• PHP 8.4+
• PDO extension (for database features)
• Composer

Quick Start

Or add Arc to an existing project:

Visit http://localhost:8080

Environment Setup

Copy .env.example to .env and adjust values:

Arc includes a built-in .env loader. Load it early in your bootstrap:

Environment variables are available via $_ENV and getenv(). Existing env vars are never overwritten.

Routing

Define routes in routes/web.php:

Route groups with prefix and middleware:

Controllers

Controllers extend Arc\Support\Controller and receive the current request via setRequest():

Controllers are resolved through the DI container, enabling constructor injection.

Views and Templates

Views live in resources/views/ and use .phtml files:

Layouts use yield() for content:

XSS Escaping

Use e() to escape user-supplied data:

Content and named sections yielded via yield() are raw by design (they contain trusted template HTML). Always escape user data with e().

CSRF Protection

Include a CSRF token in forms:

The CsrfMiddleware validates the token automatically on POST, PUT, PATCH, and DELETE requests.

Partials

Middleware

Immutable middleware examples

• Decorate responses immutably with withHeader() so no other layer sees mutations.
• Pass request-scoped data down the pipeline with Request::withAttribute().

Example: add security headers without mutating the original Response

Example: attach request-scoped data immutably

Register global middleware in your bootstrap:

Security Headers

SecurityMiddleware sets headers with configurable defaults:

CSRF

CsrfMiddleware uses the double-submit cookie pattern with a SameSite=Strict, HttpOnly cookie (marked Secure automatically on HTTPS requests). The token is attached to the request as the _csrf_token attribute and is automatically passed to views rendered via Controller::view(), so csrfField() works without manual wiring.

Rate Limiting

RateLimitMiddleware tracks requests per client IP with configurable limits:

Behind a reverse proxy, pass the proxy IPs as trustedProxies so the client is read from X-Forwarded-For (it is ignored from untrusted peers, preventing spoofing). For stricter per-route limits, supply a keyResolver:

The default in-memory store is per-process; for multi-process or distributed deployments, implement RateLimitStoreInterface with Redis or a database backend.

HTTP Request & Response

• Request: use withAttribute(key, value) to return a cloned instance with a new attribute. setAttribute() still exists and mutates in place; prefer withAttribute() in middleware pipelines to avoid shared-reference surprises.
• Response: in addition to mutating setters (setStatusCode, setHeader, setContent, addCookie, json, redirect), Response provides immutable variants that return a new instance: withStatusCode(int), withHeader(name, value), withContent(string), withAddedCookie(Cookie).
• When writing middleware that decorates the response (e.g., adding security headers), prefer the immutable methods so upstream/downstream middleware don’t observe unexpected mutations.
• Open redirect protection: Response::redirect() rejects external URLs by default; pass allowExternal: true only for known-safe flows.

Compatibility note (PHP 8.5): There is a core bug where return clone($this)->method() may mutate $this instead of the clone. Arc’s with* implementations use a two-statement pattern ($new = clone $this; $new->method(); return $new;) to avoid this. If you implement your own immutable-style methods, avoid one-line clone-chains on PHP 8.5.

Query Builder

Arc\Database\QueryBuilder provides a fluent interface for building SQL queries. All identifiers are validated against SQL injection.

Database and Models

Configure the database connection in config/database.php, then extend the Model:

Available methods:

Fluent queries via query():

Column names in where(), create(), and update() are validated against a strict regex (/^[a-zA-Z_][a-zA-Z0-9_]*$/) to prevent SQL injection. Invalid identifiers throw InvalidArgumentException.

Validation

Available rules: required, string, integer, numeric, email, url, boolean, min, max, between, same, different, in, not_in, alpha, alpha_num, regex, date.

The regex rule uses ~ as delimiter (supports patterns containing /):

Custom error messages:

Session

File Uploads

Configuration

Config files live in config/ and return arrays:

Access via the application:

DI Container

The container supports explicit bindings, singletons, and auto-wiring:

Constructor parameters with class types are resolved from the container. Scalar parameters require defaults or explicit bindings.

Error Handling

In production (APP_DEBUG=false), errors are logged and a generic error page is shown. In debug mode, full stack traces are displayed.

Database errors are wrapped in DatabaseException to prevent sensitive SQL and table names from leaking.

CORS

CorsMiddleware handles cross-origin requests and preflight:

HTTP Method Override

Browser forms only support GET and POST. Arc supports method spoofing via a hidden _method field or the X-HTTP-Method-Override header:

Or via API header:

Only POST requests can be overridden to PUT, PATCH, or DELETE. Use getOriginalMethod() to see the actual HTTP method.

Console Commands

License

MIT, see LICENSE.

Contributing

PRs welcome. Please open an issue first for major changes. See CONTRIBUTING.md for details.

Security

See SECURITY.md for how to report vulnerabilities.