Skip to content
BranchesTags

Repository files navigation

FinchPHP

English | 简体中文

轻量级 PHP MVC 框架 — 以运行速度、少量文件、易读为核心优势。

版本：1.0.0 ｜ 协议：MIT License ｜ PHP 最低版本：7.4.0（推荐 8.0+）

目录

项目介绍

FinchPHP 是一款轻量级 PHP MVC 框架，定位为「小而美」的开发工具。它不依赖 Composer，不依赖任何第三方库（除可选的 Redis 扩展），仅通过 9 个核心 PHP 文件即可支撑完整的应用开发流程。

框架以 运行速度、少量文件、易读易懂 为三大核心优势，适合个人开发者、小型团队快速搭建中小型项目，也适合作为学习 PHP MVC 架构的入门框架。

核心优势

  1. 极简文件结构 — 仅 9 个核心 PHP 文件，无需 Composer 安装，开箱即用
  2. 零依赖 — 不依赖任何第三方库（除可选的 Redis 扩展）
  3. 快速运行 — 单例模式 + 静态缓存 + 自动加载优化，性能优先
  4. 易读易懂 — 完整中文注释，代码结构清晰，便于二次开发
  5. 多数据库支持 — MySQL / MariaDB / SQLite / PostgreSQL / Oracle / MS SQL Server / Sybase
  6. 多应用模式 — 支持前后台分离（default / manage 等多应用并行），也支持单应用模式
  7. 内置模板引擎 — 编译型模板引擎，支持 {$var}、{if}、{foreach}、{include}、{php} 等标签
  8. 双缓存驱动 — 文件缓存 + Redis 缓存，可自由切换
  9. 链式 ORM — 基于 PDO 的链式查询，支持参数绑定防注入
  10. 安全防护 — XSS 过滤（html_in / html_out）、SQL 注入防护（参数绑定）、自定义加解密

适用场景

  • 小型项目快速搭建
  • 企业官网、博客、CMS 等网站开发
  • RESTful / JSON API 功能开发
  • 前后台分离的多应用项目
  • PHP MVC 架构学习与教学

安装

FinchPHP 无需 Composer，直接将 framework/ 目录放入项目根目录即可。

环境要求

组件 要求
PHP ≥ 7.4.0（推荐 8.0+）
PDO 扩展 必需
PDO_SQLite / PDO_MySQL 至少启用一种数据库驱动
Redis 扩展 可选（使用 Redis 缓存时需要）

目录结构示例

project/
├── framework/              # 框架核心
│   ├── run.php             # 入口引导文件
│   ├── config.php          # C 配置类
│   ├── function.php        # F 工具类
│   ├── core.php            # core 引擎 + controller + model 基类
│   ├── db.php              # db 数据库类
│   ├── template.php        # 模板引擎
│   ├── cache.php           # 缓存工厂
│   └── cache/              # 缓存驱动
│       ├── file_cache.php
│       └── redis_cache.php
├── app/                    # 应用目录
│   └── default/
│       ├── controller/     # 控制器
│       ├── model/          # 模型
│       └── template/       # 模板
│           └── default/
├── config.php              # 应用配置（根目录）
├── index.php               # 入口文件
└── php.ini                 # 可选：项目级 PHP 配置

快速开始

1. 入口文件

创建 index.php：

<?php
// 单应用模式无需设置，直接引入框架入口
require __DIR__ . '/framework/run.php';

若仅用于验证框架能否启动，可在 require 前加 define('FINCH_NO_RUN', true); 跳过路由分发。

2. 配置文件

在根目录创建 config.php：

<?php
// 单应用模式（关闭多应用路由解析）
$config['APP_MODEL'] = false;

// 调试模式
$config['DEBUG'] = true;

// SQLite 数据库配置
$config['DB_GROUP'] = [
    [
        'DB_TYPE'   => 'sqlite',
        'DB_FILE'   => 'guestbook.db',   // SQLite 文件名
        'DB_PATH'   => 'app',            // 数据库文件存放位置：app=APP_PATH, 空=BASE_PATH
        'DB_SPACE'  => 'database',       // 数据库目录名
        'DB_PREFIX' => 't_',             // 表前缀
    ],
];

多应用模式时设置 $config['APP_MODEL'] = true;，URL 中带应用名（如 /manage/login.html）。

3. 控制器

app/default/controller/index_controller.php：

<?php
class index_controller extends controller {
    public function index() {
        $this->view['title'] = 'Hello FinchPHP';
        $this->view('index');
    }
}

4. 模型

app/default/model/user_model.php：

<?php
class user_model extends model {
    public function get_user($id) {
        return $this->db->table('users')->where('id=?', [$id])->get();
    }
}

5. 模板

app/default/template/default/index.html：

{include inc_head.html}
<h1>{$title}</h1>
{foreach $users as $user}
    <p>{$user.name}</p>
{/foreach}
{include inc_foot.html}

文件结构

框架核心目录：

framework/
├── run.php                  # 入口引导文件（常量定义 + 启动）
├── config.php               # C 配置类（点号嵌套读取 + 缓存）
├── function.php             # F 工具类（60+ 静态方法）
├── core.php                 # core 引擎 + controller 基类 + model 基类
├── db.php                   # db 数据库类（链式 ORM + 事务 + 多驱动）
├── template.php             # template 模板引擎（编译型 + 缓存）
├── cache.php                # cache 缓存工厂
└── cache/
    ├── file_cache.php       # 文件缓存驱动
    └── redis_cache.php      # Redis 缓存驱动

路由规则

URL 格式：/控制器/操作.html 或 /应用名/控制器/操作.html

URL 应用 控制器 操作
/index.html default index_controller index()
/products/list.html default products_controller list()
/manage/login.html manage login_controller index()

单应用模式（APP_MODEL=false）下，URL 不含应用名段；多应用模式下首段为应用名。 访问 /index.html 时，框架会路由到 default 应用的 index_controller 控制器并执行 index() 方法。

伪静态配置

FinchPHP 通过 URL 路径（如 /index.html、/index/post.html）进行路由分发。在生产环境推荐配置伪静态，隐藏入口文件 index.php，使 URL 更简洁、对 SEO 更友好。

项目根目录已提供 .htaccess 配置文件（Nginx rewrite 规则），内容如下：

location / {
  if (!-e $request_filename){
    rewrite  ^(.*)$  /index.php?s=$1 last; break;
  }
}

Nginx 配置

将上述 location 规则添加到 Nginx 站点配置的 server 块中，重启 Nginx 即可。配置后，所有不存在的文件请求都会被重写到 index.php，由框架解析路由。

完整示例：

server {
    listen       80;
    server_name  yourdomain.com;
    root         /path/to/finch;
    index        index.php;

    location / {
        if (!-e $request_filename){
            rewrite  ^(.*)$  /index.php?s=$1 last; break;
        }
    }

    location ~ \.php$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_index  index.php;
        fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
        include        fastcgi_params;
    }
}

Apache 配置

Apache 用户在根目录 .htaccess 中使用以下规则（需开启 mod_rewrite）：

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ index.php?s=$1 [QSA,PT,L]
</IfModule>

提示：使用 PHP 内置服务器（php -S）开发时无需伪静态配置，直接访问 index.php 入口即可。

数据库

FinchPHP 基于 PDO 提供链式 ORM，支持参数绑定以防 SQL 注入。

链式查询示例

// 查询单条
$row = $this->db->table('users')->where('id=?', [1])->get();

// 查询列表
$list = $this->db->table('users')
    ->where('status=?', [1])
    ->order('id DESC')
    ->limit(10)
    ->getlist();

// 插入
$id = $this->db->table('users')->insert(['name' => 'test', 'age' => 20]);

// 更新
$this->db->table('users')->where('id=?', [1])->update(['name' => 'new']);

// 删除
$this->db->table('users')->where('id=?', [1])->delete();

// 聚合查询
$count = $this->db->table('users')->where('status=?', [1])->count();

SQLite 配置说明

$config['DB_GROUP'] = [
    [
        'DB_TYPE'   => 'sqlite',
        'DB_FILE'   => 'app.db',   // 数据库文件名
        'DB_PATH'   => 'app',      // 'app'=APP_PATH，空=BASE_PATH（项目根）
        'DB_SPACE'  => 'database', // 数据库目录名
        'DB_PREFIX' => 't_',       // 表前缀
    ],
];

事务

$this->db->action(function($db) {
    $db->table('orders')->insert([...]);
    $db->table('stock')->where('id=?', [1])->update(['qty' => 5]);
});

支持的数据库驱动

  • MySQL / MariaDB
  • SQLite
  • PostgreSQL
  • Oracle
  • MS SQL Server
  • Sybase

模板引擎

FinchPHP 内置编译型模板引擎，模板编译后缓存，二次访问直接读取缓存，性能优异。

模板标签

标签 说明
{$var} 输出变量
{$arr.key} 输出数组元素
{CONSTANT} 输出常量
{if $cond}...{else}...{/if} 条件判断
{for $i=0;$i<10;$i++}...{/for} for 循环
{foreach $arr as $k=>$v}...{/foreach} foreach 循环
{include file.html} 包含子模板
{php echo 'code';} 执行 PHP（注意安全）
{TPL_PATH} 模板风格路径
{:url('param')} 生成 URL（调用 $this->url()）

模板示例

{include inc_head.html}
<h1>{$title}</h1>
{if $users}
    {foreach $users as $user}
        <p>{$user.name} - {$user.age}</p>
    {/foreach}
{else}
    <p>暂无数据</p>
{/if}
{include inc_foot.html}

缓存

FinchPHP 提供文件缓存与 Redis 缓存两种驱动，可通过配置自由切换。

使用示例

$cache = new cache(['CACHE_TYPE' => 'file']);
$cache->set('key', $data, 3600);   // 写入缓存，有效期 3600 秒
$result = $cache->get('key');      // 读取缓存
$cache->del('key');                // 删除缓存

切换为 Redis 缓存

$cache = new cache([
    'CACHE_TYPE' => 'redis',
    'REDIS_HOST' => '127.0.0.1',
    'REDIS_PORT' => 6379,
]);

F 工具类 API

F 类提供 60+ 静态方法，涵盖输入输出、安全、HTTP、文件、工具等常用操作。

输入

方法 说明
F::input('get.id') 获取输入（支持 get. / post. 前缀）
F::input_int('post.page') 获取整型输入

输出

方法 说明
F::json($data) 输出 JSON
F::redirect($msg, $url) 跳转提示

安全

方法 说明
F::html_in($str) 入库前 XSS 过滤
F::html_out($str) 出库后反转义
F::authcode($str, $key) 自定义加解密

HTTP

方法 说明
F::httpClient($data, $url) POST 请求
F::get($url) GET 请求

文件

方法 说明
F::dir_create($dir) 递归创建目录
F::dir_delete($dir) 递归删除目录

工具

方法 说明
F::formatTree($data) 数组转无限级树形结构
F::arrayPage($list, $page, $size) 数组分页
F::cut($str, $len) 字符串截取

示例：留言本

本项目内置一个简易留言本作为框架功能验证示例，演示了 FinchPHP 的核心能力：单应用模式、SQLite 数据库、链式 ORM、模板引擎、Session 管理、CSRF 防护等。

功能清单

  • 留言列表分页展示
  • 访客提交留言（昵称 + 内容）
  • 管理员登录 / 登出
  • 管理员删除留言

目录结构

app/default/
├── controller/
│   └── index_controller.php        # 留言本控制器（列表/提交/登录/登出/删除）
├── model/
│   └── message_model.php           # 留言模型
├── template/default/
│   ├── index.html                  # 留言列表页 + 提交表单
│   ├── login.html                  # 管理员登录页
│   ├── inc_head.html               # 公共头部
│   ├── inc_foot.html               # 公共尾部
│   ├── _redirect_ok.html           # 跳转提示页（成功）
│   ├── _redirect_fail.html         # 跳转提示页（失败）
│   └── _redirect_flood.html        # 跳转提示页（频繁）
└── database/
    └── guestbook.db                # SQLite 数据库文件（首次运行自动创建）

启动方式

  1. 启动 PHP 内置服务器： 
    php -c php.ini -S localhost:8765 -t d:\webRoot\finch
  2. 浏览器访问 http://localhost:8765/index.php
  3. 访客可直接留言；管理员登录后可删除留言

管理员账号

在根目录 config.php 的 ADMIN 配置项中设置：

$config['ADMIN'] = [
    'username' => 'admin',
    'password' => 'admin123',   // 明文，生产环境请改为 hash
];

协议

FinchPHP 基于 MIT License 开源协议发布。

Copyright © 2026 FinchPHP. All rights reserved.

About

轻量级 PHP MVC 框架 — 轻量 · 易读 · 快速开发

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages