创建并运行 Phalcon 项目

什么是 Phalcon？

Phalcon 是一个开源的、高性能的 PHP Web 框架，以 C 扩展的形式实现。这种独特的实现方式使得 Phalcon 具有极低的资源消耗和极高的执行速度，显著优于大多数传统的 PHP 框架。Phalcon 遵循 MVC（模型-视图-控制器）架构模式，为开发者提供了一系列丰富的功能组件，包括 ORM（对象关系映射）、模板引擎、路由、缓存、事件管理器等，旨在帮助开发者快速构建功能强大且高性能的 Web 应用和 API。

Phalcon 的主要特性和优势

• 卓越性能: 作为 C 扩展运行，Phalcon 避免了 PHP 脚本解析和加载的开销，提供了原生级别的性能表现。
• 资源高效: 内存占用极低，适合对性能和扩展性有较高要求的应用。
• 功能全面: 内置了开发 Web 应用所需的大部分核心组件，减少了对第三方库的依赖。
• 易于使用: 提供了清晰、一致的 API 和详尽的文档，即使是 Phalcon 的新手也能快速掌握。
• 高度解耦: 各组件独立设计，开发者可以根据项目需求自由选择使用或替换特定组件。
• 安全性: 提供了一系列安全相关的组件，如输入过滤、CSRF 防护等。

Phalcon 是构建高性能、可扩展的 Web 应用和 API 的理想选择，尤其适合对速度和资源效率有严格要求的项目。

使用 ServBay 创建并运行 Phalcon 项目

ServBay 是一个专为 macOS 设计的本地 Web 开发环境，集成了多种版本的 PHP、数据库（如 MySQL, PostgreSQL, MongoDB, Redis）和 Web 服务器（Caddy, Nginx, Apache）以及其他开发者工具。利用 ServBay，您可以轻松搭建和管理 Phalcon 项目所需的运行环境。

本指南将引导您使用 ServBay 的 PHP 环境来创建一个基本的 Phalcon 项目，配置 Web 服务器以使其可访问，并演示如何集成关系型数据库（MySQL）和 NoSQL 数据库（Redis）。

前提条件

在开始之前，请确保您满足以下条件：

1. ServBay 已安装并运行: 确保您已在 macOS 系统上成功安装并启动 ServBay。
2. 已启用所需的 PHP 版本: 在 ServBay 中，确保您计划使用的 PHP 版本已启用。
3. 已启用 Phalcon 模块: ServBay 内置了 Phalcon 模块，但默认可能未启用。请务必按照 如何启用ServBay自带的Phalcon模块 文档中的说明启用对应 PHP 版本的 Phalcon 扩展，并重启 PHP 服务。
4. Composer 已可用: ServBay 自带 Composer，您无需单独安装。请确保您可以在终端中直接使用 composer 命令。

不同版本的 Phalcon 和 DevTools

Phalcon 框架及其配套的开发工具 (Phalcon DevTools) 的版本需要与您使用的 PHP 版本兼容。下表列出了常见的 PHP 版本与推荐的 Phalcon 框架及 DevTools 版本对应关系：

PHP 版本	推荐 Phalcon 框架版本	推荐 Phalcon DevTools 版本	注意事项
PHP 5.6, 7.0, 7.1	Phalcon 3.4.5	3.4.x
PHP 7.2, 7.3, 7.4	Phalcon 4.1.2	~4.1 (或 4.3.x)
PHP 8.0, 8.1, 8.2	Phalcon 5.x	5.0.x (官方)	官方 DevTools 在 PHP 8.x 上可能存在兼容性问题。
PHP 8.3, 8.4	Phalcon 5.x	dev-master (使用修复版仓库)	建议使用社区维护的修复版本以获得更好的兼容性。

重要提示: 对于 PHP 8.x 及以上版本，官方 Phalcon DevTools 的兼容性可能不佳。建议使用社区提供的修复版本。后续创建项目的步骤将包含如何通过 Composer 使用修复版 DevTools 的方法。

创建 Phalcon 项目

建议网站存放路径

为了方便管理，ServBay 建议开发者将所有网站项目放置在默认的网站根目录 /Applications/ServBay/www 下。本示例也将在此目录下创建项目。

1. 进入网站根目录并创建项目文件夹

   打开终端，进入 ServBay 的网站根目录，并为您的 Phalcon 项目创建一个新的文件夹（例如 servbay-phalcon-app）：

   cd /Applications/ServBay/www
   mkdir servbay-phalcon-app
   cd servbay-phalcon-app

2. 安装 Phalcon DevTools

   Phalcon DevTools 是一个命令行工具集，用于帮助开发者快速生成代码、创建项目骨架、管理数据库迁移等。我们通过 Composer 来安装它。根据您选择的 PHP 版本，安装命令略有不同：

   • 对于 PHP 5.6, 7.0, 7.1 (Phalcon DevTools ^3.4):

     composer require phalcon/devtools:"^3.4"

   • 对于 PHP 7.2, 7.3, 7.4 (Phalcon DevTools ~4.1):

     composer require phalcon/devtools:"~4.1"

   • 对于 PHP 8.0, 8.1, 8.2, 8.3, 8.4 (Phalcon DevTools dev-master 修复版): 由于官方 DevTools 对 PHP 8.x 支持可能存在问题，我们需要通过 Composer 使用社区维护的修复版本。首先，在当前项目根目录 (/Applications/ServBay/www/servbay-phalcon-app) 创建或编辑 composer.json 文件，添加修复版仓库的配置：

     {
        "repositories": [
           {
              "url": "https://github.com/daleffe/phalcon-devtools-5.x-fixed.git",
              "type": "git"
           }
        ],
        "require": {
           "phalcon/devtools": "dev-master"
        },
        "minimum-stability": "dev",
        "prefer-stable": true
     }

     然后，运行 Composer 更新命令来安装 DevTools：

     composer update

   Composer 会在项目根目录 (servbay-phalcon-app) 下创建一个 vendor 目录，DevTools 可执行文件位于 vendor/bin/phalcon。

3. 使用 Phalcon DevTools 创建项目骨架

   现在，使用刚刚安装的 DevTools 命令来生成 Phalcon 项目的基本文件结构。我们将项目实际代码放在一个子目录中（例如也叫 servbay-phalcon-app，这是 DevTools 的默认行为）：

   vendor/bin/phalcon project servbay-phalcon-app

   这个命令会在 /Applications/ServBay/www/servbay-phalcon-app 目录下创建一个新的子目录 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app，并在其中生成一个完整的 Phalcon 项目骨架。

4. 进入项目代码目录

   进入新创建的项目代码目录，后续的操作都在此目录下进行：

   cd servbay-phalcon-app

   现在您应该位于 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app 目录。

配置项目环境

Phalcon 项目的配置通常集中在 app/config/config.php 文件中。您需要在此文件中配置数据库连接信息、应用路径等重要设置。

1. 编辑配置文件

   使用您喜欢的代码编辑器打开 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/config.php 文件。找到或添加数据库配置部分。ServBay 的 MySQL/MariaDB 默认用户是 root，默认密码为空，但出于安全考虑，ServBay 强烈建议您设置一个强密码。示例中使用 password 作为占位符，请根据您的实际配置修改。数据库名 servbay_phalcon_app 是我们为这个项目创建的示例数据库名（您可能需要手动创建这个数据库）。

   return new \Phalcon\Config([
       // ... 其他配置 ...
       'database' => [
           'adapter' => 'Mysql', // 或 'Postgres' 等
           'host' => '127.0.0.1',
           'username' => 'root', // ServBay 默认 root 用户
           'password' => 'password', // <-- 请修改为您的数据库密码
           'dbname' => 'servbay_phalcon_app', // <-- 请修改为您的数据库名
       ],
       // ... 其他配置 ...
   ]);

   重要: 确保您已在 ServBay 中启动了相应的数据库服务（如 MySQL 或 MariaDB），并且数据库用户和密码与此配置一致。您也需要手动创建 servbay_phalcon_app 数据库。您可以使用 ServBay 提供的数据库管理工具（如 phpMyAdmin 或 Adminer）来创建数据库和管理用户。

配置 Web 服务器（通过 ServBay 网站功能）

为了通过浏览器访问您的 Phalcon 项目，您需要使用 ServBay 的 网站 功能来配置一个虚拟主机，将其指向项目的 Web 可访问目录。

1. 打开 ServBay 应用
2. 进入 『网站』 设置：在 ServBay 主界面找到并点击『网站』选项。
3. 添加新网站：点击添加网站的按钮。
   • 名称: 输入一个易于识别的名称，例如 My First Phalcon Dev Site。
   • 域名: 输入您想在浏览器中访问的域名，例如 servbay-phalcon-test.local。ServBay 会自动将 .local 域名解析到本地。
   • 网站类型: 选择 PHP。
   • PHP 版本: 选择您为项目启用了 Phalcon 模块的那个 PHP 版本。
   • 网站根目录: 这是关键步骤。Phalcon 项目的入口文件 index.php 通常位于 public 目录下。因此，您需要将网站根目录指向项目的 public 目录：/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public。
4. 保存设置：保存新的网站配置。ServBay 会自动应用更改，可能需要重启 Web 服务器（Caddy 或 Nginx）。

详细设置步骤请参考 添加第一个网站。完成配置后，ServBay 会自动处理域名的本地解析以及 Web 服务器的相应配置。

添加示例代码

让我们添加一些简单的代码来验证项目是否正常运行。

1. 配置路由

   编辑 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/config/routes.php 文件，添加一个简单的路由规则来处理根路径 / 的请求：

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   // 定义默认路由，将根路径 '/' 映射到 IndexController 的 indexAction
   $router->add(
       '/',
       [
           'controller' => 'index',
           'action'     => 'index',
       ]
   );
   
   // ... 可以添加其他路由规则 ...
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

2. 创建控制器

   编辑 /Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/app/controllers/IndexController.php 文件（如果不存在则创建），添加一个简单的 indexAction 方法：

   <?php
   namespace App\Controllers; // 确保命名空间正确
   
   use Phalcon\Mvc\Controller;
   
   class IndexController extends Controller
   {
       // 处理根路径 '/' 的请求
       public function indexAction()
       {
           // 返回一个简单的字符串作为响应
           return 'Hello ServBay!';
       }
   }

访问网站

保存所有文件后，确保 ServBay 正在运行。打开您的 Web 浏览器，访问您在 ServBay 中配置的域名：

https://servbay-phalcon-test.local

如果一切配置正确，您应该能在浏览器中看到输出 Hello ServBay!。

集成数据库

Phalcon 提供了强大的数据库抽象层和 ORM。ServBay 集成了多种数据库，您可以轻松地将它们与 Phalcon 项目集成。下面以 MySQL 和 Redis 为例。

关系型数据库示例：MySQL

我们将演示如何使用 Phalcon 的数据库适配器连接到 ServBay 的 MySQL 服务，并执行简单的插入和查询操作。

1. 创建数据库结构 (使用迁移)

   Phalcon DevTools 支持数据库迁移，这是一种管理数据库模式版本控制的常用方法。

   • 生成迁移文件: 在项目代码目录 (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app) 下运行 DevTools 命令生成一个空的迁移文件：

     vendor/bin/phalcon migration generate

     这会在 migrations 目录下创建一个新的迁移文件，文件名类似于 YYYYMMDDHHMMSS_MigrationName.php。

   • 编辑迁移文件: 打开新生成的迁移文件，编辑 morph 方法来定义一个简单的 users 表结构：

     <?php
     
     use Phalcon\Db\Column;
     use Phalcon\Db\Index;
     use Phalcon\Migrations\Mvc\Model\Migration;
     
     /**
      * Class UsersMigration_100
      */
     class UsersMigration_100 extends Migration // 文件名中的类名需要与实际文件名对应
     {
         /**
          * Run the migrations
          *
          * @return void
          */
         public function morph()
         {
             $this->morphTable('users', [
                 'columns' => [
                     new Column(
                         'id',
                         [
                             'type'          => Column::TYPE_INTEGER,
                             'autoIncrement' => true,
                             'notNull'       => true,
                             'primary'       => true,
                         ]
                     ),
                     new Column(
                         'name',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                         ]
                     ),
                     new Column(
                         'email',
                         [
                             'type'    => Column::TYPE_VARCHAR,
                             'size'    => 255,
                             'notNull' => true,
                             'unique'  => true,
                         ]
                     ),
                 ],
                 'indexes' => [
                     new Index('PRIMARY', ['id'], 'PRIMARY'),
                     new Index('email_UNIQUE', ['email'], 'UNIQUE'),
                 ],
                 'options' => [
                     'TABLE_ENGINE' => 'InnoDB',
                     'CHARACTER SET' => 'utf8mb4',
                     'COLLATE' => 'utf8mb4_unicode_ci',
                 ],
             ]);
         }
     
         /**
          * Reverse the migrations
          *
          * @return void
          */
         public function down()
         {
             // 可选：实现回滚逻辑，例如删除表
             // $this->getConnection()->dropTable('users');
         }
     }

     注意: 确保类名（UsersMigration_100）与您的迁移文件名对应。文件名通常包含时间戳和类名。

   • 运行迁移: 在项目代码目录运行 DevTools 命令来执行迁移，这将在数据库中创建 users 表：

     vendor/bin/phalcon migration run

     如果遇到连接错误，请检查 app/config/config.php 中的数据库配置以及 ServBay 中 MySQL/MariaDB 服务是否正常运行。

2. 配置数据库连接 (已在前面完成)

   确保 app/config/config.php 中 'database' 部分的配置指向 ServBay 运行的 MySQL/MariaDB 服务（默认 host 是 127.0.0.1，端口 3306，用户 root，密码根据您的设置）。

3. 添加示例路由

   编辑 app/config/routes.php 文件，添加用于插入和查询用户数据的路由：

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   // 添加用于插入用户数据的路由
   $router->add(
       '/mysql-add',
       [
           'controller' => 'index',
           'action'     => 'mysqlAdd',
       ]
   );
   
   // 添加用于查询用户数据的路由
   $router->add(
       '/mysql',
       [
           'controller' => 'index',
           'action'     => 'mysql',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. 在控制器中实现数据库操作

   编辑 app/controllers/IndexController.php 文件，添加 mysqlAddAction 和 mysqlAction 方法来执行数据库操作。这里我们直接使用 Phalcon 的数据库连接服务。

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql; // 导入 MySQL 数据库适配器
   use Phalcon\Db\Enum; // 用于 fetchAll 的模式常量
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       // 插入用户数据示例
       public function mysqlAddAction()
       {
           // 直接从服务容器获取数据库连接（如果在服务中注册了）
           // 或者像这里一样手动创建连接（不推荐在实际应用中频繁创建）
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- 请修改为您的数据库密码
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4', // 建议设置字符集
           ]);
   
           // 插入一条示例用户记录
           $success = $connection->insert(
               'users', // 表名
               ['ServBay Demo User', '[email protected]'], // 值数组
               ['name', 'email'] // 列名数组
           );
   
           // 输出操作结果
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       // 查询并显示用户数据示例
       public function mysqlAction()
       {
            // 获取数据库连接
           $connection = new Mysql([
               'host'     => '127.0.0.1',
               'username' => 'root',
               'password' => 'password', // <-- 请修改为您的数据库密码
               'dbname'   => 'servbay_phalcon_app',
               'charset'  => 'utf8mb4', // 建议设置字符集
           ]);
   
           // 查询所有用户
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
   
           // 将结果以 JSON 格式输出
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   }

   注意: 在实际应用中，推荐将数据库连接配置为服务容器中的服务，并通过依赖注入在控制器中使用，而不是在每个 Action 中手动创建连接。

5. 访问示例

   • 打开浏览器，访问 https://servbay-phalcon-test.local/mysql-add。如果成功，您会看到 "User added successfully."。
   • 然后访问 https://servbay-phalcon-test.local/mysql。您应该会看到以 JSON 格式输出的 users 表中的数据，包括刚刚添加的记录。

NoSQL 数据库示例：Redis

我们将演示如何在 Phalcon 项目中使用 ServBay 提供的 Redis 服务作为缓存。

1. 安装 Redis 扩展

   ServBay 的 PHP 软件包通常已经内置了常用的扩展，包括 Redis 扩展。您无需通过 pecl 或手动编译安装。只需确保在 ServBay 中您使用的 PHP 版本已勾选并启用了 Redis 扩展。

2. 配置 Redis 连接

   在 app/config/config.php 文件中添加 Redis 连接信息。ServBay 的 Redis 服务默认运行在 127.0.0.1 的 6379 端口。

   return new \Phalcon\Config([
       // ... 其他配置 ...
       'cache' => [
           'adapter' => 'Redis',
           'host' => '127.0.0.1',
           'port' => 6379,
           'index' => 0, // Redis 数据库索引，默认为 0
           'persistent' => false, // 是否使用持久连接
           'auth' => null, // 如果 Redis 设置了密码，在此填写
       ],
       // ... 其他配置 ...
   ]);

3. 添加示例路由

   编辑 app/config/routes.php 文件，添加一个用于演示 Redis 缓存的路由：

   <?php
   use Phalcon\Mvc\Router;
   
   $router = new Router(false);
   
   $router->add('/', [
       'controller' => 'index',
       'action'     => 'index',
   ]);
   
   $router->add('/mysql-add', [
       'controller' => 'index',
       'action'     => 'mysqlAdd',
   ]);
   
   $router->add('/mysql', [
       'controller' => 'index',
       'action'     => 'mysql',
   ]);
   
   // 添加用于演示 Redis 缓存的路由
   $router->add(
       '/redis',
       [
           'controller' => 'index',
           'action'     => 'redis',
       ]
   );
   
   $router->handle($_SERVER['REQUEST_URI']);
   
   return $router;

4. 在控制器中使用 Redis 缓存

   编辑 app/controllers/IndexController.php 文件，添加 redisAction 方法来演示如何使用 Redis 缓存：

   <?php
   namespace App\Controllers;
   
   use Phalcon\Mvc\Controller;
   use Phalcon\Db\Adapter\Pdo\Mysql;
   use Phalcon\Db\Enum;
   use Phalcon\Cache\Adapter\Redis; // 导入 Redis 缓存适配器
   use Phalcon\Storage\SerializerFactory; // 导入序列化工厂
   
   class IndexController extends Controller
   {
       public function indexAction()
       {
           return 'Hello ServBay!';
       }
   
       public function mysqlAddAction()
       {
           $connection = new Mysql([/* ... */]);
           $success = $connection->insert(/* ... */);
           echo $success ? 'User added successfully.' : 'Failed to add user.';
       }
   
       public function mysqlAction()
       {
           $connection = new Mysql([/* ... */]);
           $users = $connection->fetchAll('SELECT * FROM users', Enum::FETCH_ASSOC);
           header('Content-Type: application/json');
           echo json_encode($users);
       }
   
       // Redis 缓存示例
       public function redisAction()
       {
           // 创建序列化工厂实例
           $serializerFactory = new SerializerFactory();
   
           // 配置 Redis 缓存选项
           // 注意：这里的配置应与 app/config/config.php 中的 'cache' 部分一致
           $options = [
               'defaultSerializer' => 'Json', // 默认使用 JSON 序列化存储数据
               'lifetime'          => 3600, // 缓存有效期（秒），例如 1 小时
               'host'              => '127.0.0.1',
               'port'              => 6379,
               'index'             => 0, // Redis 数据库索引
               // 'auth'           => 'your_redis_password', // 如果设置了密码
           ];
   
           // 创建 Redis 缓存适配器实例
           $cache = new Redis($serializerFactory, $options);
   
           $cacheKey = 'my_servbay_redis_cache_key';
           $cachedData = $cache->get($cacheKey); // 尝试从缓存获取数据
   
           if ($cachedData === null) {
               // 如果缓存中没有数据
               echo "Data not found in cache, fetching from source...";
               $cachedData = 'Data fetched from source: Hello Redis from ServBay!';
               $cache->set($cacheKey, $cachedData); // 将数据存入缓存
               echo "Data stored in cache.";
           } else {
               // 如果缓存中有数据
               echo "Data found in cache: ";
           }
   
           // 返回缓存中的数据（或刚写入的数据）
           return $cachedData;
       }
   }

   注意: 在实际应用中，通常会将缓存配置为服务容器中的服务，以便在整个应用中方便地访问。

5. 访问示例

   打开浏览器，访问 https://servbay-phalcon-test.local/redis。

   • 第一次访问时，您会看到 "Data not found in cache, fetching from source...Data stored in cache." 和 "Data fetched from source: Hello Redis from ServBay!"。
   • 在缓存有效期内再次访问时，您会看到 "Data found in cache: " 和 "Data fetched from source: Hello Redis from ServBay!"，这表明数据是从 Redis 缓存中获取的。

常见问题 (FAQ)

• Q: 访问网站时出现 404 Not Found 错误怎么办？
  • A: 确保您在 ServBay 网站设置中，“网站根目录” 正确指向了您的 Phalcon 项目的 public 目录 (/Applications/ServBay/www/servbay-phalcon-app/servbay-phalcon-app/public)。同时检查 ServBay 中对应的 Web 服务器（Caddy 或 Nginx）是否正常运行，以及域名的本地解析是否成功。
• Q: 出现 Phalcon 模块未找到的错误 (Class 'Phalcon\Mvc\Application' not found 等)？
  • A: 这通常意味着 Phalcon 扩展未在您使用的 PHP 版本中启用。请回到 ServBay 界面，确保您项目使用的 PHP 版本已启用 Phalcon 扩展，并重启 PHP 服务。参考 如何启用ServBay自带的Phalcon模块。
• Q: 数据库连接失败怎么办？
  • A: 检查 app/config/config.php 中的数据库连接配置（主机、用户名、密码、数据库名）是否正确。确保 ServBay 中对应的数据库服务（如 MySQL/MariaDB）正在运行。确认数据库用户有权限连接并访问指定的数据库，且该数据库已经创建。

总结

通过 ServBay，您可以轻松地为 Phalcon 框架搭建高性能的本地开发环境。本指南演示了从创建项目骨架、配置 Web 服务器到集成 MySQL 和 Redis 数据库的基本流程。ServBay 集成的各类软件包和便捷的管理界面极大地简化了本地开发环境的配置和维护工作，让您能够更专注于 Phalcon 应用的开发本身。希望本指南能帮助您顺利开始使用 ServBay 和 Phalcon 进行高效的 Web 开发！