README

版本 1.4 -- 2023-07-25

实现模型-视图-控制器（MVC）架构模式的简单 Web 应用程序框架。

关键特性

基于简单 html/php 的视图，具有渲染层次结构
基于 PDO 的数据库连接，具有基于数组的查询构建器（目前仅实现 MySQL）
易于使用的模型类
简单的 URL 路径到控制器/方法的转换，具有自动参数传递
数据库迁移支持
通过 SAML 进行用户登录（使用此功能需要 composer require "simplesamlphp/simplesamlphp:^1.19.2"）

模块

UMVC 支持模块，请参阅配置/组件。

Codeception 支持

该框架支持使用其框架插件进行功能测试。全局安装的 codeception 必须与所需版本兼容（目前为 v3.1.2）

命令行

UMVC 支持 CLI。您可以创建自己的命令。内置命令包括

migrate

以 php app $command $action $parameters 运行命令

安装

可以使用 composer 将该框架包含到您的项目中。运行 composer require uhi67/umvc:dev-master。可以使用 composer create-project --prefer-dist uhi67/umvc-app name 创建新的空项目。这将为您提供一个使用 UMVC 框架的新空应用程序，并将其放入指定的目录中。选择您喜欢的任何名称。

使用 UMVC 构建您的应用程序的第一步

警告：此部分正在建设中。在类的文档块中了解更多关于所提及类的信息。

创建您的应用程序的 composer.json 文件，并包含 uh67/umvc，例如 composer init --name myname/myapp --require uhi67/umvc:*。
运行 composer update。
将 vendor/uh67/umvc/app 复制到您的应用程序根目录。这是 CLI 命令的启动器。
将 vendor/uh67/umvc/www/index.php 和 .htaccess 复制到您的应用程序 www 目录。这是 Web 接口的路由器。
在 config/config.php 文件中创建您的应用程序配置，请参阅 vendor/uh67/umvc/config/config-template.php 中的模板。
创建一个可由 Web 服务器写入的 runtime 目录，用于放置临时文件。
创建一个可由 Web 服务器写入的 www/assets 目录，用于放置各种组件的缓存的资产文件。

使用 MVC 模式构建您的应用程序

在 controllers 目录中创建您的控制器，使用 \app\controllers 命名空间，并从 uhi67\umvc\Controller 继承。
在 views 目录中创建您的视图，使用简单的 PHTML 格式，并按 views/controller/action.php 结构组织。
在 models 目录中创建您的模型。数据库模型是 \uhi67\umvc\Model，无数据库模型是 \uhi67\umvc\BaseModel。

其他基本原理

迁移用于版本控制和记录源代码中的数据库更改。将迁移步骤放置在 migrations 目录中。
布局是一个特殊的视图，用于嵌入所有其他视图。将布局放置在 views/layouts 目录中。视图可以调用其他部分视图。
您可以在 commands 目录中定义 CLI 命令，从 \uhi67\umvc\Command 类继承。框架中包含一些内置命令。php app 命令列出所有可用的命令，包括内置和自定义命令。
内置简单的基于文件的本地化支持。将您的翻译放入 messages/la.php 文件中，其中 "la" 是您要翻译到的语言。

组件配置和属性

所有组件，包括主App类本身，以及大多数UMVC类，都是\uhi67\umvc\Component。 Component实现了property特性：魔法获取器和设置器使用getProperty和setProperty方法。Component是configurable的：构造函数接受一个包含公共属性值的配置数组。

内置组件

MySqlConnection -- 连接到数据库。包括SQL查询构建器。目前是Connection的唯一实现。
FileCache -- CacheInterface的唯一实现。
SamlAuth -- AuthManager的唯一实现。
L10n -- 简单本地化，默认自动包含，仅翻译UMVC消息。
L10nFile -- 基于文件的本地化，用于翻译应用程序的消息。

您可以使用的其他基本类

Form -- 一个小部件，具有内置视图，用于显示和处理使用您的模型编写的HTML表单。
Grid（小部件，但内置视图仍然缺失）-- 用于显示分页、过滤后的模型列表。
Query -- 代表PHP结构中的参数化和灵活的SQL查询。可以从它构建SQL命令。
Request -- 代表HTTP请求，可以用来获取GET和POST参数。
Session -- 代表当前PHP会话，可以用来获取和设置变量。

入口脚本、URL和路由

Web应用程序的单个入口脚本为www/index.php。相应地，CLI应用程序的单个入口脚本为app文件。它们都必须从vendor/uhi67/umvc/目录复制到您的应用程序目录。

www/.htaccess规则将所有未找到的请求重定向到www/index.php。然而，静态资源直接从www目录提供服务。稍后了解更多关于服务库资源的信息。

index.php初始化自动加载器，加载主要配置，创建主对象（配置中定义的类，通常是uhi67/umvc/App或其子类）。主配置遵循可配置的Component规则。

路由

所有URL都形成为https://myapp/acontroller/anaction，以以下方式处理

uhi67/umvc/App解析请求，计算要使用的实际控制器类（从uhi67/umvc/Controller派生），创建控制器并运行请求的动作方法。如上例所示，acontroller指的是您的controllers目录中的控制器类AcontrollerController，而anaction指的是动作方法（actionAnaction）。

如果URL中缺少动作名称，将运行actionDefault。如果也缺少控制器名称，则使用配置的mainController。还可以创建一个不指定控制器名称而具有默认控制器动作名称的URL - 唯一的限制是不能有与该动作同名的控制器。

CLI命令形式为php app acontroller/anaction，以以下方式处理

uhi67/umvc/App解析请求，计算要使用的实际控制器类（从uhi67/umvc/Command派生），创建控制器并运行请求的动作方法。如上例所示，acontroller指的是您的commands目录中的控制器类AcontrollerController，而anaction指的是动作方法（actionAnaction）。可以以相同的方式运行内置命令。具有相同名称的应用程序命令会覆盖内置命令。

在控制器动作中使用URL

当前URL请求的部分可以按以下方式访问

路径：传递给控制器的路径部分（控制器名称已移除）
查询：原始请求的查询部分，作为一个关联数组

要使用控制器和操作名称以及可选的查询参数创建新的URL，请使用以下之一：

$this->app->createUrl(['controller/action', 'key'=>'queryvalue', ..., '#'=>'fragment']) -- 所有部分都是可选的
return $this->app->redirect([...]) -- 用于通过重定向终止操作

服务库资产

在您的视图文件中，您可以通过以下方式以静态方式引用位于 www 目录下的静态资产，例如 <link href="/assets/css/app.css" rel="stylesheet">。相反，如果您想引用位于由 composer 创建的供应商库中的某个位置的资产文件，您可以使用这种方式

<script src="<?= $this->linkAssetFile('npm-asset/bootstrap/dist', 'js/bootstrap.bundle.min.js') ?>"></script>

linkAssetFile 函数将第一个参数目录中的所有文件复制到 www 下的资产缓存目录，并为第二个参数中的文件创建一个有效的URL。注意：第一个参数标识了一个资产包。对于任何包的第一个调用都会复制文件。对同一包的所有后续调用只生成文件的链接。

通过 composer install 命令清空资产缓存。资产缓存始终位于 www/asset/cache，不可配置。

其他主题（即将推出）

日志记录
使用表单更新模型的基本结构
网格分页和过滤
模型验证
助手（仅包含静态方法的类）

...

框架开发信息

独立安装和内部单元测试

此仓库包含一个内置的测试应用程序，用于内部 Codeception 单元测试。在 tests 目录中的测试应用程序的唯一目的是能够运行单元测试，而不是作为示例应用程序。

独立安装步骤

git clone
composer update
根据模板创建 tests/_data/test-config.php
根据 tests/_data/test-config.php 中的数据库设置创建 umvc-test 数据库
运行 php vendor/bin/codecept run unit 进行单元测试

更多单元测试即将推出...

Docker 中的测试

内置的 Docker 化测试环境可用于使用不同的 PHP 和数据库版本进行测试。

步骤

在 tests/docker-compose.yml 中配置所需的数据库版本（克隆此模板文件）
在 tests/docker/Dockerfile 中配置 PHP 版本（扩展安装步骤可能更改）
在 tests/.env 中配置使用的端口和 base-url
使用 docker compose up --build -d 构建 stack（在 tests 目录中）
您的 PHP 容器现在应该是 'umvc-php-1'
使用 docker exec -it umvc-php-1 php vendor/bin/codecept run unit 运行单元测试

变更日志

版本 1.4 -- 2024-07-25

添加了 Query::filterInReferredModels()
清空缓存：跳过 .gitignore 文件
UMVC 指南和引用 umvc 应用
php 8 兼容性修复
其他错误修复

版本 1.3.1 -- 2023-03-27

SQL Builder：使用 tablename 作为默认别名
添加了 migrate/wait 命令
延迟连接 Connection
本地化渲染

版本 1.3 -- 2022-12-03

迁移 SQL 事务问题
MySQL 8.0 兼容性，保持 5.7 兼容性
App：修复了视图路径
CLI 配置检查
AppHelper::waitFor()
单元测试修复
包含测试指南的简单 Docker 化测试应用程序
Docker：等待数据库容器初始化（简单方法）
添加了第一步骤文档

版本 1.2.1 -- 2022-10-02

修复了 twig/twig < 2.15.3 漏洞（composer.lock）
添加 AuthManager::actionLogin() 以修复默认登录返回问题

版本 1.2 -- 2022-09-20

错误修复，phpdoc 修复
linkButton 签名已更改
Connection::connect 返回
Connection 信息方法（getTables() 等）
MysqlConnection dropXXX 方法
迁移/重置命令
单元测试，测试应用（草案）
显示异常：修复之前的消息
模型主键检查
SamlAuth：仅在登录时更新用户记录
版本文件创建已移除

版本 1.1 -- 2022-08-30

资产注册改进（Controller::registerAssets()等）
添加 Html::img() 函数
Session、Request、FileUpload 类
本地化（App::l()、App::$locale、L10n、L10nFile等）
App：默认布局参数
渲染错误修复
SamlAuth::get() 已修复

版本 1.1 的升级说明

必须将 App::asset() 调用替换为 App::linkAssetFile() 调用（使用相同的参数）

uhi67 / umvc

维护者

详细信息