如何成为 QueryPHP 开发者

Testing Is Documentation

tests/Docs/BecomeAQueryphpDeveloperDoc.php开发者 - 图1

QueryPHP 非常欢迎各位给我们共同的充满想象且令人惊叹的完成度的开源作品添砖加瓦，实现为 PHP 社区提供一个好框架的美好愿景。

成为开发者需要加入我们的组织，如有相关意愿请发送邮件至 小牛哥 <635750556@qq.com>，我们会联系你的。

成为开发者并没有什么任务负担，一切主要以你的意愿，兴趣才是最重要的。

本篇指南将带你搭建的 QueryPHP 开发框架的开发环境，使得你可以参与 QueryPHP 底层代码、单元测试和文档等开发工作。

这里以笔者的 Mac 为例子说明，其实 Windows 下面还更简单些。

克隆 queryphp 仓库

QueryPHP 框架的开发来自于从克隆主仓库开始，由于国内访问 Github 网速的问题，只需要等待一小段时间。

下载代码

  1. $cd /data/codes/test
  2. $git clone git@github.com:hunzhiwange/queryphp.git

Composer 安装

  1. composer install

如果你电脑没有安装 composer，那么已经为你下载一个版本。

  1. sudo chmod 777 ./build/composer
  2. ./build/composer install

安装过程

  1. Cloning into 'queryphp'...
  2. remote: Enumerating objects: 54, done.
  3. remote: Counting objects: 100% (54/54), done.
  4. remote: Compressing objects: 100% (39/39), done.
  5. remote: Total 17821 (delta 19), reused 36 (delta 14), pack-reused 17767
  6. Receiving objects: 100% (17821/17821), 45.12 MiB | 693.00 KiB/s, done.
  7. Resolving deltas: 100% (8700/8700), done.

测试是否安装成功

如果可以访问，那么恭喜你第一阶段即安装完毕。

  1. php leevel server <Visite http://127.0.0.1:9527/>

搭建后台 API 端

首先我们需要创建一个数据库来运行我们的后台，让我们对 QueryPHP 有一个直观的感受，同时方便后期开发调试等。

首先创建一个数据库

可以用 Navicat For Mysql 创建一个数据库 queryphp_development_db.

  1. CREATE DATABASE IF NOT EXISTS queryphp_development_db DEFAULT CHARSET utf8 COLLATE utf8_general_ci;

修改 .env

  1. ...
  2. // Database
  3. DATABASE_DRIVER = mysql
  4. DATABASE_HOST = 127.0.0.1
  5. DATABASE_PORT = 3306
  6. DATABASE_NAME = queryphp_development_db
  7. DATABASE_USER = root
  8. DATABASE_PASSWORD =
  9. ...
  11. 修改为
  13. ...
  14. // Database
  15. DATABASE_DRIVER = mysql
  16. DATABASE_HOST = 127.0.0.1
  17. DATABASE_PORT = 3306
  18. DATABASE_NAME = queryphp_development_db
  19. DATABASE_USER = root
  20. DATABASE_PASSWORD = 123456
  21. ...

执行数据库迁移命令

  1. php leevel migrate:migrate

安装过程

  1. using config file ./phinx.php
  2. using config parser php
  3. using migration paths
  4. - /data/codes/test/queryphp/database/migrations
  5. using seed paths
  6. - /data/codes/test/queryphp/database/seeds
  7. warning no environment specified, defaulting to: development
  8. using adapter mysql
  9. using database queryphp_development_db
  11. == 20181109060739 App: migrating
  12. == 20181109060739 App: migrated 0.0155s
  14. == 20181112023649 Role: migrating
  15. == 20181112023649 Role: migrated 0.0160s
  17. == 20181112024140 User: migrating
  18. == 20181112024140 User: migrated 0.0166s
  20. == 20181112024211 Permission: migrating
  21. == 20181112024211 Permission: migrated 0.0225s
  23. == 20181112024241 UserRole: migrating
  24. == 20181112024241 UserRole: migrated 0.0155s
  26. == 20181112024302 RolePermission: migrating
  27. == 20181112024302 RolePermission: migrated 0.0206s
  29. == 20181112024416 Resource: migrating
  30. == 20181112024416 Resource: migrated 0.0328s
  32. == 20181112024450 PermissionResource: migrating
  33. == 20181112024450 PermissionResource: migrated 0.0305s
  35. == 20181203130724 Option: migrating
  36. == 20181203130724 Option: migrated 0.0170s
  38. == 20181203144731 Test: migrating
  39. == 20181203144731 Test: migrated 0.0133s
  41. All Done. Took 0.2273s

测试数据库是否正常

  1. php leevel server <http://127.0.0.1:9527/api/entity>

结果

  1. {
  2.     count: 4,
  3.     :trace: {
  4.         ...
  5.     }
  6. }

搭建前端

后台 API 搭建好了，我们开始搭建前端了，前端基于 Vue-cli 3 和 IView，首先需要安装 node 才能够跑起来。

对于开发 QueryPHP 来说，你不需要会 Vue 或者 JavaScript，所以请放心不要有心里负担。

安装前端

第一步安装前端,细节信息可以在 frontend/README.md 查看.

  1. cd frontend
  2. npm install -g cnpm --registry=https://registry.npm.taobao.org // Just once
  3. cnpm install

安装过程

  1. ✔ All packages installed (1264 packages installed from npm registry, used 14s(network 13s), speed 221.08kB/s, json 1086(2.23MB), tarball 501.92kB)

运行前端

接着访问这个登陆地址.

  1. npm run serve # npm run dev <http://127.0.0.1:9528/#/login>

输入登陆用户名和密码,这个时候 QueryPHP 不再是一个冰冷的代码，而是有一个干净的带有基础权限系统的后台。

  1. user: admin
  2. password: 123456

运行测试用例

QueryPHP 推崇通过编写测试用例来让代码变得可维护，所以这里需要本地开发跑通测试用例。

首先创建一个数据库

可以用 Navicat For Mysql 创建一个数据库 queryphp_development_test.

  1. CREATE DATABASE IF NOT EXISTS queryphp_development_test DEFAULT CHARSET utf8 COLLATE utf8_general_ci;

修改 .env

  1. ...
  2. // Database
  3. DATABASE_DRIVER = mysql
  4. DATABASE_HOST = 127.0.0.1
  5. DATABASE_PORT = 3306
  6. DATABASE_NAME = test
  7. DATABASE_USER = root
  8. DATABASE_PASSWORD =
  9. ...
  11. 修改为
  13. ...
  14. // Database
  15. DATABASE_DRIVER = mysql
  16. DATABASE_HOST = 127.0.0.1
  17. DATABASE_PORT = 3306
  18. DATABASE_NAME = queryphp_development_test
  19. DATABASE_USER = root
  20. DATABASE_PASSWORD = 123456
  21. ...

执行数据库迁移命令

  1. php leevel migrate:migrate -e testing

安装过程

  1. using config file ./phinx.php
  2. using config parser php
  3. using migration paths
  4. - /data/codes/test/queryphp/database/migrations
  5. using seed paths
  6. - /data/codes/test/queryphp/database/seeds
  7. using environment testing
  8. using adapter mysql
  9. using database queryphp_development_test
  11. == 20181109060739 App: migrating
  12. == 20181109060739 App: migrated 0.0155s
  14. == 20181112023649 Role: migrating
  15. == 20181112023649 Role: migrated 0.0160s
  17. == 20181112024140 User: migrating
  18. == 20181112024140 User: migrated 0.0166s
  20. == 20181112024211 Permission: migrating
  21. == 20181112024211 Permission: migrated 0.0225s
  23. == 20181112024241 UserRole: migrating
  24. == 20181112024241 UserRole: migrated 0.0155s
  26. == 20181112024302 RolePermission: migrating
  27. == 20181112024302 RolePermission: migrated 0.0206s
  29. == 20181112024416 Resource: migrating
  30. == 20181112024416 Resource: migrated 0.0328s
  32. == 20181112024450 PermissionResource: migrating
  33. == 20181112024450 PermissionResource: migrated 0.0305s
  35. == 20181203130724 Option: migrating
  36. == 20181203130724 Option: migrated 0.0170s
  38. == 20181203144731 Test: migrating
  39. == 20181203144731 Test: migrated 0.0133s
  41. All Done. Took 0.2273s

运行测试用例

  1. php ./build/phpunit

结果

注意随着系统演进，测试用例会增加，输出结果就有所不同。

  1. PHPUnit Pretty Result Printer 0.26.2 by Codedungeon and contributors.
  2. PHPUnit 8.1.3 by Sebastian Bergmann and contributors.
  5. ==> Tests\Admin\Service\Resource\IndexTest       ✓  ✓
  6. ==> Tests\Example\ExampleTest                    ✓
  7. ==> Tests\Example\PHPUnitTest                    ✓
  8. ==> Common\Domain\Service\Search\IndexTest       ✓  ✓  ✓  ✓  ✓  ✓
  9. ==> Common\Infra\Helper\ArrayToFormTest          ✓  ✓  ✓  ✓  ✓  ✓
  10. ==> Common\Infra\Support\WorkflowServiceTest     ✓  ✓  ✓  ✓  ✓
  11. ==> Common\Infra\Support\WorkflowTest            ✓  ✓  ✓  ✓  ✓
  13. Time: 391 ms, Memory: 18.00 MB
  15. OK (26 tests, 43 assertions)

统一团队代码风格

风格统一对保证我们系统一致性非常重要，我们做到开箱即用，支持 PHP 和 JavaScript。

使用 Git 钩子

  1. cp ./build/pre-commit.sh ./.git/hooks/pre-commit
  2. chmod 777 ./.git/hooks/pre-commit

测试自动化格式

common/Test.php

  1. <?php
  3. declare(strict_types=1);
  5. namespace Common;
  7. class Test{
  8.     public function demo($a=1, $b=4){
  9.         echo 1;
  10.     }
  11. }

frontend/src/hello.js

  1. function hello(a,b) {
  2.     var c
  3.         if(a>b) {
  4.             c=a
  5.         } else {
  6.             c=b
  7.         }
  8.     console.log(c)
  9. }

Git 提交测试格式化

  1. git add .
  2. git commit -m '测试格式化'

运行过程

  1. Checking PHP Lint...
  2. No syntax errors detected in common/Test.php
  3. Running Code Sniffer...
  4. Loaded config default from ".php_cs.dist".
  5. Paths from configuration file have been overridden by paths provided as command arguments.
  6. 1) common/Test.php Fixed all files in 0.009 seconds, 12.000 MB memory used
  7. The file has been automatically formatted.
  8. [13:04:00] Working directory changed to /data/codes/test/queryphp/frontend
  9. [13:04:00] Using gulpfile /data/codes/test/queryphp/frontend/gulpfile.js
  10. [13:04:00] Starting 'iview'...
  11. [13:04:00] Finished 'iview' after 413 μs
  12. frontend/src/hello.js 53ms
  13. [master 681d7e29] 测试格式化
  14. 3 files changed, 32 insertions(+)
  15. mode change 100644 => 100755 build/composer
  16. create mode 100644 common/Test.php
  17. create mode 100644 frontend/src/hello.js

格式化后的 PHP

代码干净漂亮了不少，不是吗。

  1. <?php
  3. declare(strict_types=1);
  5. /*
  6.  * This file is part of the your app package.
  7.  *
  8.  * The PHP Application For Code Poem For You.
  9.  * (c) 2018-2099 http://yourdomian.com All rights reserved.
  10.  *
  11.  * For the full copyright and license information, please view the LICENSE
  12.  * file that was distributed with this source code.
  13.  */
  15. namespace Common;
  17. class Test
  18. {
  19.     public function demo($a = 1, $b = 4)
  20.     {
  21.         echo 1;
  22.     }
  23. }

格式化后的 JavaScript

代码干净漂亮了不少，不是吗。

  1. function hello(a, b) {
  2.     var c
  3.     if (a > b) {
  4.         c = a
  5.     } else {
  6.         c = b
  7.     }
  8.     console.log(c)
  9. }

回滚测试提交

这些测试代码不需要提交到 Git 库，你可以回滚掉刚才测试的这些代码。

  1. git log
  2. git reset --hard 931f283b0b8847e4a3f2ad86efb3c07cd7974c3b // 或者 git revert xxx
  3. HEAD is now at 931f283b Merge branch 'dev'

克隆 framework 仓库将框架替换为开发版本

应用层框架全部搭建完毕，接下来我们将框架层代码替换为开发阶段的代码来进行日常框架迭代。

删除框架层

  1. rm -rf ./vendor/hunzhiwange/framework

克隆框架层开发库

  1. $cd /data/codes/test
  2. $git clone git@github.com:hunzhiwange/framework.git ./vendor/hunzhiwange/framework
  3. cd ./vendor/hunzhiwange/framework

Composer 安装

  1. composer install

如果你电脑没有安装 composer，那么已经为你下载一个版本。

  1. sudo chmod 777 ./build/composer
  2. ./build/composer install

安装过程

  1. Cloning into './vendor/hunzhiwange/framework'...
  2. remote: Enumerating objects: 382, done.
  3. remote: Counting objects: 100% (382/382), done.
  4. remote: Compressing objects: 100% (218/218), done.
  5. remote: Total 39304 (delta 196), reused 262 (delta 125), pack-reused 38922
  6. Receiving objects: 100% (39304/39304), 14.49 MiB | 12.00 KiB/s, done.
  7. Resolving deltas: 100% (27594/27594), done.

测试是否安装成功

从新访问首页，如果可以访问，那么恭喜你第一阶段即安装完毕。

  1. php leevel server <Visite http://127.0.0.1:9527/>

运行框架核心测试用例

QueryPHP 底层框架拥有 3000 多例测试用例，这些测试用例需要被维护，所以这里需要本地开发跑通测试用例。

首先创建一个数据库

可以用 Navicat For Mysql 创建一个数据库 test.

  1. CREATE DATABASE IF NOT EXISTS test DEFAULT CHARSET utf8 COLLATE utf8_general_ci;

复制一份配置文件并修改

  1. cp ./tests/config.php ./tests/config.local.php

修改为

  1. <?php
  3. $GLOBALS['LEEVEL_ENV']['DATABASE']['MYSQL'] = [
  4.     'HOST'     => '127.0.0.1',
  5.     'PORT'     => 3306,
  6.     'NAME'     => 'test',
  7.     'USER'     => 'root',
  8.     'PASSWORD' => '123456',
  9. ];
  11. $GLOBALS['LEEVEL_ENV']['CACHE']['REDIS'] = [
  12.     'HOST'     => '127.0.0.1',
  13.     'PORT'     => 6380,
  14.     'PASSWORD' => '123456',
  15. ];
  17. $GLOBALS['LEEVEL_ENV']['SESSION']['REDIS'] = [
  18.     'HOST'     => '127.0.0.1',
  19.     'PORT'     => 6380,
  20.     'PASSWORD' => '123456',
  21. ];

执行数据库迁移命令

  1. php vendor/bin/phinx migrate

安装过程

  1. Phinx by CakePHP - https://phinx.org. 0.9.2
  3. using config file ./phinx.php
  4. using config parser php
  5. using migration paths
  6.  - /data/codes/test/queryphp/vendor/hunzhiwange/framework/tests/assert/database/migrations
  7. using seed paths
  8.  - /data/codes/test/queryphp/vendor/hunzhiwange/framework/tests/assert/database/seeds
  9. warning no environment specified, defaulting to: development
  10. using adapter mysql
  11. using database test
  13.  == 20181010111946 User: migrating
  14.  == 20181010111946 User: migrated 0.0076s
  16.  == 20181011111926 Post: migrating
  17.  == 20181011111926 Post: migrated 0.0101s
  19.  == 20181011111937 Comment: migrating
  20.  == 20181011111937 Comment: migrated 0.0106s
  22.  == 20181011151247 PostContent: migrating
  23.  == 20181011151247 PostContent: migrated 0.0087s
  25.  == 20181011160957 Role: migrating
  26.  == 20181011160957 Role: migrated 0.0078s
  28.  == 20181011161035 UserRole: migrating
  29.  == 20181011161035 UserRole: migrated 0.0100s
  31.  == 20181031094608 CompositeId: migrating
  32.  == 20181031094608 CompositeId: migrated 0.0094s
  34.  == 20181107044153 GuestBook: migrating
  35.  == 20181107044153 GuestBook: migrated 0.0086s
  37.  == 20190424055915 TestUnique: migrating
  38.  == 20190424055915 TestUnique: migrated 0.0133s
  40. All Done. Took 0.1179s

运行测试用例

  1. php ./build/phpunit

结果

注意随着系统演进，测试用例会增加，输出结果就有所不同。

  1. PHPUnit 8.1.3 by Sebastian Bergmann and contributors.
  4. ==> Tests\Auth\HashTest                          ✓  ✓
  5. ==> Tests\Auth\ManagerTest                       ✓  ✓  ✓
  6. ==> Tests\Auth\Middleware\AuthTest               ✓  ✓
  7. ==> Tests\Auth\Provider\RegisterTest             ✓
  8. ==> Tests\Auth\SessionTest                       ✓  ✓
  10. ...
  12. ==> Tests\View\Compiler\CompilerWhileTest        ✓  ✓
  13. ==> Tests\View\HtmlTest                          ✓  ✓  ✓  ✓  ✓  ✓  ✓  ✓  ✓
  14. ==> Tests\View\ManagerTest                       ✓
  15. ==> Tests\View\PhpuiTest                         ✓  ✓  ✓  ✓  ✓  ✓  ✓  ✓
  16. ==> Tests\View\Provider\RegisterTest             ✓
  18. Time: 19.51 seconds, Memory: 93.19 MB
  20. Tests: 2978, Assertions: 10031, Failures: 0, Skipped: 6.

统一框架核心团队代码风格

风格统一对保证我们系统一致性非常重要，我们做到开箱即用，核心库只包含 PHP 文件。

使用 Git 钩子

  1. cp ./build/pre-commit.sh ./.git/hooks/pre-commit
  2. chmod 777 ./.git/hooks/pre-commit

测试自动化格式

tests/Name.php

  1. <?php
  3. declare(strict_types=1);
  5. namespace Test;
  7. class Name{
  8.     public function demo($a=1, $b=4){
  9.         echo 1;
  10.     }
  11. }

Git 提交测试格式化

  1. git add .
  2. git commit -m '测试格式化'

运行过程

  1. Checking PHP Lint...
  2. No syntax errors detected in tests/Name.php
  3. Running Code Sniffer...
  4. Loaded config default from ".php_cs.dist".
  5. Paths from configuration file have been overridden by paths provided as command arguments.
  6. 1) tests/Name.php Fixed all files in 0.009 seconds, 12.000 MB memory used
  7. The file has been automatically formatted.
  8. [master 20f2f845] 测试格式化
  9. 2 files changed, 29 insertions(+)
  10. mode change 100644 => 100755 build/composer
  11. create mode 100644 tests/Name.php

格式化后的 PHP

代码干净漂亮了不少，不是吗。

测试代码回滚请见上面的方法，谢谢。

  1. <?php
  3. declare(strict_types=1);
  5. /*
  6.  * This file is part of the ************************ package.
  7.  * _____________                           _______________
  8.  *  ______/     \__  _____  ____  ______  / /_  _________
  9.  *   ____/ __   / / / / _ \/ __`\/ / __ \/ __ \/ __ \___
  10.  *    __/ / /  / /_/ /  __/ /  \  / /_/ / / / / /_/ /__
  11.  *      \_\ \_/\____/\___/_/   / / .___/_/ /_/ .___/
  12.  *         \_\                /_/_/         /_/
  13.  *
  14.  * The PHP Framework For Code Poem As Free As Wind. <Query Yet Simple>
  15.  * (c) 2010-2020 http://queryphp.com All rights reserved.
  16.  *
  17.  * For the full copyright and license information, please view the LICENSE
  18.  * file that was distributed with this source code.
  19.  */
  21. namespace Test;
  23. class Name
  24. {
  25.     public function demo($a = 1, $b = 4)
  26.     {
  27.         echo 1;
  28.     }
  29. }

克隆 queryphp.com 仓库实现自动化文档搭建

QueryPHP 底层的文档基于单元测试加备注的方式来实现的，通过命名工具全部采用自动化生成 Markdown，这大幅度简化了文档的编写工作，同时保证了文档实时性。

官方文档采用 VuePress 读取 Markdown 来实现的

  1. $cd /data/codes/test
  2. $git clone git@github.com:hunzhiwange/queryphp.com.git

修改文档工具生成 Markdown 的路径

  1. $cd /data/codes/test/queryphp
  2. $vim .env
  4. # 修改路径
  5. FRAMEWORK_DOC_OUTPUTDIR = "/data/codes/test/queryphp.com/docs/docs/"

生成文档

  1. $cd /data/codes/test/queryphp
  2. $php leevel make:docwithin tests

运行过程

  1. Class Tests\Encryption\EncryptionTest was generate succeed.
  2. Class Tests\Encryption\HelperTest was generate succeed.
  3. Class Tests\Database\ManagerTest was generate succeed.
  4. Class Tests\Database\Ddd\UnitOfWorkTest was generate succeed.
  5. Class Tests\Database\Ddd\Create\CreateTest was generate succeed.
  6. Class Tests\Database\Query\AggregateTest was generate succeed.
  7. Class Tests\Validate\AssertTest was generate succeed.
  8. Class Tests\Di\ContainerTest was generate succeed.
  9. Class Tests\Docs\BecomeAQueryphpDeveloperDoc was generate succeed.
  10. Class Tests\Support\FnTest was generate succeed.
  11. Class Tests\Support\StrTest was generate succeed.
  12. Class Tests\Support\ArrTest was generate succeed.
  13. Class Tests\View\SummaryDoc was generate succeed.
  14. Class Tests\View\Compiler\CompilerAssignTest was generate succeed.
  15. Class Tests\View\Compiler\CompilerPhpTest was generate succeed.
  16. Class Tests\View\Compiler\CompilerBreakTest was generate succeed.
  17. Class Tests\View\Compiler\CompilerIncludeTest was generate succeed.
  18. Class Tests\View\Compiler\CompilerTagselfTest was generate succeed.
  19. Class Tests\View\Compiler\CompilerWhileTest was generate succeed.
  20. Class Tests\View\Compiler\CompilerCssTest was generate succeed.
  21. Class Tests\View\Compiler\CompilerForTest was generate succeed.
  22. Class Tests\View\Compiler\CompilerVarTest was generate succeed.
  23. Class Tests\View\Compiler\CompilerListTest was generate succeed.
  24. Class Tests\Debug\DebugTest was generate succeed.
  25. A total of 24 files generate succeed.

修改文档菜单

  1. $vim docs/.vuepress/config.js

运行本地文档网站

访问地址 localhost:8088 即可。

  1. $npm install -g yarn
  2. $yarn add -D vuepress # or npm install -D vuepress
  3. $yarn run dev # or npx vuepress dev docs

结尾

到这里为止，我们本地开发环境已经全部搭建完毕，可以愉快地开发了。

TIP

值得注意的是，我们通常在 dev 分支开发，开发完毕后 merge 到 master 分支完成开发。