fundraising-application

维基媒体德国筹款的面向用户的应用程序。

安装
运行应用程序
配置
运行测试、代码风格检查和静态分析
电子邮件
数据库
前端开发
更新依赖项
部署
项目结构
另请参阅

安装

首次设置

对于开发，您需要安装Docker和docker-compose。您至少需要Docker版本 >= 17.09.0和docker-compose版本 >= 1.17.0。如果您的操作系统没有附带正确的版本，请使用Docker和docker-compose的官方安装说明。您不需要在计算机上安装其他依赖项（PHP、Node.js、MariaDB）。

获取我们git仓库的克隆，然后运行：

make setup

这将

安装PHP依赖项
复制基本配置文件。有关配置的更多详细信息，请参阅配置部分。
生成Doctrine代理类
从fundraising-app-frontend下载并安装前端资产

安装当前依赖项

make install-php

将安装当前在composer.lock中指定的依赖项。每当您检出一个对composer.lock有更改的分支时，请使用此命令。

运行应用程序

命令

make up-app

将在Docker容器中运行应用程序。您可以在http://localhost:8082/访问它。

要停止应用程序，请运行

make down-app

不使用Makefile运行

up-app任务还将确保您的本地配置正确，并停止应用程序的先前实例。您可以使用以下命令在前台运行应用程序，而无需使用Makefile：

docker-compose up

配置

应用程序的Web和CLI入口点会检查APP_ENV环境变量。如果未设置，应用程序假定值为dev。每个环境必须在app/config中有一个相应的配置文件，遵循config.ENVIRONMENTNAME.json的命名模式。请参阅下面的"在不同环境中运行"部分，了解如何设置APP_ENV。运行命令make default-config将自动设置配置文件。

您可以通过添加遵循config.ENVIRONMENTNAME.local.json命名模式的文件来添加本地修改。

应用程序将配置文件中的值与文件app/config/config.dist.json中的默认值合并。

.env文件

它们主要包含凭据。Symfony需要这些文件，并将根据APP_ENV环境变量选择文件。

.env：为所有环境设置默认值，被以下所有文件覆盖。
.env.dev：为开发环境设置默认值
.env.test：为单元测试环境设置默认值
.env.dev.local：覆盖所有环境的默认值。请参阅下面的支付部分。

.env.dev和.env.test包含默认值，不应包含实际凭据。如果您想覆盖凭据，请创建文件.env.dev.local。不要将其检入版本控制！

当我们使用部署脚本部署应用程序时，部署脚本将创建一个名为.env的文件，其中包含生产环境的配置数据。

前端开发

如果您想处理应用程序的客户端代码，您需要从不同的源加载它，例如在端口7072上运行的fundraising-app-frontend开发服务器。配置中有一个设置assets-path，您可以将其指向不同的路径甚至URL。

以下设置将使您的应用程序指向前端开发服务器：

"assets-path": "http://localhost:7072"

如果浏览器找不到资产，应用程序将显示一条消息。

创建使用MariaDB数据库的测试配置

为了在本地运行测试时加快速度，测试使用SQLite而不是MariaDB。要使用真实数据库运行测试，请添加文件app/config/config.test.local.json，内容如下：

{
    "db": {
        "driver": "pdo_mysql",
        "user": "fundraising",
        "password": "INSECURE PASSWORD",
        "dbname": "fundraising",
        "host": "database",
        "port": 3306
    }
}

支付

要获得具有所有支付类型和工作模板的完全工作实例，您需要在app/config/config.dev.json中填写以下配置数据：

"operator-email"
"operator-displayname-organization"
"operator-displayname-suborganization"
"paypal-donation"
"paypal-membership"
"creditcard"

要能够访问PayPal页面进行支付，您还需要在.env.dev.local文件中填写PayPal凭据。 .env.dev.local文件将覆盖.env.dev中给出的示例数据。有关PayPal配置条目的说明，请参阅.env.dev文件。

内容

应用程序需要https://github.com/wmde/fundraising-frontend-content的内容仓库副本才能正常工作。在开发中，内容仓库是一个composer dev-dependency。如果您想要将内容仓库放在其他地方，您需要配置i18n-base-path以指向它。以下示例显示了当内容仓库与应用程序目录在同一级别时的配置：

"i18n-base-path": "../fundraising-frontend-content/i18n"

A/B测试活动

有关如何设置活动的更多信息，请参阅"如何创建A/B测试"。

活动定义位于app/config目录中。您可以通过编辑app/config/config.ENVIRONMENTNAME.json中的campaigns值来告诉应用程序使用哪些文件。应用程序将按顺序合并活动配置文件。

在不同环境中运行

默认情况下，配置环境为dev，配置文件为config.dev.json。如果您想更改，必须将环境变量传递给make、docker和docker-compose命令。

make ci APP_ENV=prod

对于docker-compose，您可以在应用程序目录中创建一个名为.env的文件，内容如下：

APP_ENV=prod

如果您想覆盖.env文件中的默认值，可以在shell中设置变量，如下所示：

export APP_ENV=prod

如果您运行单个docker容器，可以使用-e标志传递变量：

docker run -e APP_ENV=prod php some_script.php

有效的环境名称是

dev - 开发环境，主要用于本地开发
test - 单元测试环境
uat - 用户验收测试
prod - 生产

**注意：**无论APP_ENV如何设置，PHPUnit测试始终在test环境配置下运行！

运行测试、代码风格检查和静态分析

运行所有检查

make ci

这将运行测试、检查代码风格、进行静态分析并检查配置文件。

仅运行测试

make test

如果您想运行特定的测试文件夹或仅运行一个文件，请使用TEST_DIR参数。示例：

# 运行单元测试
make phpunit TEST_DIR=tests/Unit

# 运行特定的测试文件
make phpunit TEST_DIR=tests/EdgeToEdge/Routes/AddDonationRouteTest.php

仅运行代码风格检查

make cs

如果您想修复代码风格违规，请运行

make fix-cs

静态分析

我们在运行make ci期间使用PHPStan进行静态代码分析。

在没有dev-dependencies的情况下（即模拟生产环境的vendor/代码），您可以使用以下命令运行PHPStan

docker build -t wmde/fundraising-frontend-phpstan build/phpstan
docker run -v $PWD:/app --rm wmde/fundraising-frontend-phpstan analyse -c phpstan.neon --level 1 --no-progress cli/ contexts/ src/

这些任务也在DroneCI运行期间执行。

电子邮件

在开发环境中，我们使用mailhog捕获应用程序发送的所有电子邮件。您可以在http://localhost:8025/访问mailhog Web界面

您可以在电子邮件模板文档中找到有关如何测试电子邮件模板以及如何在不使用应用程序的情况下渲染它们的更多信息。

数据库

在本地环境中重置数据库

要从头开始重新构建数据库，您需要停止数据库容器，删除docker-compose.yml中定义的卷db-storage，然后重新启动数据库容器。

您可以使用以下命令关闭所有容器并删除所有卷：

docker-compose down -v

下次运行make up-app时，数据库容器将处理.docker/database中的所有SQL文件。

使用命令行客户端访问数据库

要启动命令行客户端，请使用以下命令：

docker-compose up -d database
docker-compose exec database mysql -u fundraising -p"INSECURE PASSWORD" fundraising

从主机机器访问数据库

如果您想使用不同的客户端访问数据库，需要连接到端口3307。

数据库迁移

开箱即用，数据库应该处于可用于本地开发的状态。

如果您对数据库架构进行了更改，您需要做两件事：

为生产数据库创建一个Doctrine迁移脚本。将迁移脚本存储在您进行更改的有界上下文的migrations目录中。
在您的开发环境中，使用make generate-database-schema命令创建新的数据库架构定义。这将刷新文件./docker/database/01_Database_Schema.sql。然后重新启动容器环境，同时删除数据库卷。请参阅上面的"在本地环境中重置数据库"部分。

迁移CLI和配置

迁移的配置文件位于app/config/migrations.php中

bin/doctrine CLI命令附带了为筹款应用程序预配置的迁移命令。无论Doctrine迁移文档中提到运行命令vendor/bin/doctrine-migrations，请使用命令bin/doctrine代替。例如bin/doctrine migrations:status。

在基于Docker的开发环境中，使用docker-compose exec在app容器中运行命令。容器环境必须正在运行才能使其工作。示例：

docker-compose exec app bin/doctrine migrations:status

在服务器上运行迁移

有关如何在服务器上运行迁移，请查看部署文档。

**注意：**如果您收到找不到配置文件的错误，请确保将APP_ENV设置为正确的值。请参阅本文档中的"在不同环境中运行"部分。

从Docker镜像访问数据库

如果您想从不属于docker-compose.yml配置的另一个docker容器连接到数据库容器（例如使用Adminer或PHPMyAdmin等工具），您我们计划使用GitHub fundraising-app-frontend中最新版本的资源,但这需要扩展我们的基础设施。

使用实时资源进行开发

如果你想从不同的源加载资源,例如在7072端口运行的fundraising-app-frontend开发服务器,你需要在config.dev.json文件中添加以下行:

"assets-path": "http://localhost:7072"

HTML模板会在每个资源(CSS,JavaScript)引用前加上assets-path的值。

更新依赖

要更新所有PHP依赖,运行

make update-php

要只更新应用程序和邮件中的消息,使用以下命令更新fundraising-frontend-content依赖:

make update-content

要更新单个PHP依赖,使用命令行

docker run --rm -it -v $(pwd):/app -u $(id -u):$(id -g) registry.gitlab.com/fun-tech/fundraising-frontend-docker:composer composer update PACKAGE_NAME

将PACKAGE_NAME替换为你的包名。

部署

有关如何在我们的服务器上部署应用程序的详细文档,请参阅部署文档。

故障排除

缓存

容器中的CLI命令和PHP-FPM进程共享容器内的同一缓存位置 - /tmp/symfony。运行CLI命令时,文件所有者将是root:root。这将阻止PHP-FPM进程写入缓存。如果你在浏览器中遇到缓存相关错误,在docker-compose环境运行时执行以下命令:

make clear

该命令将删除app容器内的所有缓存文件。运行命令后,请确保先访问网站,然后再运行其他CLI命令。

项目结构

本应用及其使用的限界上下文遵循Clean Architecture + Bounded Contexts中概述的架构规则。

架构图

使用的限界上下文:

生产代码布局

src/: 不属于任何限界上下文的代码,尽可能与框架无关
- Factories/: 框架使用的应用程序工厂,包括顶级工厂FFFactory
- Presentation/: 展示代码,包括Presenters/
- Validation/: 验证代码
vendor/wmde/$ContextName/src/: 属于特定限界上下文的与框架无关的代码
- Domain/: 领域模型和领域服务
- UseCases/: 每个用例一个目录
- DataAccess/: 绑定到数据库、网络等的服务实现
- Infrastructure/: 绑定到横切关注点的服务实现,如日志记录
web/: 可通过网络访问的代码
- index.php: HTTP入口点
- skins: 不同皮肤的资源文件(CSS、JavaScript、图像、字体)
app/: 包含应用程序特定配置和所有框架(Symfony)相关代码
- Controllers/: Symfony控制器
- EventHandlers: 在HTTP请求处理前后执行任务的"中间件"代码
- config/: 配置文件
  - config.dist.json: 默认配置
  - config.test.json: 集成和系统测试使用的配置(合并到默认配置中)
  - config.test.local.json: 实例特定(gitignored)测试配置(合并到config.test.json中)
  - config.development.json: 实例特定(gitignored)生产配置(合并到默认配置中)
config/: Symfony配置文件
cli/: 命令行命令,集成到Symfony控制台中
var/: 临时应用程序数据
- log/: 日志文件(在调试模式下,每个请求都会创建一个日志文件)
- cache/: Twig模板和Symfony DI容器的缓存目录

测试代码布局

测试目录结构(和命名空间结构)镜像生产代码。src/和app/中代码的测试在tests/中。

测试按类型分类。要仅运行给定类型的测试,你可以使用phpunit.xml.dist中定义的测试套件之一。

Unit/: 小型隔离测试(一个类或少量相关类)
Integration/: 结合多个单元的测试
EdgeToEdge/: 边缘到边缘测试(对框架的伪HTTP请求)
System/: 涉及外部系统的测试(即超出我们的PHP应用和数据库)
Fixtures/: 测试替身(存根、间谍和模拟)

如果你在非单元测试中需要访问FunFunFactory,例如与持久化交互,你应该继承KernelTestCase并从容器中获取Factory。

测试类型限制

<table> <tr> <th></th> <th>网络</th> <th>框架(Symfony)</th> <th>顶级工厂</th> <th>数据库和磁盘</th> </tr> <tr> <th>单元</th> <td>否</td> <td>否</td> <td>否</td> <td>否</td> </tr> <tr> <th>集成</th> <td>否</td> <td>否</td> <td>不鼓励</td> <td>是</td> </tr> <tr> <th>边缘到边缘</th> <td>否</td> <td>是</td> <td>是</td> <td>是</td> </tr> <tr> <th>系统</th> <td>是</td> <td>是</td> <td>是</td> <td>是</td> </tr> </table>