README

Module PHP 是一个遵循最佳实践并融合了先进技术的 PHP 模块化框架，旨在为创建健壮和可扩展的 Web 应用程序提供一个灵活和高效的架构。它专注于创建具有多级用户的多级 Web 应用程序。

功能

自动构建路由：实现一个自动定义和管理路由的系统，简化 Web 应用程序的路由过程。
资产构建器：提供构建器来构建资产，如 JavaScript、CSS、图片和视频，简化资源的生产环境准备。
PWA 自动创建：具有自动化创建渐进式 Web 应用程序 (PWA) 的功能，提供高级用户体验。
Lighthouse 集成：与 Lighthouse 集成以自动评估应用程序的质量和性能，有助于持续优化。
性能优化自动化：实施自动化资源，以优化页面加载性能，确保用户获得敏捷体验。
多级用户支持：提供对多级用户的支持，通过封装来确保更高的安全性和访问控制。
全局资源：提供适用于所有用户的全局资源，确保开发中的一致性和效率。
数据库和电子邮件自动连接：简化与 MySQL 数据库和电子邮件服务的自动连接，简化开发和功能集成。
环境切换简便：允许轻松在开发环境和生产环境之间切换，简化开发和部署过程。
辅助脚本：包含用于简化框架中操作的脚本，如添加用户级别或用户，加速常见管理任务。
通用代码库：提供通用代码库，如页眉、页脚、脚本、样式和元标签，以避免在所有页面中重复代码，促进重用和高效维护。
性能检查器：集成了性能检查器，它记录每个请求中每个操作的耗时，允许识别和优化性能瓶颈。
用户资源：提供用户管理资源，包括登录、注销、注册和修改密码的简化方式。
JSON 自动响应：实施资源以自动生成 JSON 响应，简化与外部 API 和服务的集成。
Node.js 集成：与 Node.js 集成以执行专用资源，需要在本机上安装 Node 以利用特定功能。
颜色调色板创建器：包含颜色调色板创建器，用于适应不同的视觉身份，确保用户获得个性化的体验。
日志生成器：具有日志生成器，方便应用程序的调试和监控，有助于诊断问题和维护系统。
通过PHPUnit进行单元测试：提供通过PHPUnit进行单元测试的支持，确保开发出的代码的质量和健壮性。
这些都是Module PHP项目的主要功能，旨在提供先进的、高效的Web开发体验。

安装

通过Composer创建项目：首先，使用Composer创建一个新项目。在终端中执行以下命令
```
composer create-project duxtec/modulephp
```
安装依赖项：在项目目录内执行以下命令安装项目的依赖项，以便在终端中
```
composer install
```
填充配置文件：创建项目后，您需要使用必要的信息填充配置文件。有两种方法可以做到这一点
- 使用命令
```
php allay configure
```
  有关更多信息，请参阅脚本。
  
  此命令将引导您完成填写必要配置的过程。
- 手动：如果您愿意，可以在config文件夹中手动创建.env文件，使用.env.example文件作为模板。复制.env.example文件并将其重命名为.env，然后根据需要填写环境变量的值。
更新数据库模式
```
php allay update:schema
```
有关更多信息，请参阅脚本。
准备开始开发

如果您按照上述步骤操作，则项目已配置完毕，准备开发！现在，我们建议您

阅读README中的第一步部分，以获取有关如何使用框架开发项目的指导。
探索文档，以获取有关可用资源、API和工作流程的更详细信息。

享受开发过程！

如果您需要帮助或有问题，请参阅文档或与开发团队联系。

第一步

用户级别

app目录是系统大部分代码的位置。它包含为每个用户级别提供特定文件夹的文件夹，确保封装和安全。该结构旨在清楚地分离不同类型用户的职能和权限。

创建用户级别

可以使用以下命令创建用户级别

php allay create:userlevel nome_do_nível_de_usuário

有关更多信息，请参阅脚本。

创建用户级别时，将在app文件夹中创建相应的目录。此外，用户级别将自动分配ID并在数据库中注册。

特殊级别

存在两个特殊用户级别

public：表示未登录系统中的用户。该文件夹中的内容对所有未登录网站访客均可访问。
global：包含所有用户共享的资源。如果请求的资源未在特定用户文件夹中找到，则将在返回“找不到资源”错误之前在该文件夹中查找。

按用户级别划分的目录结构

对于每个用户级别，app目录内的目录结构类似，包含models、controllers、views和assets文件夹。这确保每个用户级别都可以拥有自己的资源集和功能。

这种组织方式允许清楚地分离和管理资源，便于维护和系统扩展。

渲染基础

渲染基是HTML页面结构，它们在应用的不同视图中共享，可以直接使用HTML或通过具有render()方法的类来创建。这提供了开发中的灵活性，允许在简单性和组件重用之间进行选择。每个用户级别都可以在其各自的文件夹中拥有自己的渲染基，或者使用全局渲染基。

可用的渲染基如下：

view/base/head/metatag.php：定义在所有页面中使用的HTML元标签，如描述、关键词和其他元数据。
view/base/head/script.php：包含在所有页面的<head>部分加载的JavaScript脚本。
view/base/head/style.php：包含在所有页面的<head>部分加载的CSS样式表。
view/base/body/aside.php：定义可被不同页面用于导航或附加信息的侧边栏（aside）部分。
view/base/body/header.php：定义顶部所有页面出现的通用头部（header）。
view/base/body/main.php：定义页面主体（main）部分，其中显示主要内容。
view/base/body/footer.php：定义出现在所有页面底部的页脚（footer）。

渲染基的示例可以在相应的文件夹中找到。

路由

该框架使用三种主要类型的路由来组织和实现功能，这些路由约定有助于清楚地组织和分离应用的不同功能方面，确保结构清晰和模块化。

要创建新的路由，只需在相应的目录中创建一个文件，该类型路由将自动创建。

路由如下：

页面路由（默认路由）
- 描述：只需在相应的文件夹中创建一个文件，路由就会自动创建。
- 目录：app/USERLEVEL_NAME/view/pages
- 路由条件：所有非controller或assets的路由都将重定向到此目录。
资源路由
- 描述：这些路由用于提供如JavaScript、CSS、图像和其他用户界面所需资源的静态文件。在开发过程中，文件从src目录提供，而在生产中，文件在优化后生成到build目录。更多信息请参阅生产。
- 目录:
  - 开发：app/USERLEVEL_NAME/assets/src
  - 生产：app/USERLEVEL_NAME/assets/build。
- 路由条件：所有以"assets/"开头的路由都将重定向到此目录。
控制器路由
- 描述：：这些路由默认使用JSON通信，可用于开发RESTful API。
- 目录：app/USERLEVEL_NAME/controller
- 路由条件：所有以"controller/"开头的路由都将重定向到此目录。

示例

安装框架后，您将获得帮助您更好地理解如何使用其主要功能的实际示例。示例可以在以下位置找到

app/USERLEVEL_NAME/view/base
app/USERLEVEL_NAME/view/pages
app/USERLEVEL_NAME/assets/src
app/USERLEVEL_NAME/controller
app/USERLEVEL_NAME/model

在文档（开发中）中，您还可以找到详细示例和逐步指南，介绍框架的多种功能。

开发模式下的配置和执行

要在本地开发环境中启动您的项目，请按照以下步骤操作

初始配置
- 请确保配置文件config/system.env已正确配置。请确保变量PRODUCTION被定义为false。这确保了环境配置为开发模式。
本地服务器执行
- 使用以下命令启动本地服务器。该命令将在默认端口93上启动服务器。
```
php allay localhost
```
  有关更多信息，请参阅脚本。
  
  请确保端口93已打开并可使用。根据用户权限，可能需要以提升的权限执行命令（例如，使用sudo）。

目录结构

主要目录

app：此目录包含对应每个用户级别的文件夹。这种组织结构确保了用户封装，提高了安全性。

特殊用户级别:
- public：未登录系统用户的用户级别。
- global：为所有其他用户服务的用户级别。如果请求的资源对特定用户不可用，它将首先在global级别中查找，然后再报告不存在。
子目录:
- model：包含代表业务逻辑和数据结构的应用程序模型。
- controller：包含处理应用程序逻辑和调度对输入请求的响应的控制器。
- view/base：包含不同视图之间共享的通用页面结构。
  - view/base/head/metatag.php：定义在所有页面中使用的HTML元标签，如描述、关键词和其他元数据。
  - view/base/head/script.php：包含在所有页面的<head>部分加载的JavaScript脚本。
  - view/base/head/style.php：包含在所有页面的<head>部分加载的CSS样式表。
  - view/base/body/aside.php：定义可被不同页面用于导航或附加信息的侧边栏（aside）部分。
  - view/base/body/header.php：定义顶部所有页面出现的通用头部（header）。
  - view/base/body/main.php：定义页面主体（main）部分，其中显示主要内容。
  - view/base/body/footer.php：定义出现在所有页面底部的页脚（footer）。
- view/pages：包含用户看到的页面内容。每个位于pages中的文件或子目录代表网站上的单个页面。
- view/modules：包含可重用的模块或组件，可以包含在多个页面中。这些模块作为封装用户界面特定部分的组件，便于重用和维护。
- view/assets：包含所有静态资源，如图像、JavaScript文件和CSS样式表。在开发期间，文件保存在src中。在生产中，编译和压缩后的文件存储在build中。

config：存储系统配置，如数据库访问数据和电子邮件。还包括有关网站的详细信息，如名称、描述、主要颜色、链接到其他网络等。有关更多信息，请参阅安装的第3项。

database：数据库实体和缓存所在的位置，将由ORM Doctrine加载。有关更多信息，请参阅Doctrine ORM文档。

logs：保存错误或审计日志的文件夹。错误日志由框架自动生成，使用Monolog。审计日志可以使用php allay lighthouse命令生成，此功能依赖于Node和兼容Lighthouse的浏览器，如Chrome。有关更多信息，请参阅Lighthouse CLI文档。

public_html：包含.htaccess和index.php。Web服务器的公共根目录应指向此目录以正确运行框架。

resources：包含框架的本地功能。不建议编辑此目录，因为这可能会影响框架的安全性，并且这些文件在更新期间可能会被重写。

更新：在更新之前，请仔细阅读更新部分。
兼容性：升级或降级仅在版本主版本相同之间兼容。例如：任何1.x.y版本之间兼容，但不与2.x.y或3.x.y版本兼容。
协作：如果您有兴趣为框架更新做出贡献，开发或修改的功能应位于此目录中。您的贡献非常受欢迎，请提交一个Pull Request :)

scripts：包含框架使用的脚本。不建议编辑此目录下的脚本。要执行脚本，请使用“allay”命令行界面。

脚本执行：不建议直接通过脚本文件执行脚本。要执行脚本，请使用php allay nome_do_script。要动态选择所需的脚本，请仅输入php allay以访问脚本选择器。要获取有关脚本的帮助，请使用php allay nome_do_script -h或php allay nome_do_script --help。

tests：应在PHPUnit中进行测试的地方。如有疑问，请参阅PHPUnit文档。PHPUnit文档

vendor：Composer库安装的目录。

生产

要配置和在生产环境中执行您的框架，请按照以下步骤操作

生产配置
- 打开配置文件config/system.env。
- 将变量PRODUCTION更改为true。
资产构建
- 执行以下命令以构建资产
```
php allay build
```
- 此命令将编译并准备资产以在生产环境中使用。
服务器部署
- 确保Web服务器的公共目录指向public_html。
- 将构建后生成的所有文件和目录传输到服务器的public_html目录。
本地测试
- 要测试本地生产版本，请执行以下命令
```
php allay localhost
```
- 此命令将在本地构建资产并启动一个在端口93上运行的带有生产配置的本地服务器。
系统访问
- 在配置和部署系统到生产环境后，通过浏览器使用配置的Web服务器对应的地址访问它，该地址指向public_html目录。

请务必仔细遵循这些步骤，以确保您的框架正确配置并能在生产环境中正常工作。

测试

要执行测试，请按照以下步骤操作

测试位置
- 测试位于/tests目录中。
- 要添加新测试或执行现有测试，请导航到该目录。
PHPUnit的使用
- 测试使用PHPUnit执行。
- 请参阅PHPUnit官方文档以学习如何编写和执行特定测试。

审计

要在本地进行项目审计，请按照以下步骤操作

Lighthouse执行
- 确保项目在本地运行。
- 在终端中执行命令php allay lighthouse。
- 您的系统上需要安装Node.js。
- Lighthouse需要一个兼容的浏览器，例如Chrome，以执行审计。
日志位置
- 审计结果将保存在目录/logs/lighthouse中。
- 每个生成的审计将被存储在一个以执行日期和时间命名的HTML文件中。

使用Lighthouse进行审计可以帮助确保您的项目满足性能、可访问性、最佳实践和SEO标准。使用这些信息根据需要优化和改进您的项目。

更新

升级或降级仅在主版本相同之间兼容。例如：任何1.x.y版本之间兼容，但不与2.x.y或3.x.y版本兼容。

要更新框架，只需将系统的resources目录替换为所需版本的resources目录，或执行更新脚本（正在开发中）php allay update，该脚本将自动执行此过程。

即使在兼容的更新中，也非常推荐在将版本部署到生产之前，先备份旧系统和在开发环境中进行测试，我们不对不正确的更新或意外行为负责，请负责任地更新，并自行承担风险。

贡献

该项目对所有感兴趣的开发者开放贡献。以下是一些贡献方式

报告问题（Issues）:
- 如果您在框架中发现任何问题或bug，请随时通过GitHub issues进行报告。
- 确保包括尽可能多的详细信息，并在适用的情况下，附上截图或代码片段。
发送Pull Requests:
- 欢迎通过pull requests进行错误修复、新功能或文档改进的贡献。
- 在发送pull request之前，请确保您的代码遵循样式指南并已通过测试。
改进文档:
- 文档对于简化框架的使用至关重要。如果您发现现有文档中可以改进的方面，请随时提出建议或发送更改。
分享和反馈:
- 与其他开发者分享框架，在论坛或社交媒体上参与讨论。
- 如果您有任何关于改进框架的反馈或建议，请通过提供的联系方式联系。

贡献指南

为确保贡献顺畅有效，请遵循以下指南

编码标准：采用项目中的编码标准以保持一致性。
测试：确保所有更改都由适当的单元测试覆盖。
文档：在文档中记录任何新的功能或更改，如果适用。
遵守行为准则：遵守项目行为准则，并以尊重和礼貌的态度对待所有参与者。

感谢贡献者

感谢迄今为止为项目做出贡献的所有开发者。您的支持对于框架的持续成功至关重要。

贡献者

由公司开发：Dux技术。

由开发者开发：Thiago Costa Pereira。

感谢：Leonardo Coelho的热心参与和测试。

许可证

本项目许可协议为MIT许可协议，鼓励在GPL-3.0许可下创建软件并共享源代码。

联系方式

更多信息或支持，请联系

电子邮件： contato@tpereira.com.br
WhatsApp： +55 21 98903-2187
网站： https://tpereira.com.br

版本说明

版本1.0.0（第一个稳定版本）

这是框架的第一个稳定版本。
包括文档中描述的所有主要功能。
错误修复和性能改进。

duxtec / modulephp

维护者

详细信息