创建一个 Hypervel 项目

在创建第一个 Hypervel 项目之前，请确保你的本地机器已安装 Composer（用于依赖管理），并且已安装 Swoole PHP 扩展。通常可以通过 PECL 安装：

  1. pecl install swoole

Mac 用户也可以通过 brew 安装 Swoole：

  1. brew tap shivammathur/extensions
  2. brew install shivammathur/extensions/swoole@8.3

使用 shivammathur/extensions 可以帮助你解决在 Apple M1 环境下安装 swoole 时常见的问题。请根据你所用的 PHP 版本替换公式结尾的版本号。

信息提示

你也可以使用 Box 作为你的运行环境。

小技巧

如果你打算使用全局协程助手函数（如 go、co 和 defer），建议在 php.ini 文件中将 swoole.use_shortname 设置为 Off，这样可以在协程中更好地捕获错误。否则当协程中的错误未被正确捕获时，会抛出 Uncaught RuntimeException。

详情请参考 错误处理错误示范。

完成 PHP、Composer 和 Swoole 扩展的安装后，你可以使用 Composer 的 create-project 命令来创建一个新的 Hypervel 项目：

  1. composer create-project hypervel/hypervel example-app

项目创建完成后，使用 serve 命令启动 Hypervel 的本地开发服务器：

  1. cd example-app
  2. php artisan serve

由于在运行后所有文件都会被加载到内存中，因此当你修改文件时需要重启服务器。在开发环境下，你可以使用热重载命令：

  1. php artisan watch

当 HTTP 服务器启动后，你的应用可以通过浏览器访问：http://localhost:9501。接下来你就可以正式开始使用 Hypervel 进行开发了。

小技巧

你可以在 config/server.php 文件中自定义 host、端口及其他服务器配置项。

初始配置

Hypervel 的所有配置文件都保存在 config 目录下。每个配置项都有注释说明，你可以查看这些文件，了解所有可用选项。

你可能希望先查看 config/app.php 文件及其文档，其中包含如时区（timezone）、语言（locale）等配置项，可以根据你的应用需求进行修改。

基于环境的配置

由于 Hypervel 的许多配置值会根据运行环境（如本地开发或生产服务器）而变化，因此许多关键配置项通过应用根目录下的 .env 文件进行定义。

你的 .env 文件不应提交到版本控制系统中，因为每个开发者或服务器可能需要不同的环境配置。此外，如果有攻击者获取了源码仓库访问权限，敏感的凭据也将暴露，存在安全风险。

注意

关于 .env 文件及基于环境的配置的更多信息，请参阅完整的 配置文档。

数据库与数据迁移

当你创建了一个 Hypervel 应用后，通常你希望将数据存储到数据库中。默认情况下，应用的 .env 文件指定使用 SQLite 数据库。

在创建项目时，Laravel 会自动为你创建 database/database.sqlite 文件，并执行必要的迁移来创建数据库表。

如果你希望使用其他数据库驱动（如 MySQL），你可以修改 .env 文件中的数据库配置。例如，如果你想使用 MySQL，请修改以下变量：

  1. DB_CONNECTION=mysql
  2. DB_HOST=127.0.0.1
  3. DB_PORT=3306
  4. DB_DATABASE=laravel_hyperf
  5. DB_USERNAME=root
  6. DB_PASSWORD=

如果你选择使用非 SQLite 数据库，需要先创建数据库，然后运行数据迁移命令：

  1. php artisan migrate

使用 Docker 进行开发

如果你的系统不满足 Hypervel 的运行要求，或者你不熟悉系统环境配置，也可以使用 Docker 来开发 Hypervel 项目：

  • 启动容器 下面这个示例中，宿主机的目录 /workspace/hypervel 会映射到容器中：

注意

如果你的 Docker 启动时启用了 selinux-enabled 选项，那么容器中访问宿主资源会受到限制，此时需要在启动容器时添加 --privileged -u root 参数。

  1. docker run --name hypervel \
  2. -v /workspace/hypervel:/data/project \
  3. -p 9501:9501 -it \
  4. --privileged -u root \
  5. --entrypoint /bin/sh \
  6. hyperf/hyperf:8.3-alpine-v3.19-swoole-v6

注意

如果 docker 启用了 selinux-enabled，请在命令中添加 --privileged -u root。

不兼容的扩展

由于 Hypervel 是基于 Swoole 的协程机制构建的，因此某些扩展在协程环境下不兼容。目前以下扩展（包括但不限于）不兼容：

  • xhprof
  • xdebug（适用于 PHP 8.1+ 和 Swoole ≥ 5.0.2）
  • blackfire
  • trace
  • uopz