Spiral 詳細上手指南之安裝與配置

  • 2020 年 2 月 15 日
  • 筆記

在上一篇《Spiral: 一個性能卓越的PHP/Golang混合開發框架》 中,我介紹了 Spiral 這個基於 PHP/Golang 的高性能混合開發框架,這次開始這個上手指南系列的第一篇文章。

TOC

我主要從事的是 WEB 開發工作,所以我就從 WEB 開發的角度來聊一下。

官方提供了 WEB 開發的項目骨架:spiral/app, 如果你想快速上手,可以從這個項目骨架開始:

安裝

採用每個 PHPer 都很熟悉的 composer 來創建項目:

composer create-project spiral/app myapp

項目創建之後,會自動執行一系列動作:

  1. 執行 php -r "copy('.env.sample', '.env')" 創建本地環境變量文件 .env
  2. 執行 php app.php encrypt:key -m .env.env 文件中注入項目的唯一 key
  3. 執行 php app.php configure -vv 確保當前項目被正確安裝和配置,這個步驟會做的事情包括:
    1. 創建並驗證 runtime 目錄權限,更新 orm, prototyped, i18n 本地化語言包的緩存
    2. 將項目代碼和視圖模板中所有調用到的國際化字符提取到語言包文件中
    3. 預熱視圖緩存
    4. 更新依賴注入的標識與目標對象關係
  4. 下載 RoadRunner 的當前平台二進制文件

經過這一系列操作之後,你的本地項目就創建完成,可以立即開始體驗或者進行開發了。

目錄結構

官方項目骨架初始化得到的目錄結構如下:

myapp -- 項目目錄  ├── .env -- 環境變量配置文件  ├── .rr.yaml -- 應用服務器配置文件  ├── LICENSE -- 開源協議  ├── README.md -- 說明文件  ├── app -- 應用目錄  │   ├── config -- 配置文件  │   │   └── database.php -- 數據庫組件配置文件  │   ├── locale -- 語言包目錄  │   │   ├── en -- 英文語言包  │   │   └── ru -- 俄語語言包  │   │       └── messages.en.php -- 俄語語言文件  │   ├── src -- 源碼目錄  │   │   ├── App.php -- 應用核心類  │   │   ├── Bootloader -- 引導加載器目錄  │   │   │   ├── LocaleSelectorBootloader.php -- 用戶語言識別加載器  │   │   │   ├── LoggingBootloader.php -- 日誌加載器  │   │   │   └── RoutesBootloader.php -- 路由加載器  │   │   ├── Controller -- 控制器目錄  │   │   │   └── HomeController.php -- 控制器類  │   │   ├── Job -- 任務目錄  │   │   │   └── Ping.php 任務類  │   │   └── Middleware -- 中間件目錄  │   │       └── LocaleSelector.php -- 語言識別中間件  │   └── views -- 視圖目錄  │       ├── embed -- 嵌入式視圖(可以理解為頁面片)目錄  │       │   └── links.dark.php -- 嵌入式視圖文件  │       ├── home.dark.php -- 視圖文件  │       └── layout -- 布局目錄  │           └── base.dark.php -- 基礎布局文件  ├── app.php -- 命令腳手架(開發輔助工具)  ├── composer.json -- composer 配置文件  ├── composer.lock -- composer 鎖定文件  ├── phpunit.xml -- phpunit 配置文件  ├── public -- 網站根目錄  │   ├── favicon.ico -- favicon  │   ├── images -- 圖片目錄  │   │   └── logo.svg -- LOGO 圖片  │   └── styles -- 樣式目錄  │       └── welcome.css -- 樣式文件  ├── runtime -- 運行時目錄(程序自動生成)  │   └── cache -- 緩存目錄  │       ├── cycle.php -- Cycle ORM 緩存  │       ├── i18n.en.php -- 英語語言緩存  │       ├── i18n.locales.php -- 本地化語言緩存  │       └── prototyped.php -- 依賴注入緩存  ├── spiral -- golang 開發的應用服務器(用來啟動服務)  └── tests -- 測試文件目錄      ├── Feature -- 特性測試文件目錄      │   └── BasicTest.php -- 特性測試示例      ├── TestApp.php -- 用於測試的應用核心類      ├── TestCase.php -- PHPUnitFrameworkTestCase 的擴展      ├── Traits -- Traits 定義      │   ├── InteractsWithConsole.php -- 提供與 Console 命令交互的方法      │   └── InteractsWithHttp.php -- 提供與 HTTP 路由交互的方法      └── bootstrap.php -- 測試引導程序

由於項目團隊目前的核心還是在 Framework 以及 RoadRunner 的開發迭代以及文檔的編寫上,所以這個 WEB 項目骨架還是不太完善的,絕對沒有 Laravel 的那麼舒服和合理。尤其是單元測試的部分,官方的骨架本來是沒有集成 PHPUnit 的,我在第一次體驗 Spiral 的時候,匆匆擼了一份提交 PR 過去,被接受了,但是顯然就太簡陋了。但是 Spiral 和 Symfony 一樣,是允許你自由配置項目目錄結構的,也可以不要官方提供的這個骨架,通過各個組件自由搭配你自己的框架(這個以後再說)。

運行服務器

項目初始化完成後,通過根目錄下的 spiral 可執行文件,就能啟動服務了:

./spiral serve -v -d

上述命令,--verbose, -v 等效,是輸出詳細信息,--debug, -d 是調試模式。除了 serve 子命令啟動 HTTP 服務以外,還有 stop 子命令來停止服務,http:reset 重置 HTTP 服務的進程池,http:workers 查看 HTTP 服務工作進程。此外還有 GRPC 以及 JOB 相關的命令這裡就不提了。可以自行通過 ./spiral help 或者 ./spiral -h 查看。

要說明的一點是,這個二進制文件不要加到代碼倉庫里,尤其是開發機、測試機、生產服務器操作系統不同的時候。因為它是根據你的平台操作系統下載的,你在 Mac 上開發,同一個二進制文件部署到 Linux 服務器就用不了了。

在部署代碼的時候,需要執行一次 vendor/bin/spiral get-binary 命令,就會下載對應平台的二進制文件(如果你有多個 Spiral 項目部署在同一台機器,可以只下載一個二進制文件)。

服務啟動以後,默認情況下,訪問 http://localhost:8080 就會看到歡迎頁面。

系統自帶了三個路由,分別是:

  • / (等效:/index.html, /home/index): 歡迎頁面
  • /home/ping (等效:/ping.html): 顯示當前工作進程 id
  • /home/exception (等效:/exception.html): 展示開發模式下的錯誤調試頁面

實際上系統還默認提供了一個系統運行指標服務,監聽在 2112 端口,可以通過 Prometheus 訪問 http://localhost:2112/metrics 監控系統指標,此處不多贅述。

如果你另外打開一個終端,執行 ./spiral http:/workers, 會看到類似這樣的一個表:

+---------+-----------+---------+---------+--------------------+  |   PID   |  STATUS   |  EXECS  | MEMORY  |      CREATED       |  +---------+-----------+---------+---------+--------------------+  |   61067 | ready     |       1 | 20 MB   | 10 minutes ago     |  |   61070 | ready     |       1 | 18 MB   | 10 minutes ago     |  |   61071 | ready     |       1 | 18 MB   | 10 minutes ago     |  |   61072 | ready     |       1 | 18 MB   | 10 minutes ago     |  |   61073 | ready     |       1 | 21 MB   | 10 minutes ago     |  |   61074 | ready     |       1 | 18 MB   | 10 minutes ago     |  |   61075 | ready     |       0 | 17 MB   | 10 minutes ago     |  |   61076 | ready     |       0 | 17 MB   | 10 minutes ago     |  |   61077 | ready     |       0 | 17 MB   | 10 minutes ago     |  |   61078 | ready     |       0 | 17 MB   | 10 minutes ago     |  |   61079 | ready     |       0 | 17 MB   | 10 minutes ago     |  |   61083 | ready     |       0 | 17 MB   | 10 minutes ago     |  +---------+-----------+---------+---------+--------------------+

這裡展示了你當前項目的所有工作進程的工作狀況,如上圖,我一共啟動了 12 個工作進程(實際上默認還會有兩個 jobs 進程)。這 12 個進程是採用輪詢策略順序調度的,每一個新的請求都會交給下一個工作進程執行。默認情況下啟動的 HTTP 工作進程數是你的 CPU 核數。

在本地開發的時候,建議使用單一工作進程,我們先來配置一下:

  1. 打開 .rr.yaml 文件
  2. 找到 http.workers(即 http: 下面的 workers:)
  3. command: "php app.php" 的下一行,加上兩行:
    • pool.numWorkers: 1
    • pool.maxJobs: 1

然後就可以進行開發了。與 swoole 系的框架相比,Spiral 的一大好處是除非你改動了諸如 App, Bootloader 這類常駐內存的核心代碼,否則你是不必重啟服務的。像增加路由啊、增加數據實體啊一類的,跟常規的 PHP 程序的開發模式是沒區別的,實時生效。

配置文件

官方骨架除了 .env 下面提供了 DEBUG=trueSAFE_MIGRATIONS=true 這兩個需要在開發環境和生產環境調整的環境變量以外,只提供了一個 App/config/database.php 文件。

查找某個組件對應的配置文件名和可用配置項

實際上官方的每一個組件,都有自己的配置項是可以通過配置文件來調整配置的。但是骨架本身沒有提供對應的配置示例,原因在於他們認為項目骨架已經提供了最優配置。當然,如果你需要的話,下面是如何查找某個組件的配置文件名以及可用配置項的方法:

假如我們要配置一個 spiralcomponent 組件的配置文件名和配置項,那麼你可以去 github.com/spiral/component 查閱該組件的文檔(如果有文檔的話),或者用下面的方法:

  • vendor 目錄下找到 spiral/component 子目錄
  • 展開這個目錄,查找下面的 src/Config 目錄,如果沒有這個目錄,那麼這個組件就不支持配置文件配置。
  • vendor/spiral/component/src/Config 目錄下,打開 ComponentConfig.php 文件
  • 你會看到 public const CONFIG = 'component' 這樣的一行代碼,說明這個組件的配置文件名是 component.php
  • 你還會看到 protected $config = [] 這樣的一個定義,這個數組就是該組件的可用配置項。

示例:修改項目的默認語言

掌握了這樣的方法,比如我們要配置一下本地化組件,把默認語言改成 zh

  • 打開 vendor/spiral/translator/src/Config/TranslatorConfig.php
  • 通過這個文件,我們知道對應的配置文件是 translator.php, 要配置的 keylocale, 兼容語言的 keyfallbackLocale,其它的配置項用默認的。
  • 接下來,在 App/config 目錄下創建 translator.php, 寫入如下代碼:

<?php

return [

  'locale' => 'zh',
  'fallbackLocale' => 'en'

];


就完成了對 Translator 組件的配置。

當然,實際上我們大多數時候只需要調整運行環境和數據庫配置即可。

數據庫配置

系統默認只提供了 sqlite 的數據庫配置,但 Spiral 的數據庫和 ORM 組件支持 MySQL, MariaDB, SQLite, PostgreSQL, SQLServer 等多種數據庫,都提供了自動化數據庫遷移(Migration)支持。

接下來我們要配置一下本地開發數據庫,連接信息如下:

Host: localhost  Port: 3306  Database: dev  User: dev  Password: dev

打開 App/config/database.php 文件,默認內容如下:

use SpiralDatabaseDriver;    return [      'default'   => 'default',      'databases' => [          'default' => ['driver' => 'runtime'],      ],      'drivers'   => [          'runtime' => [              'driver'     => DriverSQLiteSQLiteDriver::class,              'connection' => 'sqlite:' . directory('runtime') . 'runtime.db',              'profiling'  => true,          ],      ]  ];

這裡的三個 keydefault 代表不指定的情況下使用的連接,databases 代表的是可用連接,而 drivers 代表的是可用數據庫驅動。

注意!!Spiral 的 databases 實際上相當於其他框架一般用的 connections,而且在執行諸如 migrate 一類的操作時,會在 databases 中定義的所有連接上執行!!!

我們來增加一個 mysql 的配置:

use SpiralDatabaseDriver;    return [    'default' => 'default',    'databases' => [      'default' => ['driver' => 'mysql'],    ],    'drivers' => [      'runtime' => [        'driver' => DriverSQLiteSQLiteDriver::class,        'connection' => 'sqlite:' . directory('runtime') . 'runtime.db',        'profiling' => true,      ],      'mysql' => [        'driver' => DriverMySQLMySQLDriver::class,        'connection' => 'mysql:host=localhost;dbname=dev;charset=utf8mb4',        'username' => 'dev',        'password' => 'dev',      ]    ]  ];

配置時採用的是 PDO 的 DSN 寫法,需要了解更多的話可以查閱 Spiral 的官方文檔或者 PHP PDO 的文檔。

在下一篇文章,我會繼續介紹 Spiral 的路由、控制器相關的部分。

至此我們就完成了開發前的基本配置。