README

Lithe Framework

A lightweight, modular PHP framework for building modern web applications.

About · Requirements · Installation · Features · Development

About

Lithe is an open-source PHP framework focused on clear architecture, modular features, and a straightforward developer experience. It provides the core services needed by a web application while allowing optional capabilities to live in independent packages.

The framework package contains infrastructure only. Application UI, starter-kit features, teams, themes, extensions, and other optional modules belong in separate packages so projects install only what they need.

Warning

Lithe 0.0.1 is in active development. APIs and internal structure may change before the first stable release. It is not yet recommended for production applications.

Requirements

• PHP 8.3 or newer
• Composer 2
• The PHP extensions required by the database and features used by your application

Supported database connectors currently include:

• MySQL
• PostgreSQL
• SQLite

Installation

The recommended way to start a complete Lithe application is through the Lithe Starter Kit. This repository is the reusable framework package consumed by applications and other Lithe packages.

When the package is available through your configured Composer repository, install it with:

composer require lithe/framework:^0.0.1

For local framework development, add a path repository to the consuming application's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../lithe-framework",
            "options": {
                "symlink": true
            }
        }
    ],
    "require": {
        "lithe/framework": "@dev"
    }
}

Then run:

composer update lithe/framework

The path in url must point to the actual framework directory on your machine. Do not include a path repository in distributable starter-kit releases; published releases should resolve the framework from the package repository.

Features

Application foundation

• Application container and dependency injection
• Service providers and automatic package discovery
• Environment and configuration loading
• HTTP and console kernels
• Exception handling and maintenance mode
• Configuration, route, event, command, view, and provider caching

HTTP and routing

• Request, response, redirects, uploads, and file responses
• Router and route definitions
• Middleware pipeline
• CORS, proxy and host trust, security headers, and throttling
• HTTP client and structured HTTP exceptions

Database

• MySQL, PostgreSQL, and SQLite connections
• Query builder and pagination
• Schema builder and database-specific grammars
• Migrations, migration history, and seeders
• ORM foundations and query events

Authentication and security

• Session-based authentication and user providers
• Authorization gates, policies, and middleware
• Password reset broker and login throttling
• Email verification middleware
• CSRF and request security foundations
• Validation and form requests

Application services

• Cache stores and atomic locks
• Sessions, events, hooks, jobs, queues, and scheduling
• Mail and notifications
• Filesystem, image handling, logging, and localization
• Views and template rendering
• APIs, resources, version negotiation, and personal access tokens

Developer experience

• Command-line application and command discovery
• Code generators and publishable stubs
• Database, cache, route, configuration, event, storage, and optimization commands
• Debugging, health checks, observability, performance, and stability tools
• Testing support

AI

• AI manager, agents, tools, and structured responses
• Provider contracts
• OpenAI-compatible, Anthropic, Gemini, and Ollama providers

AI support is infrastructure, not an enabled application feature. Provider credentials and AI functionality must be configured explicitly by the consuming application.

Package boundaries

Lithe follows a package-first architecture:

Optional packages must not be treated as active merely because their classes are installed. Applications should explicitly select and configure the features they use.

Project structure

src/
├── Foundation/       Application lifecycle and bootstrapping
├── Container/        Dependency injection
├── Http/             Requests, responses, middleware, and HTTP client
├── Routing/          Router and route definitions
├── Database/         Connections, queries, schema, and migrations
├── Orm/              Model and persistence layer
├── Auth/             Authentication
├── Authorization/    Gates, policies, and authorization middleware
├── Console/          CLI application and commands
├── Events/           Event dispatcher and discovery
├── Jobs/             Job dispatching
├── Queue/            Queue infrastructure
├── Cache/            Cache stores and locks
├── View/             View rendering
├── Validation/       Validation rules and errors
├── Security/         Security services
├── Api/              API resources and tokens
├── Ai/               AI providers, agents, and tools
└── Support/          Shared helpers and utilities

Development

Install dependencies:

composer install

Refresh the autoloader after adding or moving classes:

composer dump-autoload

Before submitting a change:

1. Keep framework code independent from starter-kit UI and optional packages.
2. Preserve PHP 8.3 compatibility unless the documented minimum version changes.
3. Add or update tests for changed behavior.
4. Run the available test and static-analysis commands configured by the repository.
5. Update CHANGELOG.md when the change affects users.

The current 0.1.0 archive contains the test namespace and test directory, but no committed automated test suite or PHPUnit configuration. These should be added before a stable release.

Versioning

Lithe intends to follow Semantic Versioning. During the 0.0.x development cycle, minor releases may contain breaking changes.

Security

Do not report security vulnerabilities in a public issue. Until a dedicated security policy and private reporting address are published, contact the repository owner privately through their GitHub profile.

Contributing

Issues and pull requests are welcome. Please keep contributions focused, explain the problem being solved, and avoid coupling the framework core to optional application features.

License

Lithe Framework is open-source software licensed under the MIT License.