nadirlc / pak-php-framework
PHP微框架
Requires
- php: ^7.2
This package is auto-updated.
Last update: 2024-09-11 14:48:29 UTC
README
简介
Pak Php 框架是一个用于开发 PHP 应用的框架。它可以用于开发基于 模型视图控制器 (MVC) 设计模式 的命令行应用和浏览器应用。
应用框架提供库和工具来开发应用。Pak Php 框架提供错误处理、函数验证、日志处理、会话处理、基于 MVC 设计模式的 URL 请求处理、URL 路由、翻译和测试。它还包括提供常用功能（如模板引擎、数据库抽象、错误处理、文件和文件夹管理）的实用类。
Pak Php 框架提供的实用类和功能作为独立的组件实现，易于扩展。Pak Php 框架的所有组件都基于 关注点分离 和 不要重复自己 的原则。
可以与 Pak Php 框架集成第三方前端库，如 Twitter Bootstrap、JQuery、W3.CSS 等。
要求
Pak Php 框架需要 PHP 7.2 及以上版本。Pak Php 框架的代码全部有注释，并遵循 PSR-2 编码规范。所有方法都提供了参数和返回类型。
Pak Php 框架除了 XDebug PHP 扩展外，没有其他外部依赖。它拥有自己的模板引擎和测试管理器。它提供了一个简单的框架来开发经过良好测试的应用。
网站开发
该网站是根据 精益创业原则 开发的。在框架开发过程中，《理解软件》这本书是一份无价的指南。
Pak Php 框架的目的是提供一组轻量级工具，用于开发专业、经过良好测试的 Web 应用。使用 Pak Php 框架开发的应用应基于精益创业原则。
应用结构
单个 Pak Php 框架实例可以支持多个应用。每个应用必须位于其自己的文件夹中。以下是一个示例 Pak Php 框架应用的结构
├── config
│ ├── Custom.php
│ ├── General.php
│ ├── Path.php
│ ├── RequiredObjects.php
│ ├── Test.php
│ └── Callables.txt
├── Config.php
├── lib
├── test
│ └── results
│ ├── codecoverage
│ └── tracelogs
└── ui
├── css
├── html
├── images
├── js
├── pages
config 文件夹包含应用配置文件。每个文件应包含一个名为 GetConfig 的方法。此方法应返回一个包含配置数据的数组，该数组覆盖默认框架配置。请参阅 framework/config 文件夹中的默认配置文件。
可以包含自定义配置的 Custom.php 文件。Callables.txt 文件定义了应用的 URL 路由信息。
《lib》文件夹应包含用户定义的库文件。《ui》文件夹包含与用户界面相关的代码。它应包含上例中显示的子文件夹。CSS子文件夹包含应用程序CSS文件，images文件夹包含应用程序图像文件，js文件夹包含应用程序JavaScript文件。《html》文件夹包含HTML模板文件。《pages》文件夹应包含从《\Framework\Application\Page》基类派生的文件。
框架结构
Pak Php 框架具有以下结构
├── autoload.php
├── index.php
├── .htaccess
├── framework
│ ├── application
│ │ ├── Api.php
│ │ ├── Application.php
│ │ ├── CommandLine.php
│ │ ├── libraries
│ │ │ ├── ErrorHandling.php
│ │ │ ├── FunctionValidation.php
│ │ │ ├── LogHandling.php
│ │ │ ├── SessionHandling.php
│ │ │ ├── Translation.php
│ │ │ └── UrlRouting.php
│ │ ├── Page.php
│ │ └── Web.php
│ ├── config
│ │ ├── base
│ │ │ ├── GeneralConfig.php
│ │ │ ├── PathConfig.php
│ │ │ ├── RequiredObjectsConfig.php
│ │ │ └── TestConfig.php
│ │ ├── Config.php
│ │ ├── Initializer.php
│ │ └── Manager.php
│ ├── documentation
│ │ └── changelog.txt
│ ├── templateengine
│ │ ├── BasePage.php
│ │ ├── Generator.php
│ │ └── HeaderTags.php
│ ├── testmanager
│ │ ├── BlackBoxTesting.php
│ │ ├── CodeCoverageGenerator.php
│ │ ├── TestDataManager.php
│ │ ├── TestFunctionProcessor.php
│ │ ├── TestFunctionValidator.php
│ │ ├── TestResultsManager.php
│ │ ├── UiTesting.php
│ │ ├── UnitTestRunner.php
│ │ └── WhiteBoxTesting.php
│ ├── utilities
│ │ ├── Authentication.php
│ │ ├── autoload.php
│ │ ├── CacheManager.php
│ │ ├── commentmanager
│ │ ├── databasemanager
│ │ ├── documentation
│ │ │ └── changelog.txt
│ │ ├── Email.php
│ │ ├── Encryption.php
│ │ ├── errormanager
│ │ ├── examples
│ │ ├── Excel.php
│ │ ├── filesystem
│ │ ├── LogManager.php
│ │ ├── Profiler.php
│ │ ├── StringUtils.php
│ │ ├── TemplateUtils.php
│ │ └── UtilitiesFramework.php
│ └── vendors
主入口点
index.php 文件是应用程序的主入口点。所有URL请求都通过 .htaccess 文件路由到 index.php 文件。使用 autoload.php 文件来自动加载类。所有类都应该有命名空间。类的文件夹结构应与类命名空间相匹配。
应用程序基类
所有Pak Php框架应用程序都是《Application》基类的子类，该基类位于《application/Application.php》。目前支持三种类型的应用程序。API、命令行和Web。
API应用程序扩展了《Api》基类。命令行应用程序扩展了《CommandLine》基类。Web应用程序可以扩展Web类或Page类。Page类是从Web类派生的。
主要的框架特性，如URL路由、会话处理、错误处理、翻译、函数验证和日志处理，是由《application/libraries》文件夹中的类实现的。每个特性都是独立于其他特性实现的。
配置
配置是Pak Php框架的主要特性之一。它允许在不显式初始化对象的情况下使用类对象。用户只需在《config/RequiredObjects.php》中提及类一次。例如
$config['contactpage']['class_name'] = '\PakJiddat\Ui\Pages\Contact';
然后可以使用以下语法使用该类：Config::GetComponent("contactpage");。框架负责初始化类对象。如果对象已经创建，则直接返回。所有类都使用PSR-4自动加载标准自动加载。
应用程序数据存储在《config/》文件夹中的配置文件中。有关详细信息，请参阅用户应用程序结构。可以使用以下语法访问配置变量
Config::$config["general"]["dev_mode"]
上面的代码返回应用程序的当前开发模式。如果它是false，则应用程序处于生产模式。
URL路由
Pak Php框架提供URL路由。用户应用程序应包含《config/Callables.txt》文件。此文件指定命令的回调以及处理URL请求的回调。文件中的条目有两部分。第一部分以 url: 或 command: 开始。第二部分以 callback: 开始。
应用程序应为每个URL或URL模式定义一个条目。条目中的第一行是一个正则表达式，用于定义要处理的URL。下一行定义应处理URL请求的回调函数。下一行定义一个可选的验证回调。这是用于验证应用程序参数的回调。
命令行脚本
如果应用程序有从命令行调用的函数，则每个函数应在《Callables.txt》中有一个条目，以 command: 开始。条目应指定用户需要从命令行输入的命令名称。下一行定义处理该命令的回调函数。例如，如果应用程序定义了“生成网站地图”的命令，则可以使用以下命令运行它
php index.php --application=[app-name] --command="Generate Site Map"
《Callables.txt》文件应包含以下条目
command: Generate Site Map
callback: {"object": "websitetools", "function": "GenerateSiteMap"}
此条目表示，当输入“生成网站地图”命令时，将调用对象“websitetools”的函数 GenerateSiteMap。配置文件：config\General.php 应包含以下行
/** The custom commands */
$config['commands'] = array("Generate Site Map (generates site map of website)");
上述命令定义了应用程序实现的命令。当用户输入命令时，这些命令将显示给用户
php index.php --application=[app-name] --command="Help"
此命令列出应用程序支持的所有命令。
以下代码显示了 Callables.txt 文件的示例内容
url: ^/$
callback: {"object": "homepage", "function": "Generate"}
url: ^/articles(/view/\d+/[A-Za-z\-0-9\._%]+)?$
callback: {"object": "viewarticlepage", "function": "Generate"}
url: ^/articles/(tag|search)/[a-z\-0-9A-Z\._%]+?$
callback: {"object": "listarticlepage", "function": "Generate"}
url: ^/contact/form$
callback: {"object": "contactpage", "function": "Generate"}
url: ^/contact/add$
callback: {"object": "contactpage", "function": "SendContactMessage"}
command: Generate Site Map
callback: {"object": "websitetools", "function": "GenerateSiteMap"}
模板引擎
Pak Php 框架包含一个模板引擎，允许用户应用程序将应用程序数据与 HTML 模板合并
测试管理器
Pak Php 框架提供用于测试代码的类。支持三种类型的测试：白盒测试、黑盒测试和 UI（用户界面）测试。白盒测试、黑盒测试 和 Ui（用户界面）测试。
白盒测试编写方式类似于 PhpUnit 测试。用户在文件中定义测试方法。每个方法名应以 "Test" 开头。然后从命令行运行测试。测试方法内可以使用断言语句来验证条件。
黑盒测试通过在测试文件内部定义测试数据来编写。每个方法都有其自己的测试数据文件。测试数据文件的第一行给出参数列表，参数之间用 '|' 分隔。第一行的最后三个条目给出期望的返回值、返回值类型和用于验证返回值的规则。可以为应用程序定义的每个方法自动生成测试数据文件。以下命令
php index.php --application="[app-name]" --action="Generate Test Data"
将为每个用户定义的方法生成测试数据文件。测试数据文件将放置在文件夹：test/testdata/{class-name} 中。文件名与方法名相同。以下是测试数据文件的示例结构
param_int_name1|param_int_name2|param_int_name3|return_name1|return_type|rule
1|1|7|{"count":7}|array|count
A UI（用户界面）测试允许检查响应的 HTML 是否存在错误。使用 validator.nu 服务检查 HTML 是否符合 HTML5 标准。作为 Ui 测试的一部分，也会检查断链。Ui 测试的测试数据定义在数据库表中。请参阅表结构：pakphp_test_data。它有两个主要字段，即 URL 和 URL 参数。此数据可以通过将 config/Test.php 中的 save_ui_test_data 变量设置为 true 来自动生成。当此选项设置为 true 时，框架将当前 URL 和参数保存到数据库
在运行黑盒测试或白盒测试之后，测试的代码覆盖率信息将在控制台上显示，并保存到数据库中。测试结果摘要保存到数据库和文件中。所有函数调用的跟踪日志也保存。代码覆盖率和函数跟踪是通过 XDebug 生成的。以下截图显示了运行黑盒测试后在控制台上打印的测试结果
以下截图显示了运行黑盒测试后的代码覆盖率摘要
工具
工具文件夹包含提供实用函数的类。这些类由框架使用，也可在用户应用程序中使用。有关如何使用实用类的信息，请参阅 Utilities Framework 包。
供应商
供应商文件夹包含第三方库，如 Twitter Bootstrap、JQuery、W3.CSS 和 QUnit。这些前端库可以用于 HTML 模板。可以开发可重用的控件，使开发者能够轻松创建外观吸引人的应用程序。
安装
- 运行以下命令
composer require nadirlc/pak-php-framework (Installation using Composer) OR
git clone https://github.com/nadirlc/pak-php-framework.git (Download from [GitHub Repository](https://github.com/nadirlc/pak-php-framework))
下载源代码后，创建一个名为 pakjiddat_pakphp 的 MySQL 数据库，并将文件 framework/data/pak-php-framework.sql 的内容导入到数据库中。这将创建 Pak Php 框架使用的数据库表。这些表用于保存错误数据、访问日志、测试数据和测试结果。
示例
helloworld 示例应用程序展示了如何开始使用 Pak Php 框架。要运行应用程序，请在 helloworld/Config.php 文件中输入用于访问应用程序的主机名。将 example.pakjiddat.pk 替换为 your-host-name。同时，在 helloworld/config/RequiredObjects.php 中输入数据库服务器的凭据。之后，在浏览器中打开应用程序。
对于更复杂的示例，您可以下载并安装以下之一
- 开发者网站。这是一个简单的网站，允许网络开发者发布他们的作品
- 伊斯兰伴侣网站。允许用户阅读神圣的《古兰经》和圣训。还允许通过电子邮件订阅《古兰经》和圣训
- 伊斯兰伴侣 Web API。它提供了一个 RESETFul API，用于获取《古兰经》和圣训数据