README

Docker

Docker 是一个开源的虚拟化平台，允许通过容器创建、部署和运行应用程序。容器允许您将软件及其所有依赖项打包在一起，包括库、操作系统和其他依赖项。这意味着您可以确保应用程序在执行的环境中以完全相同的方式运行。

更多信息或下载链接，请访问 Docker 官方网站 https://dockerd.com.cn/。

在 VS Code 中使用 Docker

• 在 VS Code 中安装 Dev Container 扩展
• 创建一个包含 Dockerfile 和 devcontainer.json 文件的 .devcontainer 文件夹
• 在 VS Code 的侧边菜单中，有 Dev Container 扩展的图标，可以用来管理（创建、暂停、打开）容器和目录。如果打开一个已配置 .devcontainer 的项目目录，VS Code 会建议在容器中重新打开。
• 通过 VS Code 的终端访问文件

注意：第一次访问容器时，将进行安装和配置过程，可能需要几分钟。
注意：在容器外使用 git。虽然可以在容器内使用，但需要配置 ssh 密钥，但考虑到项目是版本化的，可以在多个工作站上克隆，因此不建议保存 git 凭据。

Docker 配置文件

• devcontainer.json 文件配置 VS Code 内的容器，启用/禁用其他扩展，以及将目录封装在容器虚拟卷中

{
	"name": "PHP",
	"build": {
		"dockerfile": "Dockerfile",
		"args": { 
			"VARIANT": "8.1",
			"NODE_VERSION": "none"
		}
	},
	"customizations": {
		"vscode": {
			"settings": { 
				"php.validate.executablePath": "/usr/local/bin/php"
			},
			"extensions": [
				"xdebug.php-debug",
				"bmewburn.vscode-intelephense-client",
				"mrmlnc.vscode-apache"
			]
		}
	},
	"forwardPorts": [8080],
	"remoteUser": "vscode"
}

• Dockerfile 文件包含容器的规格，可以在任何配置有 docker 的环境中使用，包括生产服务器。

ARG VARIANT="8.1-apache-bullseye"
FROM mcr.microsoft.com/vscode/devcontainers/php:0-${VARIANT}

ARG NODE_VERSION="none"
RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi

RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
     && apt-get -y install --no-install-recommends wget graphviz \
     && wget https://phpdoc.org/phpDocumentor.phar \
     && chmod +x phpDocumentor.phar \
     && mv phpDocumentor.phar /usr/local/bin/phpDocumentor \
     && echo xdebug.mode=coverage >> /usr/local/etc/php/conf.d/xdebug.ini 

注意：上面的容器由微软提供，包括 Linux 环境的 PHP 和 Node 安装，以及通过 Unix 命令安装的系统级别依赖项和 PHP Documentor 以及 Xdebug 的覆盖模式配置。

PHP 内置服务器

PHP 内置服务器是从 PHP 5.4 版本开始内置在特定 PHP 版本中的 Web 服务器。它允许开发人员快速启动本地开发服务器，而无需安装和配置 Apache 或 Nginx 等其他服务器。内置服务器仅应用于开发目的，不应用于生产环境。

要启动服务器，请通过终端访问公共目录并输入以下命令

php -S localhost:8888

然后通过浏览器访问 URL。

注意：请使用任何高端口，不一定要使用 8888，并避免使用 8080，因为 VS Code 会用其进行隧道。

使用 Ngrok 提供内置服务器访问

Ngrok 是一个工具，允许创建一个安全的本地服务器来测试托管在本地服务器上的应用程序和服务。它创建一个隧道，将本地服务器暴露给公网，同时保持本地 IP 和端口的隐私。它用于开发、测试、演示和其他应用。

在网站 https://ngrok.com/ 上注册，然后在启动内置服务器后，在另一个终端中输入以下命令

ngrok http 8888

注意：终端将锁定在Ngrok应用程序上，该应用程序将提供公开链接以访问您的开发环境。

Composer

什么是？

Composer是PHP的依赖项管理器。它用于管理项目的依赖项，如库、框架和其他工具。Composer允许您轻松快速地创建项目，同时保持您的代码始终最新和可访问。

访问文档

https://getcomposer.org.cn/doc/

安装

https://getcomposer.org.cn/download/

在哪里可以找到通过Composer安装的PHP包

• 官方下载存储库的网站 - https://packagist.org.cn/
• GitHub存储库，维护着多个领域的最佳和最常用的库列表 - https://gist.github.com/llbbl/7607016

如何使用Composer启动一个项目？

composer init

然后回答问题并配置您的composer.json。

您也可以手动创建composer.json文件。

主要命令

• init - 使用Composer初始化项目
• install 或 i - 安装所有依赖项
• update 或 u - 更新所有依赖项
• clear-cache - 清除Composer缓存
• dumpautoload -o - 更新autoload PSR-0和PSR-4的classpath

composer.json中存在的关键属性

• name: 使用[vendor/name]格式，指定供应商和项目名称
• description: 项目的描述
• type: 项目的类型，可以是library、project或metapackage
• version: 项目的版本，通常使用数字格式，包括大版本和小版本
• autoload: 指定用于仅使用Composer的autoload的classpath或文件
• require: 项目所有依赖项的列表
• scripts: 通过composer使用的函数、快捷方式和通用脚本的列表

注意：autoload和require具有类似的属性，具有dev后缀，其中存储了仅适用于开发环境的有效定义。要安装依赖项而不加载开发资源，请使用以下命令

composer install --no-dev

完整的composer.json文件示例

{
    "name": "senaces/sig-integration",
    "type": "project",
    "description": "SENAC | ES",
    "authors": [
        {
            "name": "Felipe Gaspar"
        }
    ],
    "autoload": {
        "psr-4": {
            "Senac\\Cron\\": "scripts/",
            "Senac\\Services\\": "src/integration/",
            "WebApp\\Platform\\Core\\Utils\\": "src/utils",
            "WebApp\\Platform\\Core\\Database\\": "src/database",
            "WebApp\\Platform\\OpenApi\\Senac\\": "src/api/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Test\\UnitTest\\": "tests/unit"
        }
    },
    "require": {
        "php": "^8",
        "symfony/yaml": "^5.3",
        "guzzlehttp/guzzle": "^7.0",
        "monolog/monolog": "^3.2",
        "symfony/mailer": "^6.1",
        "symfony/mime": "^6.1",
        "phuml/phuml": "^6.1",
        "code-simplify/ciesta-project": "^0.0.1"
    },
    "require-dev": {
        "phpunit/phpunit": "^9",
        "codeception/codeception": "^5.0",
        "codeception/module-asserts": "^3.0",
        "phpmetrics/phpmetrics": "^2.8",
        "phpunit/php-code-coverage": "^9",
        "rregeer/phpunit-coverage-check": "^0.3.1"
    },
    "scripts": {
        "clear": [
            "rm -f composer.lock",
            "@composer clear-cache"
        ],
        "code-coverage": "codecept run --coverage",
        "code-coverage-details": [
            "codecept run --coverage --coverage-html",
            "mv reports/coverage docs"
        ],
        "unit-test": "codecept run unit",
        "test-application": [
            "@code-coverage"
        ],
        "build-application": [
            "@clear",
            "@composer install",
            "@test-application"
        ],
        "doc": [
            "rm -rf docs",
            "mkdir docs",
            "mkdir docs/metrics",
            "mkdir docs/code",
            "mkdir docs/class",
            "mkdir docs/coverage",
            "vendor/bin/phpmetrics --report-html=docs/metrics src",
            "phpdoc -d src/ -t docs/code",
            "vendor/bin/phuml phuml:diagram -r -a -i -o -e php -p dot src/ docs/class/diagram.png",
            "@code-coverage-details"
        ]
    },
    "scripts-descriptions": {
        "clear": "Limpa o cache de dependências e o arquivo composer.lock",
        "code-coverage": "Executa o teste de cobertura de código com saida pelo console",
        "code-coverage-details": "Gera um relatório completo do teste de cobertura de código em formato HTML",
        "code-coverage-test": "Verifica o sucesso da cobertura de código com base em um parâmetro numérico especificado",
        "unit-test": "Executa os testes unitários utilizando o framework PHPUnit",
        "test-application": "Executa todas as rotinas de testes configuradas. OBS.: Habilite apenas as rotinas implementadas",
        "build-application": "Limpa o cache e instala as dependências, e em seguida executa todas as rotinas de testes configuradas",
        "doc": "Gera a documentação completa do projeto"
    }
}

composer.lock和vendor

composer.lock文件包含对环境所有安装的引用，包括每个库安装的版本信息，作为Composer保留指定版本的一个参考。

而vendor目录包含所有已安装库的源代码、autoload的classpath和二进制脚本。它是使用Composer的项目的基础。要使用它，只需在项目的任何文件中加载/vendor/autoload.php即可。

在版本控制期间通常不会保存这两个文件。为了便于管理，请使用.gitignore文件指定项目根目录到您想要保留在版本控制之外的任何文件和目录的路径。

创建与composer一起执行的脚本

在此示例中，我们将使用一个脚本来清理缓存和composer文件

1. 如下例所示，创建script部分

"scripts": {

},

1. 添加键"clear"，并分配一个空数组
2. 添加命令"rm -f composer.lock"，使用引号，并在末尾加上逗号。（Composer接受通过-r标志的任何Unix命令和PHP命令。例如：php -r "echo 'test';";）
3. 添加命令"@composer clear-cache"。要使用脚本中的composer命令，请使用@在composer之前引用关键字。
4. 使用以下命令测试您的脚本

composer clear

活动

创建一个名为 "build-app" 的命令，用于清理您的环境并安装所有依赖项

使用 composer 创建您的第一个库

1. 使用 composer init 创建您的 composer.json 文件
2. 在 /src 文件夹内创建一个名为 Conexao.php 的文件
3. 将以下代码复制到该文件中

<?php

namespace Treinamento\Teste;

final class Conexao {
    private array $data = [];
    public function __construct() {
        $this->data = [
            (object)[
                'titulo' => 'Exemplo 01',
                'autor' => 'Fulano',
                'corpo' => 'Foo'
            ],
            (object)[
                'titulo' => 'Exemplo 02',
                'autor' => 'Beltrano',
                'corpo' => 'Bar'
            ],
            (object)[
                'titulo' => 'Exemplo 03',
                'autor' => 'Cicrano',
                'corpo' => 'Baz'
            ]
        ];
    }

    public function lerNoticiasDoBanco() : array {
        return $this->data;
    }
}

1. 为连接类创建 PSR-4 自动加载规范

"autoload": {
    "psr-4": {
        "Treinamento\\Teste\\": "src/"
    }
}

1. 在您的 GitHub 上创建一个公共仓库。 (将 vendor name 改为您的 GitHub 账户名)
2. 将代码上传到您的 GitHub
3. 为您的项目创建一个版本和一个标签 1.0
4. 访问并登录到网站 https://packagist.org.cn/
5. 点击提交菜单并为您提供 GitHub 仓库链接以发布您的仓库
6. 在 Packagist 上发布您的仓库后，您可以在项目中将其作为依赖项插入。为此，关闭当前文件夹，创建一个新项目使用 .devcontainer 并将 Packagist 中的您的库安装命令复制到新项目中。

文档生成器

PHUML

PHUML (处理和操作 UML 模型) 是一个基于 UML (统一建模语言) 的建模工具，允许用户创建软件和系统模型。PHUML 允许用户查看、分析和操作这些模型，并提供从创建的模型生成自动代码的资源。

在上一活动创建的新项目中，添加以下开发依赖项

composer require --dev phuml/phuml ^6.1

使用以下命令生成类图。

vendor/bin/phuml phuml:diagram -r -a -o -e php -p dot examples/ docs/class/diagram.png

您可以根据需要更改源目录和目标目录。有关 PHUML 配置的更多信息，请访问 https://montealegreluis.com/phuml/docs/class-diagram.html。您可以使用仅包含方法的文档版本、仅包含属性的文档版本，或者包含或不包含关联的文档版本，并从提供的工具中选择绘图工具，如 dot 和 neato。上述建议的命令已经使用了 graphviz dot，它已安装在 .devcontainer 中。

活动

为新闻类别添加一个新类并更新类图

PHP Documentor

PHP Documentor 是一个开源代码文档工具，它为 PHP 代码生成结构化和可读的文档。PHP Documentor 用于提高生产力和简化维护，因为它有助于创建内容丰富、结构化和更新的文档。PHP Documentor 允许开发者从源代码生成 HTML、PDF、DocBook 和 man 页面。

要生成文档，请使用以下命令

phpDocumentor -d examples -t docs

请注意，文档是不完整的，并且只包含类和文件的基本信息。

使用 docblocks，它们是一组属性，可以添加到文件、类、函数和变量的定义中，以提高生成文档的质量，不仅限于生成的文件，而且通过代码中的注释进行显式。

DocBlocks

1. 文件

通常通过指定包（namespace）和文件的目的来记录文件。

/**
 * Breve descrição sobre o seu arquivo
 * @package Exemplo\Treinamento
 * @author Felipe Gaspar <felipesouzalimagaspar@gmail.com>
 */

1. 类或接口

使用简短描述和 @final 或 @abstract 标记（如果它们是抽象或最终类）来记录类。

/**
 * Classe de exemplo Foo que não serve para nada
 * @abstract
 */
abstract class Foo {

1. 函数

在函数的文档中，通常使用 @access 来定义函数的隐私级别，通过 @param 使用参数列表，通过 @return 使用返回值，如果可能抛出可预见的异常，则使用 @throws。

/**
 * Função de demonstração de docblocks
 * @access public 
 * @param string $foo Parâmetro de exemplo
 * @param array $bar Outro parâmetro
 * @throws TypeError Minha função pode disparar exceptions da classe TypeError
 * @return int Minha função sempre retornará um inteiro
 */
public function minhaFuncao(string $foo, array $bar) : int {

1. 属性

对于属性，使用 @var 结合类型和描述来记录。

/**
 * @access private
 * @var bool Minha váriavel que não serve para nada além de demonstração
 */
private bool $exemplo;

如果您有一个可能具有多种类型或您不知道类型的变量、参数或返回值，请使用 mixed。mixed 是 PHP 的基本类型，从早期版本开始允许变量更改类型。

访问PHP Documentor网站查看可用的完整docblocks列表及其使用方法。

https://docs.phpdoc.org/3.0/guide/guides/docblocks.html#more-on-docblocks

活动

现在您已经了解了docblocks和PHP Documentor，请在示例目录中的类中添加docblocks并重新生成文档。

活动

利用Composer脚本和PHP Documentor以及PHUML的知识，创建一个“composer doc”脚本来创建一个空白的docs文件夹，并使用这两个工具生成文档。

测试类型

单元测试

单元测试是验证单个代码单元的测试。它们旨在检查特定代码单元是否正确运行。这些测试是在单个代码单元上执行的，这意味着它们是独立于其余代码执行的。

集成测试

集成测试用于验证不同的代码单元是否正确交互。这些测试用于验证代码单元是否能够良好协作并产生预期的结果。

验收测试

验收测试用于验证系统是否满足用户的需求。这些测试用于验证系统是否按用户预期运行。

代码覆盖率

代码覆盖率是一种衡量已测试代码量的指标。代码覆盖率用于检查是否已充分测试了代码的所有部分。

断言

测试中的断言是声明，用于断言测试中获得的结果是否为预期。它们用于验证代码是否正确执行并产生预期结果。断言通常用诸如“结果应该等于...”或“结果应该在...之间”之类的短语表示。

PHPUnit

PHPUnit是用于PHP编程语言的单元测试框架。它提供了测试PHP应用程序以确保其质量和可靠性的工具。PHPUnit允许开发者为PHP应用程序和代码库编写和执行自动化的单元测试。PHPUnit基于xUnit构建，遵循敏捷开发原则。它是PHP中最流行的单元测试框架。

要安装PHPUnit，只需在composer.json中添加以下依赖关系

composer require --dev phpunit/phpunit ^9

配置测试套件

测试套件是一组在预定义环境中执行的测试单元。

1. 在项目根目录创建一个名为phpunix.xml的文件，并添加以下行

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="./src/vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="./tests/bootstrap.php"
         colors="true"
>
<testsuites>
    <testsuite name="Unit Test Suite">
        <directory> ./tests/unit/</directory>
    </testsuite>
</testsuites>
</phpunit>

1. 创建一个名为tests的目录，并在其中创建一个名为bootstrap.php的文件，内容如下

<?php
    require_once __DIR__ . '/../vendor/autoload.php';
    /**
    * @todo acrescente aqui outras definições base para execução dos testes 
    */

1. 在composer.json中添加以下部分

"autoload-dev": {
    "psr-4": {
        "Test\\UnitTest\\": "tests/unit"
    }
},

1. 在tests目录中创建一个名为unit的目录，并开始创建测试。

使用PHPUnit创建单元测试

在此示例中，我们将使用基本数学运算来了解PHPUnit的功能。

使用PHPUnit创建的所有测试都必须以Test后缀命名文件，并且测试方法必须以前缀test命名。

1. 创建一个名为MathTest.php的文件，并添加以下代码

<?php
    namespace Test\UnitTest;

    final class MathTest extends \PHPUnit\Framework\TestCase {
        public function testTaFuncionandoOPHPUnit(): void {
            $this->assertTrue(true);
        }
    }

1. 创建第一个测试。为此，添加一个名为testSoma的函数。测试2 + 2等于4。为此，使用接收两个参数并比较它们的assertEquals断言。

2. 让我们将之前创建的测试修改为动态的。为此，将两个数字2和数字4替换为变量$n1、$n2和$n3。

在运行测试之前，创建一个名为NumerosProvider的函数，代码如下

public function NumerosProvider() : array {
    return [
        '2+2' => [2,2,4],
        '3+3' => [3,3,6],
        '2+3' => [2,3,5]
    ];
}

在函数testSoma之前添加以下docblock

/**
 * @dataProvider NumerosProvider
 */

DataProviders是一组测试实例，可用于通过提供多个参数和预期响应来提高测试的精确度。

1. 在其类中添加以下函数

public static function setUpBeforeClass(): void {
    echo "Imagine que isso seja muito importante e tenha de ser executado antes dos testes";
}
public static function tearDownAfterClass(): void {
    echo "Imagine que isso seja muito importante e tenha de ser executado após os testes";
}

活动

搜索并实现使用PHPUnit官方文档中提供的断言的测试 https://docs.phpunit.de/en/9.Para，为此，请使用PHP的基本操作。

活动

使用Composer的autoload加载examples目录中的类，并对每个类进行单元测试。

活动

加载您创建的库，并对Conexão类进行单元测试。

活动

实现一个集成测试，使用Conexão、Autor和Notícia类。

Codeception

Codeception是一个用于PHP Web应用程序的自动化测试框架。它提供了一系列工具来帮助测试Web应用程序，从单元测试到用户接受测试。它还包含一系列库和资源，以帮助自动化测试执行。

创建测试覆盖率

1. 在composer.json中添加以下依赖项

"codeception/codeception": "^5.0",
"codeception/module-asserts": "^3.0",
"phpunit/php-code-coverage": "^9"

1. 在项目根目录创建一个名为codeception.yml的文件，并粘贴以下代码

paths:
    tests: tests
    output: reports
    data: reports
    support: tests/.codeception
    envs: tests/_envs
bootstrap: bootstrap.php
settings:
    suite_class: \PHPUnit_Framework_TestSuite
    memory_limit: 1024M
    log: true
    colors: true
actor_suffix: Tester
extensions:
    enabled:
        - Codeception\Extension\RunFailed
coverage:
    enabled: true
    include:
        - examples/*
    exclude: 
        - examples/*log
    low_limit: 50
    high_limit: 90
    show_only_summary: false
    show_uncovered: true

1. 将codeception.zip文件解压到tests文件夹内
2. 执行以下命令以运行测试覆盖率

vendor/bin/codecept run --coverage

如果您想以图形模式生成报告，请使用以下命令

vendor/bin/codecept run --coverage --coverage-html

创建接受测试

1. 使用PHP内置服务器，将view文件夹的内容在8888端口上提供
2. 在/tests目录下创建一个名为acceptance的文件夹
3. 安装以下依赖项

"codeception/module-phpbrowser": "^3.0"

1. 将以下代码复制到您将在acceptance目录中创建的FirstCest.php文件中

<?php
class FirstCest
{
    public function frontpageWorks(AcceptanceTester $I)
    {
        $I->amOnPage('/');
        $I->see('Exemplo');
    }

    public function viewpageWorks(AcceptanceTester $I)
    {
        $I->amOnPage('/view.php?url=exemplo-01');
        $I->see('Foo');
    }
}

活动

实现一个使用任何在线表单和文档中提供的可用方法的表单测试