README

轻量、易于使用的PHP MVC框架

V1.1.0版本的新功能

• 更好的URL路由
• 支持额外的请求类型
• 更好的错误处理
• 强大的模板引擎
• 中间件
• 额外的控制台命令
• 支持所有Web服务器
• 额外的实用工具
• 迁移模式
• 灵活的模型

文档

安装

• 仓库

使用git命令或下载zip文件克隆此目录

• Composer

运行以下命令通过Composer安装Traillamp

    composer require etorojah/traillamp

在Composer的vendor文件夹中找到traillamp文件夹，移动到最终位置并重命名。

用法

对于本地开发，任何服务器环境应用程序（如Xampp、Lamp或Laragon）都可以运行Traillamp。首先在app/env/.env文件中配置环境变量，然后启动应用程序

.env文件参数

• APP_KEY：唯一的应用程序标识符。
• APP_NAME：您的应用程序/API名称。
• APP_VERSION：您的应用程序或API版本。
• DATABASE_HOST：您的数据库连接主机，默认为localhost。
• DATABASE_USER：您的数据库连接用户名，默认为root。
• DATABASE_PASSWORD：您的数据库连接密码。
• DATABASE_NAME：数据库名。
• ENCRYPTION_KEY：用于加密/解密的随机字符串。
• MAIL_HOST：邮件主机。
• MAIL_PORT：用于从应用程序发送邮件的端口。
• MAIL_USERNAME：邮件用户名。
• MAIL_PASSWORD：邮件用户名密码。
• MAIL_SENTFROM：描述邮件来源，例如The Traillamp Support Desk。
• SUBDOMAIN：当为true时，开发服务器设置为子域或文件夹路径（https://example.com/traillamp/、https://traillamp.example.com、https:///traillamp）

如果您将内容直接部署到服务器根目录（htdocs、www、public_html），请将此值设置为false。

文件夹结构

• console.exe：使用控制台可执行文件运行Traillamp控制台命令。
• app：包含所有要处理的资源。
• app/controllers/：应用程序控制器在此处找到。
• app/env/：.env文件位于此处。包含环境变量。
• app/errors/：包含错误日志文件，用于错误记录和参考。
• app/middlewares/：应用程序中间件在此处找到。
• app/migrations/：包含数据库迁移模式文件。
• app/models/：应用程序模型在此处找到。
• app/public/：包含在视图中引用的文件，如样式表、脚本和其他文件。
• app/routes/：包含所有路由和路由文件。
• app/server/：默认应用程序代码库存储在此处。在此处编辑任何文件可能会破坏您的应用程序。
• app/utilities/：包含邮件实用工具文件。
• app/views/：视图子文件夹和文件在此处找到

路由

• 基本路由

所有路由文件都位于 app/routes/ 目录。可以写如下一个没有中间件的简单路由。

   $router::get("/", "WelcomeController@main");

第一个参数是相对路由路径或URL

第二个参数是控制器名称和控制器方法，它们由一个@符号分隔。

路由也可以通过函数回调来调用。例如：

     $router::get("/", function(){
        echo "ok";
    });

路由可以通过指定为路由的中间件作为第三个参数来调用。以下是一个简单带中间件的路由示例。

   $router::get("/", "WelcomeController@main", "WelcomeMiddlewarre@main");

或者使用函数：

    $router::get("/", "WelcomeController@main", function(){
        echo "ok";
        return true;
    });

请记住在您的路由文件中使用适当的请求方法。

• 参数化路由

带有参数的路由使用花括号中的参数名称指定。

  $router::get("/about/{name}", "Controller@Main");

因此，访问 https://url/about/Etorojah 将调用控制器类中的Main方法，并将名称参数的值设置为Etorojah。

支持多个参数。要获取参数的值，只需简单使用

    $this->parameter 

示例

    echo $this->name;

在中间件或控制器方法中。

可以将最多4个参数传递给回调函数。

对于具有超过4个参数的路由，应使用控制器/中间件类方法。

您可以将参数传递给控制器/中间件回调函数，如下所示

    $router::get("/about/{name}", "WelcomeController@main", function($name){
        echo $name;
        return true;
    });

• 支持的请求

• GET

• POST

• PUT

• PATCH

• HEAD

• DELETE

• 多个路由文件

要创建路由文件，只需在Traillamp控制台中运行以下命令

    create router-file <filename>

示例

    create router-file admin_routes

控制器

控制器是您应用程序的核心。控制器位于 app/controllers/ 目录中。

所有控制器都继承了位于 Controller.php 文件中的 Controller 默认类的属性和方法。

• 创建控制器

要创建控制器，在Traillamp控制台中运行以下命令

    create controller <name>

示例

    create controller Test

以上在 app/controllers/ 目录中创建了一个Test.php控制器文件。

控制器文件名和类名必须相同。

现在您可以将创建的控制器添加到您选择的任何路由中。

• 默认属性和方法

request 属性持有给定路由和请求类型的请求参数（数组）。这可以用来获取表单值和其他请求参数。

例如，使用一个处理表单的POST请求的路由

    $name = $this->request["name"];

method 属性持有请求类型，这在代码块中可能很有用。例如

    $name = $this->method;
    //returns POST for a POST request method etc

files 属性持有发送到该路由的请求参数中的文件。例如

    $file = $this->files["photo"];
    

如前所述，路由参数也可以使用控制器和中间件中的 $this->parameter 获取。

• 继承的方法

可以从任何扩展父控制器类的控制器中访问继承的方法。

它们列在下面

渲染视图： view(view, parameters)

要渲染视图，使用继承的类方法 view，该方法携带两个参数

• view: 字符串，视图的名称（不带文件扩展名）。

• parameters: 数组，要传递给视图模板引擎的值。

'parameters' 参数是可选的。例如

• 无参数

    $this->view("welcome");

    //subfolder view
    $this->view("includes.header");

以上渲染了位于 app/views 目录中的视图 welcome.lamp 和位于 app/views/includes/ 子目录中的 header.lamp。

• 有参数

    $this->view("profile", ["name" => "John", "email" => "john@site.io"]);
    

参数传递给模板引擎，并可以在视图文件中使用。

重定向： redirect(route)

要重定向到另一个路由，使用继承的类方法 redirect，该方法携带一个参数

• route: 字符串，相对有效URL路由。例如

    $this->redirect("/about/me");
    

加密： encrypt(text)

要加密纯文本，使用继承的类方法 encrypt，该方法携带一个参数

• text: 字符串，要加密的纯文本。例如

    $hash = $this->encrypt("I am Batman");
    echo $hash;
   

解密： decrypt(hash)

要解密纯文本，使用继承的类方法 decrypt，该方法携带一个参数

• text: 字符串，要解密的纯文本 示例

    $hash = $this->encrypt("I am Batman");
    $text = $this->decrypt($hash);
    echo $text;
    //returns I am Batman
    

请记住设置环境变量，ENCRYPTION_KEY

发送邮件: sendMail(email, subject, message)

要发送邮件，请使用继承类方法 sendMail，该方法包含三个参数：

• email：字符串，有效的电子邮件地址。
• subject：字符串，消息的主题。
• message：字符串，消息正文。示例

    sendMail("john@site.io", "Greetings", "Hello to you");

请记住设置所有邮件环境变量。

加载模型: loadModel(model)

要加载和获取数据库模型结果，请使用继承类方法 loadModel，该方法包含一个参数：

• model：字符串，格式为 Class@method 示例

    $result = loadModel('Users@get_users');

请记住始终在模型方法中返回模型结果。

中间件

中间件位于 app/middlewares/ 目录中。

所有中间件都继承默认的 Middleware 类方法。中间件可用于身份验证等多种用途

• 创建中间件

要创建中间件，请在 Traillamp 控制台运行以下命令

    create middleware <name>

示例

    create middleware Test

上述命令在 app/middlewares/ 目录中创建了一个名为 Test.php 的中间件文件。

中间件文件名和类名必须相同。

现在您可以将其添加到您选择的任何路由中。

• 默认属性和方法

中间件具有与控制器中相同的默认属性（见上文控制器）。

• 继承的方法

可以从扩展父中间件类的任何中间件中访问继承的方法。

中间件具有与控制器中相同的继承方法（见上文控制器）。

所有中间件都应该有一个 return true 语句。这使应用程序能够将逻辑传递给控制器。

如果这样做，将抛出异常。

示例：使用中间件检查账户类型

    $router::get("/accounts/{type}", "WelcomeController@main", function($type){
        if($type !== "user") {
            echo "You are not allowed to access this page";
            exit;
        }

        return true;
    });

在中间件方法中也适用相同的规则。

模型

模型与数据库交互。它们用于查询数据库。所有模型都继承了在 Model.php 文件中的默认类 Model 的属性和方法。

• 创建模型

要在 Traillamp 控制台创建模型，请运行以下命令

    create model <name>

示例

    create model Test

上述命令在 app/models/ 目录中创建了一个名为 Test.php 的模型文件。

模型文件名和类名必须相同。

• 默认属性和方法

模型从父模型继承了数据库连接变量。

Traillamp 使用 PDO 进行数据库连接和迁移。然而，出于灵活性的考虑，您可以使用任何其他格式来完成此操作。

只需在模型文件中连接到数据库或创建一个数据库连接类，将其包含在模型文件中并使用即可。

注意：模型方法必须有一个返回语句。这使得在 loadModel 方法中将值传递给控制器变得容易。

使用 PDO 查询模型方法的示例

    public function main(){
        try {
            $sql = "SELECT * FROM table_name";
            $stmt = $this->db->prepare($sql);
            $stmt->execute();
            $result = $stmt->setFetchMode(PDO::FETCH_ASSOC);
            return $stmt->fetchAll();
            
        } 
        catch (PDOException $error) {
            die("Error in query:\n".$error->getMessage());
        }
	
    }

视图

视图位于 app/views/ 目录中。视图文件具有扩展名 .lamp。

• 创建视图

要在 Traillamp 控制台创建视图，请运行以下命令

    create view <name>

示例

    create view profile

上述命令在 app/views/ 目录中创建了一个名为 profile.lamp 的视图文件。

• 将参数传递给视图

Traillamp 使用 Twig 作为其模板引擎。Twig 很容易使用。您可以在此处查看 Twig 的文档： Twig 文档。您可以使用 Twig 的模板语法在视图文件中操作从控制器传递到视图的参数。示例 在控制器中：

    $this->view('about', ['name' => 'David']);

在视图中

    <h5>{{ name }}</h5>

数据库查询结果甚至可以在控制器中显示 在控制器中：

    $result = $this->loadModel('Users@get_users');
    $this->view('about', ['users' => $result]);

在视图中

    {% for user in users %}
        <h5>Name: {{ user.name }} </h5> 
    {% else %}
        <h5>No Users found </h5> 
   {% endfor %}

• 引用外部文件

app/public/ 目录中的样式表和脚本可以在视图中引用示例

    <!--Stylesheets-->
    <link rel="stylesheet" href="./app/public/css/styles.css">
    <!--Scripts-->
    <script src="./app/public/js/script.js"></script>

注意相对路径 ./app/public

实用工具

位于 app/utilities/ 文件中的 mail.html 可以替换为您喜欢的邮件设计。

但是，在您希望消息正文进入的地方保留 **********。

控制台命令

以下是 Traillamp 的控制台命令列表。

您可以在 Traillamp 控制台中输入 --help 来查看 Traillamp 的完整控制台命令列表。

• 清除错误日志 | 清除错误日志文件
• 查看错误日志 | 显示错误日志
• 创建控制器 | 使用文件名和类创建控制器
• 创建中间件 | 使用文件名和类创建中间件
• 创建模型 | 使用文件名和类创建模型
• 创建视图 | 使用文件名创建视图
• 创建路由文件 | 使用文件名创建路由文件
• 创建迁移文件 | 创建迁移文件
• 删除控制器 | 删除指定文件名的控制器
• 删除中间件 | 删除指定文件名的中间件
• 删除模型 | 删除指定文件名的模型
• 删除路由文件 | 删除指定文件名的路由文件
• 删除视图 | 删除指定文件名的视图

迁移

注意：此功能仍在开发阶段。 迁移模式可以用于创建和修改数据库及其表。迁移模式文件位于 app/migrations

• 创建迁移模式文件

要在 Traillamp 控制台中创建模式文件，请运行以下命令

    create schema-file <name>

示例

    create schema-file users

上述命令在 app/migrations 中创建了一个 users.php 文件。

Traillamp 支持 three 种类型的模式

• DatabaseSchema
• TableSchema
• ActionSchema

要创建模式，创建相应类型的一个实例，并使用适当的参数调用该类的 migrate 方法。示例

    //Database schema
    $schema = new DatabaseSchema($parameters);
    $schema->migrate();

• DatabaseSchema

此类用于创建数据库。它携带一个参数，即要创建的数据库的名称。示例

    //new Database schema
    $dbname = "db_test";
    $schema = new DatabaseSchema($dbname);
    $schema->migrate();

• TableSchema

此类用于创建表。它携带两个参数，即要创建的表名和表结构。

• name: string, 表名
• structure: array, 格式 ["col_name" => ["type" => "", "length" => "", "null" => boolean], ...] 示例

    //new Table schema
    $tablename = "users";
    $schema = new TableSchema($tablename, [
        "email" => ["type" => "varchar", "length" => "255"], 
        "fullname" => ["type" => "varchar", "length" => "255", "null" => true]
    ]);
    $schema->migrate();

注意： 结构中不应包含 id 列。

• ActionSchema

此类用于修改数据库、表和表列。它携带一个参数，即结构。

• structure: array, 格式 ["action" => "", "target" => "", "target_type" => "", "action_type" => "", "data" => ["data_type" => "", "column" => ""]]

action: 可以是 'truncate' 或 'alter'。 target_type: 可以是 'database' 或 'table'。 target: 可以是一个数据库或表名。 action_type: 可以是 add、drop 或 modify。 data-data_type: 数据库表列的任何数据类型（varchar、int、date、date-time）等。 data-column: 表列名。

示例

    //dropping a database
    $schema = new ActionSchema([
        "action" => "alter", 
        "target" => "db_name",
        "target_type" => "database",
        "action_type" => "drop"
    ]);
    $schema->migrate();

    //dropping a table
    $tablename = "users";
    $schema = new ActionSchema([
        "action" => "alter", 
        "target" => $tablename,
        "target_type" => "table",
        "action_type" => "drop"
    ]);
    $schema->migrate();

    //truncate a table
    $tablename = "users";
    $schema = new ActionSchema([
        "action" => "truncate", 
        "target" => $tablename,
        "target_type" => "table"
    ]);
    $schema->migrate();

通过传递正确的参数可以实现其他操作。要迁移模式文件，只需访问 "https://domain.ext/path/migrations/"

您可以通过更改下面一行中的路径在 routes.php 中更改此路径为任何您选择的路径

    $router::get("/migrations/", "MigrationController@main");

MigrationController 类处理迁移，因此，app/controllers/ 中的 MigrationController 文件不应删除，除非不再使用。

注意 为了安全起见，在应用程序部署后，请从 routes.php 文件中注释或删除迁移路径。

错误处理

开发过程中出现的任何错误都会显示在屏幕上。错误还会记录到 error_log 文件中供参考。

可以使用清除错误日志命令清除错误日志文件

问题

如果您遇到参数化路由冲突，可以通过使其中一个冲突的路由唯一来解决此问题。示例

    $router::get("/about/{user}", "AboutController@main");
    $router::get("/profile/{id}", "ProfileController@main");
    //this may create a routing conflict

上述问题可以按以下方式解决

    $router::get("/about/{user}", "AboutController@main");
    $router::get("/{id}/profile", "ProfileController@main");
    //routing conflict solved

或

    $router::get("/about/{user}/details", "AboutController@main");
    $router::get("/profile/{id}", "ProfileController@main");
    //routing conflict solved

发现其他任何问题，请创建一个问题。

贡献

要为该项目做出贡献，请发送电子邮件至 etorojahokon100@gmail.com 或拨打 +234 803 264 5840