# abbs

**Repository Path**: wfdaj/abbs

## Basic Information

- **Project Name**: abbs
- **Description**: 请注意：仓库路径即仓库访问 URL 地址，更改仓库路径将导致原克隆地址不可用
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZEngine

<img src="https://i.imgur.com/PDCJq49.png" alt="ZEngine Demo">

一个轻量级的 PHP 框架。没有冗余代码，只包含你真正需要的核心功能。

需要详细的文档？查看 <a href="https://deepwiki.com/spexdw/z-engine">ZEngine DeepWiki</a>（由 AI 生成，可能存在文档错误）

## 为什么选择 ZEngine？

我厌倦了拥有数千个文件的复杂框架。ZEngine 非常简单 —— 你可以在一个下午内阅读完整个源代码，并确切地理解正在发生的事情。

## 包含的功能

- **路由** - 将 URL 映射到函数，支持参数、路由分组
- **中间件** - 保护路由、处理认证等任何你需要的功能
- **数据库** - 不碍事的查询构建器
- **服务** - Session、Cookie、缓存、验证、日志等
- **依赖注入** - 自动注入，无需 XML 配置
- **错误页面** - 自定义错误处理，带有漂亮的调试屏幕

## 环境要求

- PHP 8.1+
- Composer
- 仅此而已

## 安装

创建新项目：

```bash
composer create-project spexdw/z-engine my-project
cd my-project
```

或直接克隆：

```bash
git clone https://github.com/spexdw/z-engine.git my-project
cd my-project
composer install
```

## 快速开始

1. 编辑 `config/env.php` 并设置你的配置
2. 编辑 `app/routes.php` 添加你的路由

```php
$router->get('/hello/{name}', function ($name) {
    return json(['message' => "你好, $name!"]);
});
```

就这样。没有生成器，没有样板代码，直接写代码就行。

## 路由

```php
// 基础路由
$router->get('/users', function () {
    return json(['users' => []]);
});

$router->post('/users', function (Request $request) {
    $data = $request->json();
    return json(['created' => $data], 201);
});

// 其他 HTTP 方法
$router->put('/users/{id}', function ($id, Request $request) {
    return json(['updated' => $id]);
});

$router->patch('/users/{id}', function ($id) {
    return json(['patched' => $id]);
});

$router->delete('/users/{id}', function ($id) {
    return json(['deleted' => $id]);
});

$router->any('/endpoint', function () {
    return json(['method' => 'any']);
});

// URL 参数
$router->get('/users/{id}', function ($id) {
    return json(['user_id' => $id]);
});

// 使用中间件保护路由
$router->get('/admin', function () {
    return json(['secret' => 'data']);
})->middleware(AdminMiddleware::class);

// 路由分组
$router->group(['prefix' => '/api'], function ($router) {
    $router->get('/users', fn() => json([]));
    $router->get('/posts', fn() => json([]));
});

// 控制器用法
$router->get('/users', 'UserController@index');
$router->post('/users', [UserController::class, 'store']);
```

## 控制器

在 `app/controller` 中创建控制器：

```php
namespace app\controller;

use core\Request;

class UserController
{
    public function index()
    {
        $users = db()->table('users')->get();
        return view('users.index', ['users' => $users]);
    }

    public function store(Request $request)
    {
        $data = $request->all();
        $id = db()->insert('users', $data);
        return json(['id' => $id], 201);
    }
}
```

## 视图

在 `app/view` 中创建视图：

```php
// 返回视图
return view('welcome'); // app/view/welcome.php
return view('users.index', ['users' => $users]); // app/view/users/index.php

// 使用视图助手
$router->get('/', function () {
    return view('welcome', ['name' => '张三']);
});
```

## 请求与响应

```php
// 请求助手
$name = $request->input('name'); // 从 POST 或 GET 获取
$email = $request->get('email'); // 从查询字符串获取
$data = $request->post('data'); // 从 POST 获取
$all = $request->all(); // 获取所有输入数据
$json = $request->json(); // JSON 负载
$token = $request->header('Authorization'); // 请求头
$bearer = $request->bearerToken(); // Bearer token
$file = $request->file('upload'); // 上传的文件
$ip = $request->ip(); // 客户端 IP

// 响应助手
return json(['data' => []], 200); // JSON 响应
return view('page', ['key' => 'value']); // 视图响应
return redirect('/home'); // 重定向
return Response::make('content', 200); // 纯文本
```

## 数据库

```php
// 查询构建器
$users = db()->table('users')
    ->where('status', 'active')
    ->orderBy('created_at', 'DESC')
    ->get();

// 获取第一条记录
$user = db()->table('users')->where('id', 1)->first();

// 统计记录数
$count = db()->table('users')->where('status', 'active')->count();

// limit & offset 分页
$users = db()->table('users')->limit(10)->offset(20)->get();

// 按 ID 查找
$user = db()->find('users', 1);

// 原生查询
$results = db()->query('SELECT * FROM users WHERE id = ?', [1]);

// 插入/更新/删除
db()->insert('users', ['name' => '张三', 'email' => 'zhangsan@example.com']);
db()->update('users', ['status' => 'active'], ['id' => 1]);
db()->delete('users', ['id' => 1]);

// 事务
db()->beginTransaction();
try {
    db()->insert('users', ['name' => '张三']);
    db()->commit();
} catch (Exception $e) {
    db()->rollback();
}
```

## 服务

```php
// Session
session()->set('user_id', 123);
$userId = session()->get('user_id');
$token = session()->token(); // CSRF token

// 缓存
cache()->put('key', 'value', 300); // 5分钟
$value = cache()->get('key');

// 带回调的缓存（key 不存在时才执行）
$users = cache()->remember('users', 3600, function () {
    return db()->table('users')->get();
});

// Cookie
cookie()->set('theme', 'dark', time() + 3600);
$theme = cookie()->get('theme');

// 验证
$rules = ['email' => 'required|email', 'age' => 'min:18'];
$isValid = validator()->validate($data, $rules);

// 日志
logger()->error('出问题了', ['context' => '详情']);
logger()->warning('警告消息');
logger()->info('信息消息');
logger()->debug('调试数据', ['user_id' => 123]);

// 事件
event()->listen('user.registered', function ($userId) {
    logger()->info('用户注册成功，ID：' . $userId);
});

event()->dispatch('user.registered', 123);

// 哈希（密码哈希）
$hash = hasher()->make('password123');
$isValid = hasher()->check('password123', $hash);

// 邮件
mail()->send('user@example.com', '欢迎！', '你好，欢迎使用我们的应用！');

// 限流
$rateLimit = ratelimit()->check('api.endpoint', [
    '1minute' => 10,   
    '1hour' => 100   
]); // 你可以传入自定义标识符

if ($rateLimit) {
    return Response::json(['error' => $rateLimit], 429);
}
```

## 中间件

在 `app/middleware` 中创建中间件：

```php
class AuthMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        if (!$request->header('Authorization')) {
            return Response::json(['error' => '未授权'], 401);
        }
        return $next($request);
    }
}
```

使用它：

```php
$router->get('/dashboard', function () {
    return json(['data' => 'secret']);
})->middleware(AuthMiddleware::class);
```

## 自定义服务

将你的服务添加到 `core/Providers.php`：

```php
private static function registerMyService(Container $container): void
{
    $container->singleton('myservice', function () {
        return new MyService();
    });
}
```

然后在 `register()` 方法中调用 `self::registerMyService($container);`。

在任何地方使用它：

```php
$result = app('myservice')->doSomething();
```

## 定时任务（Tasks）

将你的定时任务添加到 `app\task\MyCron`，然后将任务添加到 `/cron.php`

```php
try {
    $doSomething = new DoSomething();
    $doSomething->handle();

} catch (\Exception $e) {
    echo "错误：" . $e->getMessage() . "\n";
}
```

注意：cron.php 只能通过 CLI 访问，并需要 CRON_KEY

## 错误处理

在 `.env` 中设置 `APP_DEBUG=true` 可以获得带有代码片段的详细错误页面。

生产环境设置 `APP_DEBUG=false` 以显示简洁的错误页面。

设置 `MAINTENANCE_MODE=1` 进入维护模式（包含 IP 白名单和维护消息）

所有错误都记录到 `storage/logs/error.log`。

## 贡献

发现 bug？想要新功能？请创建 Issue 或 PR。保持简单。

## 许可证

MIT。你可以随心所欲地使用它。

## 致谢

由 [spexdw](https://github.com/spexdw) 构建，因为现有框架太复杂了 :p