使用 ServBay 创建并运行 CakePHP 项目
ServBay 是一款专为 macOS 设计的本地 Web 开发环境，集成了 PHP、Node.js、Python、Go、Java 等多种语言环境，以及 MySQL、PostgreSQL、MongoDB、Redis 等数据库服务，搭配 Caddy 或 Nginx Web 服务器。它提供了一个便捷高效的开发平台，让开发者可以轻松搭建和管理本地项目。
本篇文章将指导您如何在 ServBay 环境中创建、配置并运行一个 CakePHP 项目。CakePHP 是一个流行的 PHP Web 开发框架，遵循 MVC（模型-视图-控制器）模式，以其快速开发能力、强大的 ORM 和内置安全特性而闻名。结合 ServBay 的便捷性，您可以迅速启动 CakePHP 开发工作。
什么是 CakePHP？
CakePHP 是一个开源的 PHP Web 应用开发框架，提供了一套基础结构，用于快速、结构化地开发 Web 应用程序，而无需牺牲灵活性。它遵循约定优于配置的原则，简化了许多常见的开发任务。
CakePHP 的主要特性和优势
- 基于 MVC 模式: 清晰的代码组织结构，易于维护和扩展。
- 快速开发: 提供了命令行工具（Bake）用于生成代码，加速开发流程。
- 强大的 ORM (对象关系映射): 简化了数据库交互，支持多种数据库系统。
- 内置安全性: 提供了 CSRF 防护、SQL 注入防护、输入验证等安全特性。
- 灵活的模板引擎: 支持多种视图层技术。
- 活跃的社区和丰富的插件: 遇到问题容易找到支持，功能可扩展。
- 详尽的文档: 提供了全面的指南和 API 参考。
CakePHP 适用于构建各种规模的 Web 应用程序，从简单的 API 到复杂的企业级系统。
使用 ServBay 搭建 CakePHP 开发环境
ServBay 为 CakePHP 开发提供了便利的集成环境，包括：
- 预安装的 PHP 解释器及常用扩展。
- 预安装的 Composer 包管理器。
- 易于配置的 Web 服务器（Caddy/Nginx）。
- 集成的数据库服务（MySQL, PostgreSQL, Redis 等）。
通过 ServBay，您可以避免手动安装和配置这些组件的繁琐过程。
前提条件
在开始之前，请确保您已完成以下准备工作：
- 安装 ServBay: 确保您已在 macOS 上下载并成功安装 ServBay。
- 启动 ServBay 服务: 启动 ServBay 应用程序，并确保所需的软件包（例如 PHP、您计划使用的数据库如 MySQL 或 PostgreSQL，以及缓存服务如 Redis 或 Memcached）已启动运行。您可以在 ServBay 控制面板的“软件包”选项卡中管理这些服务。
- 熟悉 ServBay 基础操作: 了解如何在 ServBay 中添加和配置网站。如果您不熟悉，建议先阅读 ServBay 基础使用指南。
创建 CakePHP 项目
ServBay 建议将您的 Web 项目文件统一存放在 /Applications/ServBay/www 目录下，这有助于 ServBay 自动识别和管理您的网站。
打开终端
打开 macOS 的终端应用程序。
导航到 ServBay 网站根目录
切换到 ServBay 推荐的网站存放目录：
bashcd /Applications/ServBay/www1创建项目目录
为您的 CakePHP 项目创建一个新的子目录。我们使用
servbay-cakephp-app作为示例项目名称：bashmkdir servbay-cakephp-app cd servbay-cakephp-app1
2使用 Composer 创建 CakePHP 项目
ServBay 已经预装了 Composer。在项目目录下，使用 Composer 创建 CakePHP 项目骨架：
bashcomposer create-project --prefer-dist cakephp/app .1这个命令会下载 CakePHP 的最新稳定版本及其依赖，并将其安装到当前目录 (
.)。安装 ORM 驱动 (如果使用 PostgreSQL)
如果您计划使用 PostgreSQL 数据库，需要额外安装 PostgreSQL 的 ORM 驱动：
bashcomposer require cakephp/orm-pgsql1对于 MySQL，通常无需额外安装驱动，它已包含在 CakePHP 核心依赖中。
初始化配置
创建项目后，需要进行一些基本的配置，特别是数据库连接信息。
配置环境变量和数据库连接
CakePHP 的本地环境配置主要集中在
config/app_local.php文件中。编辑此文件，找到Datasources部分，配置您的数据库连接信息。ServBay 的默认数据库用户名通常是root，默认密码是password。例如，配置 MySQL 数据库连接：
php// config/app_local.php 'Datasources' => [ 'default' => [ 'className' => \Cake\Database\Connection::class, 'driver' => \Cake\Database\Driver\Mysql::class, // 或 \Cake\Database\Driver\Postgres::class 对于 PostgreSQL 'persistent' => false, 'host' => '127.0.0.1', // 数据库服务器地址，ServBay 默认在本地 //'port' => '3306', // MySQL 默认端口 3306, PostgreSQL 默认 5432 'username' => 'root', // ServBay 默认用户名 'password' => 'password', // ServBay 默认密码 'database' => 'servbay_cakephp_app', // 您将要创建的数据库名称 'encoding' => 'utf8mb4', 'timezone' => 'UTC', 'flags' => [], 'cacheMetadata' => true, 'log' => false, /** * Set identifier quoting to true if you are using words like "user" as your table name. * But if you are using words like "cake" you can set it to false. * If you don't know use true. */ 'quoteIdentifiers' => false, /** * Current limitations include the following: * - Most drivers do not support setting isolation levels via PDO options. * Using them will result in an error. * - Not all drivers support setting the charset via PDO options. * Using them will result in an error. * - PDO options are not supported for packaged drivers like Postgres from CakePHP. * For Postgres, you only need to set the encoding. */ 'options' => [], //'url' => env('DATABASE_URL', null), // 如果您使用 DATABASE_URL 环境变量，可以启用此行 ], ],1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38请根据您使用的数据库类型（MySQL 或 PostgreSQL）调整
driver和可能的port设置。确保database名称与您计划创建的数据库名称一致。
配置 Web 服务器 (在 ServBay 中创建网站)
为了通过浏览器访问 CakePHP 项目，您需要在 ServBay 中配置一个网站来指向您的项目目录。
打开 ServBay 控制面板
点击 ServBay 图标打开控制面板。
导航到“网站”选项卡
在 ServBay 控制面板中，选择左侧导航栏的“网站”（以前称为“主机”）。
添加新网站
点击底部的
+按钮添加一个新的网站。填写以下信息：- 名字 (Name): 给您的网站一个易于识别的名称，例如
My CakePHP Dev Site。 - 域名 (Domain): 设置一个本地开发域名，例如
servbay-cakephp-test.local。ServBay 会自动将其指向本地。 - 网站类型 (Site Type): 选择
PHP。 - PHP 版本 (PHP Version): 选择一个适合您 CakePHP 版本（例如 CakePHP 4+ 通常需要 PHP 7.4+，CakePHP 5+ 通常需要 PHP 8.1+）的 PHP 版本，例如
8.3。 - 网站根目录 (Document Root): 重要！ CakePHP 项目的 Web 服务器根目录不是项目主目录，而是其内部的
webroot目录。设置为/Applications/ServBay/www/servbay-cakephp-app/webroot(请将servbay-cakephp-app替换为您实际的项目目录名称)。
- 名字 (Name): 给您的网站一个易于识别的名称，例如
保存并应用更改
填写完毕后，点击右下角的“保存”按钮。ServBay 会提示您应用更改，点击确认。ServBay 会自动配置您的 Web 服务器（Caddy 或 Nginx）以响应
servbay-cakephp-test.local域名，并将请求指向您项目的webroot目录。
详细的网站添加步骤可以参考 ServBay 文档中的 添加第一个网站 部分。
验证基本设置
现在，您应该可以通过浏览器访问您创建的网站了。
打开浏览器，访问您在 ServBay 中设置的域名，例如 https://servbay-cakephp-test.local。
如果一切配置正确，您应该会看到 CakePHP 的默认欢迎页面。这表明 PHP 环境、Web 服务器和 ServBay 的网站配置都已正常工作。
集成数据库和缓存服务
CakePHP 提供了强大的 ORM 和缓存抽象层，可以轻松集成 ServBay 提供的数据库和缓存服务。
关系型数据库示例 (MySQL / PostgreSQL)
本示例将演示如何使用 CakePHP 的 ORM 连接 ServBay 中的 MySQL 或 PostgreSQL 数据库，创建一张简单的 users 表，并进行数据的增删改查操作。
在 ServBay 中创建数据库
在进行数据库迁移之前，您需要在 ServBay 的数据库服务器中创建一个新的数据库。使用 ServBay 提供的数据库管理工具（如 phpMyAdmin for MySQL/MariaDB, pgAdmin for PostgreSQL, 或 Navicat/DBeaver 等第三方工具）连接到您的数据库服务（地址通常是
127.0.0.1，用户root，密码password），然后创建一个名为servbay_cakephp_app的新数据库。创建 ORM Model 文件
CakePHP 的 ORM 需要一个 Model 文件来表示数据库表。创建一个
UsersTable.php文件来表示users表。将以下代码保存到
src/Model/Table/UsersTable.php：php<?php namespace App\Model\Table; use Cake\ORM\Table; use Cake\Validation\Validator; // 如果需要验证规则 class UsersTable extends Table { /** * Initialize method * * @param array $config The configuration for the Table. * @return void */ public function initialize(array $config): void { parent::initialize($config); $this->setTable('users'); // 明确指定对应的表名 $this->setDisplayField('name'); // 设置在关联等操作中默认显示的字段 $this->setPrimaryKey('id'); // 设置主键 // 如果需要时间戳行为 // $this->addBehavior('Timestamp'); } /** * Default validation rules. * * @param \Cake\Validation\Validator $validator Validator instance. * @return \Cake\Validation\Validator */ public function validationDefault(Validator $validator): Validator { $validator ->scalar('name') ->maxLength('name', 255) ->requirePresence('name', 'create') ->notEmptyString('name'); $validator ->email('email') ->requirePresence('email', 'create') ->notEmptyString('email') ->add('email', 'unique', ['rule' => 'validateUnique', 'provider' => 'table']); // 确保 email 唯一 return $validator; } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49使用 Bake 工具创建迁移文件
CakePHP 推荐使用数据库迁移来管理数据库结构。在项目根目录 (
/Applications/ServBay/www/servbay-cakephp-app)，使用 CakePHP 的 Bake 工具创建一个迁移文件来定义users表结构：bashbin/cake bake migration CreateUsers name:string email:string:unique1这个命令会创建一个新的迁移文件，其中包含了创建
users表的指令，包括name(字符串类型) 和email(字符串类型，且唯一) 字段。运行数据库迁移
执行迁移命令，将
users表实际创建到您在步骤1中创建的数据库中：bashbin/cake migrations migrate1如果迁移成功，您将在数据库中看到新创建的
users表。配置数据库连接 (如果之前未配置)
确保
config/app_local.php中Datasources.default的配置与您使用的数据库类型和凭据匹配。MySQL 配置示例:
php'Datasources' => [ 'default' => [ 'className' => \Cake\Database\Connection::class, 'driver' => \Cake\Database\Driver\Mysql::class, 'host' => '127.0.0.1', 'username' => 'root', 'password' => 'password', 'database' => 'servbay_cakephp_app', // ... 其他配置 ], ],1
2
3
4
5
6
7
8
9
10
11PostgreSQL 配置示例:
php'Datasources' => [ 'default' => [ 'className' => \Cake\Database\Connection::class, 'driver' => \Cake\Database\Driver\Postgres::class, 'host' => '127.0.0.1', // 'port' => '5432', // 默认端口 'username' => 'root', // ServBay 默认用户名 'password' => 'password', // ServBay 默认密码 'database' => 'servbay_cakephp_app', // ... 其他配置 ], ],1
2
3
4
5
6
7
8
9
10
11
12
添加示例路由和控制器方法
修改
config/routes.php文件，添加用于添加和显示用户数据的路由：php// config/routes.php use Cake\Routing\RouteBuilder; use Cake\Routing\Router; use Cake\Routing\Route\DashedRoute; Router::defaultRouteClass(DashedRoute::class); Router::scope('/', function (RouteBuilder $routes) { // ... 其他路由 $routes->connect('/', ['controller' => 'Pages', 'action' => 'display', 'home']); // 添加数据库示例路由 $routes->connect('/db-add-user', ['controller' => 'Pages', 'action' => 'dbAddUser']); $routes->connect('/db-list-users', ['controller' => 'Pages', 'action' => 'dbListUsers']); // ... 其他路由 $routes->fallbacks(DashedRoute::class); });1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18修改
src/Controller/PagesController.php文件，添加用于数据库操作的方法：php<?php namespace App\Controller; use Cake\Http\Response; use Cake\ORM\TableRegistry; use Cake\Datasource\Exception\RecordNotFoundException; // 用于查找不到记录时的异常处理 class PagesController extends AppController { /** * Displays a view * * @param array ...$path Path segments. * @return \Cake\Http\Response|null */ public function display(...$path): ?Response { // ... 默认的 display 方法 return new Response(['body' => 'Hello ServBay! This is the default page.']); } /** * 数据库示例：添加用户 */ public function dbAddUser(): Response { $usersTable = TableRegistry::getTableLocator()->get('Users'); // 获取 Users Table 实例 // 创建一个新的用户实体 $user = $usersTable->newEntity([ 'name' => 'ServBay Demo User', 'email' => '[email protected]' // 使用 ServBay 品牌示例邮箱 ]); // 尝试保存实体到数据库 if ($usersTable->save($user)) { return new Response(['body' => 'User added successfully! User ID: ' . $user->id]); } else { // 如果保存失败，可能是验证错误或其他问题 $errors = $user->getErrors(); // 获取验证错误信息 return new Response(['body' => 'Failed to add user. Errors: ' . json_encode($errors)]); } } /** * 数据库示例：列出所有用户 */ public function dbListUsers(): Response { $usersTable = TableRegistry::getTableLocator()->get('Users'); // 获取 Users Table 实例 // 查找所有用户 $users = $usersTable->find()->all(); // 将结果编码为 JSON 输出 return new Response(['body' => json_encode($users->toArray())]); // 使用 toArray() 将 Collection 转换为数组 } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58访问数据库示例
打开浏览器：
- 访问
https://servbay-cakephp-test.local/db-add-user来添加一个用户。您应该会看到成功的消息。 - 访问
https://servbay-cakephp-test.local/db-list-users来查看数据库中的所有用户列表（现在应该包含您刚刚添加的用户）。
- 访问
通过这些步骤，您成功地将 CakePHP 项目连接到了 ServBay 中的关系型数据库，并执行了基本的 ORM 操作。
缓存服务示例 (Memcached / Redis)
CakePHP 提供了统一的缓存 API，可以轻松切换使用不同的缓存引擎，如 Memcached 或 Redis。ServBay 预装了 PHP 的 Memcached 和 Redis 扩展，并且提供了相应的服务。
首先，确保您在 ServBay 控制面板的“软件包”选项卡中启动了 Memcached 或 Redis 服务。
配置缓存连接
编辑
config/app_local.php文件，在Cache部分配置您的缓存连接。Memcached 配置示例:
php// config/app_local.php 'Cache' => [ 'default' => [ 'className' => \Cake\Cache\Engine\MemcachedEngine::class, 'servers' => ['127.0.0.1:11211'], // ServBay 默认 Memcached 地址和端口 'prefix' => 'servbay_cakephp_', // 缓存键前缀 ], // ... 其他缓存配置 ],1
2
3
4
5
6
7
8
9Redis 配置示例:
php// config/app_local.php 'Cache' => [ 'default' => [ 'className' => \Cake\Cache\Engine\RedisEngine::class, 'host' => '127.0.0.1', // ServBay 默认 Redis 地址 'port' => 6379, // ServBay 默认 Redis 端口 'password' => null, // 如果 Redis 设置了密码，在此填写 'database' => 0, // Redis 数据库索引 'prefix' => 'servbay_cakephp_', // 缓存键前缀 ], // ... 其他缓存配置 ],1
2
3
4
5
6
7
8
9
10
11
12
选择您使用的缓存服务进行配置。
添加示例路由和控制器方法
修改
config/routes.php文件，添加用于缓存示例的路由：php// config/routes.php // ... 其他路由 $routes->connect('/cache-memcached', ['controller' => 'Pages', 'action' => 'cacheMemcached']); $routes->connect('/cache-redis', ['controller' => 'Pages', 'action' => 'cacheRedis']); // ... 其他路由1
2
3
4
5修改
src/Controller/PagesController.php文件，添加使用缓存的方法：php<?php namespace App\Controller; use Cake\Http\Response; use Cake\Cache\Cache; // 导入 Cache 类 // ... 其他 use 语句 class PagesController extends AppController { // ... 其他方法 (display, dbAddUser, dbListUsers) /** * 缓存示例：使用 Memcached */ public function cacheMemcached(): Response { // 确保在 app_local.php 中配置了 'default' 缓存使用 MemcachedEngine $cacheKey = 'servbay_memcached_test_key'; $cachedData = Cache::read($cacheKey); // 尝试从缓存读取数据 $responseBody = ''; if ($cachedData === false) { // 缓存未命中 $responseBody = 'Cache miss! Writing "Hello Memcached!" to cache.'; $dataToCache = 'Hello Memcached!'; Cache::write($cacheKey, $dataToCache, 'default'); // 将数据写入 'default' 缓存配置 (配置为 Memcached) } else { // 缓存命中 $responseBody = 'Cache hit! Data from cache: ' . $cachedData; } return new Response(['body' => $responseBody]); } /** * 缓存示例：使用 Redis */ public function cacheRedis(): Response { // 确保在 app_local.php 中配置了 'default' 缓存使用 RedisEngine $cacheKey = 'servbay_redis_test_key'; $cachedData = Cache::read($cacheKey); // 尝试从缓存读取数据 $responseBody = ''; if ($cachedData === false) { // 缓存未命中 $responseBody = 'Cache miss! Writing "Hello Redis!" to cache.'; $dataToCache = 'Hello Redis!'; Cache::write($cacheKey, $dataToCache, 'default'); // 将数据写入 'default' 缓存配置 (配置为 Redis) } else { // 缓存命中 $responseBody = 'Cache hit! Data from cache: ' . $cachedData; } return new Response(['body' => $responseBody]); } }1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61访问缓存示例
打开浏览器：
- 如果您配置了 Memcached，访问
https://servbay-cakephp-test.local/cache-memcached。首次访问显示“Cache miss”，刷新页面则显示“Cache hit”。 - 如果您配置了 Redis，访问
https://servbay-cakephp-test.local/cache-redis。首次访问显示“Cache miss”，刷新页面则显示“Cache hit”。
- 如果您配置了 Memcached，访问
这表明您的 CakePHP 项目已成功连接并使用了 ServBay 提供的缓存服务。
注意事项
- 数据库凭据: ServBay 的默认数据库用户名和密码 (
root/password) 仅用于本地开发。在生产环境中请务必使用更安全的凭据。 - 网站根目录: 务必将 ServBay 网站的“网站根目录”指向 CakePHP 项目内的
webroot目录，而不是项目主目录。这是 CakePHP 的最佳实践。 - PHP 版本兼容性: 确保您在 ServBay 中选择的 PHP 版本与您使用的 CakePHP 版本兼容。查阅 CakePHP 官方文档获取版本要求。
- ServBay 端口: 如果 ServBay 默认端口（如 80 和 443）被其他程序占用，您需要在 ServBay 设置中修改端口，并相应地通过修改 hosts 文件或使用端口号访问。
常见问题解答 (FAQ)
- Q: 访问
servbay-cakephp-test.local出现“找不到页面”错误？- A: 检查 ServBay 中该网站的“网站根目录”是否正确指向了
/Applications/ServBay/www/servbay-cakephp-app/webroot。 - 检查 ServBay 的 Web 服务器（Caddy/Nginx）是否正在运行。
- 检查您的系统 hosts 文件是否将
servbay-cakephp-test.local解析到127.0.0.1（ServBay 会自动处理，但偶尔需要检查）。 - 检查 CakePHP 项目的
.htaccess或 Web 服务器配置文件是否正确（通常webroot/.htaccess默认是正确的）。
- A: 检查 ServBay 中该网站的“网站根目录”是否正确指向了
- Q: 数据库连接失败？
- A: 检查 ServBay 中对应的数据库服务（MySQL/PostgreSQL）是否正在运行。
- 检查
config/app_local.php中的数据库连接信息（host, port, username, password, database）是否正确，是否与 ServBay 数据库服务的配置一致。 - 确认您已经在数据库服务器中创建了
servbay_cakephp_app数据库。
- Q: Composer 命令 (
bin/cake) 无法执行？- A: 确保您在终端中当前目录是 CakePHP 项目的根目录 (
/Applications/ServBay/www/servbay-cakephp-app)。 - 确保 ServBay 中的 PHP 和 Composer 软件包已启动。
- 检查终端是否能够找到
php命令（ServBay 通常会将 PHP 添加到 PATH）。可以尝试使用 ServBay 集成的终端或手动设置 PATH。
- A: 确保您在终端中当前目录是 CakePHP 项目的根目录 (
总结
通过 ServBay，您可以高效地在 macOS 上为 CakePHP 项目搭建本地开发环境。ServBay 预集成的 PHP、Composer、Web 服务器和数据库服务极大地简化了配置过程。本文详细介绍了从项目创建、基本配置、Web 服务器设置，到集成关系型数据库和缓存服务的全过程，帮助您快速启动 CakePHP 开发之旅。利用 ServBay 的便捷性，您可以专注于编写代码，而不是环境配置的复杂性。