README

LamiaPHP

🏮 一个用于PHP的最小化MVC框架

内容

• 简介
• 安装
• 运行Lamia
• 模型、控制器和视图
  • 模型
  • 控制器
  • 视图
• 路由
  • 介绍路由
  • 合并路由
• 数据库
  • PDO
  • 迁移
• 验证
  • 介绍验证
  • 验证列表
• 测试
• 如何贡献
• 许可证

简介

每当我想启动一个不需要大框架帮助开发过程的简单PHP项目时，我都会进行创建范围、文件夹结构、设置等整个过程。为了解决这个问题，我想到了创建一个简单的模板。然而，在开发过程中，我发现项目已经不再是一个模板，而成了一个框架。于是，Lamia诞生了，一个用PHP编写的最小化框架。

安装

要安装Lamia，您必须在您的机器上安装以下依赖项

• PHP 8.0（或更高版本）
• Composer
• Docker
• Docker-compose

安装所有依赖项后，只需按照以下命令操作

composer create-project guilhermecostam/lamiaphp example-app

cd example-app

运行Lamia

安装完成，现在我们将运行应用程序。最初，我们将创建.env文件并填写其中的空白信息。

# create the .env file
cp .env.example .env

注意，数据库主机已经定义。

DB_HOSTNAME=127.0.0.1
DB_NAME=
DB_USERNAME=
DB_PASSWORD=

这是因为数据库正在Docker中运行，因此数据库主机是Docker的IP地址，通常是127.0.0.1。

如果您的机器不是127.0.0.1，只需运行ifconfig（Linux）或ipconfig（Windows）以找到Docker正在运行的IP地址。

现在我们将安装composer依赖项并运行容器。

composer install

docker-compose up -d

最后，如果所有步骤都正确执行，应用程序已经在localhost上运行，并准备好接收数据库迁移。

模型、控制器和视图

模型

模型必须在app/Models/目录中，并扩展Model抽象类

# create a symbolic namespace, based in directory
namespace App\Models;

use App\Core\Model;

class Coffee extends Model
{
    //
}

应用程序中的模型用于将控制器与业务规则和数据库进行通信。因此，在这里您应该编写数据库查询，可以使用db方法完成。有关更多详细信息，请参阅PDO部分。

控制器

控制器必须在app/Controllers/目录中，并扩展Controller抽象类

namespace App\Controllers;

use App\Core\Controller;

class CoffeeController extends Controller
{
	//
}

应用程序中的控制器用于在视图发送的请求与由模型提供的信息之间进行中介。这也是在这里对表单上提供的数据进行验证的地方。

视图

视图必须在app/Views/目录中，这是应用程序视觉信息应该包含的层。只有模板应该放在这里，CSS样式和可以公开访问的JavaScript文件应该放在public/目录中。

要渲染视图，您需要导入您想要调用的视图类，并使用指定的目录调用render方法

use App\Core\View;

// ...
	(new View)->render('coffee/index');
// ...

请注意，这里您只需指定为视图创建的文件夹和文件名，无需添加.php扩展名，因为render函数已经直接访问了app/Views/目录，包括扩展名。

如果您想向视图作用域发送信息，只需创建一个包含该信息的数组。在视图中访问它，只需调用变量 $args 并指定发送的键

# in controller
$messages = [
	'lorem' => 'ipsum'
];

(new View)->render('coffee/index', $messages);

# in view
$args['lorem']; // return must be: 'ipsum'

最后，视图还可以渲染 HTTP 错误。只需在 app/Views/error/ 目录中创建包含所需错误的视图，并调用 errorCode 函数，将错误作为整数传递。它还有一个 redirect 方法，可以将请求重定向到作为参数传递的 URL

# error code render
(new View)->errorCode(500);

# redirect to url
(new View)->redirect('/');

值得注意的是，errorCode 函数还接受如 render 这样的参数。

路由

介绍路由

应用程序路由必须位于 routes/ 目录中。正确的方法是将它们分开成具有分组路由相关命名的文件。

例如，负责咖啡 CRUD 的路由应包含在 coffee.php 文件中，而负责啤酒 CRUD 的路由应包含在 beer.php 文件中。

然而，您完全可以将所有应用程序的路由放入一个单独的文件中。

创建路由很简单。只需包含 Router 类和具有要使用功能的控制器

use App\Core\Router;
use App\Controllers\CoffeeController;

之后，只需创建一个 $routes 数组，并按照以下结构对其进行配置，调用 Router 的 createRoute 函数

$routes = [
	'/coffee/create' => (new Router)->createRoute(CoffeeController::class, 'create'),
	'/coffee/edit' => (new Router)->createRoute(CoffeeController::class, 'edit'),
];

return $routes;

在捕获未定义的路由的情况下，应用程序已经准备好返回一个 404 错误视图。

合并路由

为了让系统识别创建的路由，需要在 web.php 文件中合并创建的文件

$routes = array_merge(
	include 'coffee.php',
	include 'beer.php',
);

数据库

PDO

对于数据库，正在使用 MySQL。我们将使用 PDO 与数据库通信并创建查询。

在抽象类 Model 中，已经使用连接类实例建立了数据库连接。只需在扩展模型的类中调用 db 属性，并调用以下方法

# query for returns rows
$this->db->row('SELECT * FROM beers');

# query for returns columns
$this->db->column('SELECT * FROM beers');

值得指出的是，也可以使用这些方法绑定值。只需创建以下查询，并传递一个包含要替换的值的参数数组

# query for returns rows with bind params
$params = [
	'field' => 'brand'
];
$this->db->row('SELECT :field FROM beers', $params);

迁移

在 Lamia 中，您可以通过 Phinx 使用迁移。迁移将自动放入 database/migrations/ 目录，通过以下命令创建

/vendor/bin/phinx create MyNewMigration

有关编写迁移和 Phinx 的其他功能的更多详细信息，请参阅其 文档。

验证

介绍验证

如果您想在表单中验证数据，Lamia 为此提供原生功能。只需在 app/Requests/ 目录中创建编写规则的文件。在每个文件中，您必须扩展抽象类 Request

# create a symbolic namespace, based in directory
namespace App\Requests;

use App\Core\Request;

class CreateCoffeeRequest extends Request
{
    //
}

要执行验证，您必须创建一个公共方法 validations。这将返回每个已验证字段的返回值的 array_merge。

在合并中调用的 validate 方法必须接收两个参数。这些是待验证的字段名称和要应用于分配给字段的值的验证数组的数组。

public function validations(): array
{
	return array_merge(
		parent::validate('lorem', [
			'required' => 'Field should be required',
			'isString' => 'Field should be string',
		]),
		parent::validate('ipsum', [
			'isBoolean' => 'Field should be boolean',
		]),
	);
}

注意

• validate 接收的数组必须包含具有应用在应用程序中预定义的验证的名称作为键，以及验证失败时显示的消息作为值的项。
• 请注意，对扩展的 validate 方法 Request 的每次调用都是针对表单的一个字段。

现在，只需将请求包含到您想要执行验证的地方，并调用 validations 方法

use App\Requests\CreateCoffeeRequest;

// ...
    $messages = (new CreateCoffeeRequest)->validations();
// ...

验证列表

以下是应用程序中可用的所有验证列表

测试

对于单元测试，正在使用 PHPUnit。测试应该写在 tests/ 目录中，要运行它们，只需运行以下命令

# for a specific test
/vendor/bin/phpunit -v tests/ExampleTest.php

# for a specific path
/vendor/bin/phpunit -v tests

有关编写测试、断言列表和PHPUnit其他功能详情，请参阅其文档。

如何贡献

您想为Lamia做出贡献吗？只需遵循以下说明：

1. 将此存储库Fork。
2. 克隆您的存储库。
3. 创建一个带有您功能的分支：git checkout -b my-feature
4. 提交您的更改：git commit -m 'feat: 我的新功能'
5. 将更改推送到您的分支：git push origin my-feature
6. 从原始项目提交Pull Requests并创建一个针对dev分支的Pull Request。

您的Pull Request合并完成后，您可以删除您的分支并等待反馈。

许可证

本项目采用MIT许可证 - 有关详细信息，请参阅LICENSE页面。