README

vring/framework 是一套轻量 PHP 应用框架，负责应用启动、依赖容器、HTTP 请求与响应、路由、中间件、事件调度、数据库连接和基础 ORM。

框架只提供通用能力，不得依赖具体项目的数据表、业务函数、常量或目录结构。项目控制器、业务规则、具体事件和监听器应保留在项目自己的 app 目录。

环境要求

PHP 7.2 - 8.4
PDO 扩展
JSON 扩展
vring/phputil

安装

发布为 Composer 包后安装：

composer require vring/framework:dev-main

本地联调可以使用 Composer path repository：

{
    "repositories": [
        {
            "type": "path",
            "url": "../vring-library/framework",
            "options": {
                "symlink": false
            }
        }
    ]
}

目录结构

src/
├─ Application.php
├─ container/     依赖容器
├─ database/      数据库连接管理
├─ event/         事件接口与调度器
├─ exception/     HTTP 异常处理
├─ http/          请求、响应和中间件
├─ orm/           Model 与 Query
└─ routing/       路由定义与分发

目录和命名空间分段统一使用小写，类名与类文件名使用大驼峰。

启动应用

<?php

use vring\framework\Application;
use vring\framework\http\Request;

require __DIR__ . '/../vendor/autoload.php';

$app = new Application(dirname(__DIR__));
$app->withRoutes([
    dirname(__DIR__) . '/routes/api.php',
]);

$app->run(Request::capture())->send();

注册路由

路由文件会获得 $router 变量：

<?php

use app\controller\Status;
use vring\framework\routing\Router;

/** @var Router $router */
$router->get('/status', [Status::class, 'index']);
$router->post('/devices/{id}', [Status::class, 'update']);

控制器方法第一个参数为 Request，返回 Response：

<?php

namespace app\controller;

use vring\framework\http\Request;
use vring\framework\http\Response;

final class Status
{
    /**
     * 返回运行状态。
     *
     * @param Request $request HTTP 请求
     * @return Response
     */
    public function index(Request $request): Response
    {
        return Response::json(['status' => 'ok']);
    }
}

中间件

<?php

use vring\framework\http\MiddlewareInterface;
use vring\framework\http\Request;
use vring\framework\http\Response;

final class Authenticate implements MiddlewareInterface
{
    /**
     * 验证请求后继续执行后续处理器。
     *
     * @param Request $request HTTP 请求
     * @param callable $next 后续处理器
     * @return Response
     */
    public function process(Request $request, callable $next): Response
    {
        return $next($request);
    }
}

数据库与 ORM

应用启动时配置连接：

<?php

use vring\framework\database\ConnectionManager;

ConnectionManager::configure([
    'type' => 'MySQL',
    'host' => '127.0.0.1',
    'port' => '3306',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8mb4',
    'dbname' => 'example',
]);

定义模型并查询：

<?php

use vring\framework\orm\Model;

final class Device extends Model
{
    protected static $table = 'devices';
    protected static $fillable = ['sn', 'model'];
}

$device = Device::query()->where('id', 1)->first();

ORM 的更新和删除必须包含 WHERE 条件，避免无条件写操作。

事件

事件和监听器分别实现框架接口，应用负责维护有序注册表：

<?php

use vring\framework\event\EventDispatcher;

$dispatcher = new EventDispatcher([
    RepositoryUpdated::class => [
        RegenerateVersionsListener::class,
    ],
]);

$success = $dispatcher->trigger(new RepositoryUpdated());

监听器可以返回另一个事件，调度器会继续派发；当前事件链遇到首个异常后停止，并通过 PHP error_log() 记录错误。

设计约束

框架不得读取项目专用常量、表结构或业务函数。
项目依赖通过构造函数、配置数组或标准 PHP 环境注入。
不使用输出缓冲统一拦截业务输出。
HTTP 状态和响应头只在明确的响应对象中设置。
新增或修改函数必须补充用途明确的 PHPDoc。

vring / framework

Maintainers

Package info

Statistics

Security