Phalcon

技术栈

后端框架

phpc-extensionhigh-performancemvclow-overhead

概览

Phalcon\n\nPhalcon 是一款独特的 PHP 全栈框架——以 C 语言扩展形式加载，编译后驻留内存，提供极致的执行速度和极低的资源消耗。它不依赖 Composer，是 PHP 框架中的性能冠军。\n\n### 核心特性\n\n- C 扩展架构：编译后加载，无需解释 PHP 框架代码\n- 极致性能：基准测试中远超传统 PHP 框架\n- 低开销：极少的文件和类加载，请求延迟极低\n- 全栈 MVC：完整的 ORM、模板、路由、缓存\n- Phalcon 5：支持 PHP 8.1+，全新架构\n- Volt 模板引擎：类 Twig 的高性能模板\n- 依赖注入：内建 DI 容器\n- 安全：CSRF/XSS 防护、加密组件

安装

1. 环境准备

OS：Linux / macOS
PHP：>= 8.0（Phalcon 5）
PHP 开发工具：php-dev / php-devel 包（编译扩展）
编译器：GCC / Clang + make
数据库：MySQL 5.7+ / PostgreSQL / SQLite
注意：Phalcon 以 PHP 扩展形式安装，不是 Composer 包

2. 安装命令

安装 Phalcon 扩展

Ubuntu/Debian

sudo apt install php8.2-dev gcc make libpcre3-dev
git clone https://github.com/phalcon/cphalcon.git
cd cphalcon/build
sudo ./install
# 或通过 PECL
sudo pecl install phalcon

macOS (Homebrew)

brew install phalcon

PECL（通用）

sudo pecl install phalcon

启用扩展

添加 extension=phalcon.so 到 php.ini：

echo "extension=phalcon.so" | sudo tee /etc/php/8.2/mods-available/phalcon.ini
sudo phpenmod phalcon
php -m | grep phalcon  # 验证

创建项目

composer create-project phalcon/app my-app
cd my-app

开发工具

# Phalcon DevTools（CLI 代码生成器）
composer require --dev phalcon/devtools

启动服务器

php -S localhost:8080 -t public/ .htrouter.php

3. 常见安装问题

编译失败

确保 PHP 开发包版本与运行时一致：

php -v          # 如 8.2.15
phpize -v       # 确保版本匹配

PECL 安装失败

# 手动编译
git clone --single-branch --branch=v5.x https://github.com/phalcon/cphalcon.git
cd cphalcon/build
sudo ./install

共享主机不支持

Phalcon 需要服务器安装 C 扩展。共享主机通常不支持，需 VPS 或云服务器。

Windows 用户

下载预编译 DLL：https://github.com/phalcon/cphalcon/releases

示例

Hello World - MVC 控制器.md

Hello World：Phalcon 5 MVC 控制器

目标

创建 Phalcon 5 控制器，展示 MVC 路由和 JSON API 端点。

完整代码

1. 路由配置 public/index.php

<?php

use Phalcon\Autoload\Loader;
use Phalcon\Mvc\Application;
use Phalcon\Di\Di;
use Phalcon\Mvc\Router;

// 自动加载
$loader = new Loader();
$loader->setDirectories(['../app/controllers/']);
$loader->register();

// DI 容器
$di = new Di();

$di->set('router', function () {
    $router = new Router();
    $router->add('/hello', ['controller' => 'hello', 'action' => 'index']);
    $router->add('/hello/{name}', ['controller' => 'hello', 'action' => 'greet']);
    return $router;
});

$di->set('response', function () {
    return new \Phalcon\Http\Response();
});

$app = new Application($di);
$app->handle($_SERVER['REQUEST_URI'])->send();

2. 控制器 app/controllers/HelloController.php

<?php

use Phalcon\Http\Response;
use Phalcon\Mvc\Controller;

class HelloController extends Controller
{
    /**
     * GET /hello — JSON API 端点
     */
    public function indexAction(): Response
    {
        return $this->response
            ->setContentType('application/json')
            ->setJsonContent([
                'message' => 'Hello, Vibe!',
                'framework' => 'Phalcon',
                'php_version' => PHP_VERSION,
                'timestamp' => date('c'),
            ]);
    }

    /**
     * GET /hello/{name} — 带参数端点
     */
    public function greetAction(string $name): Response
    {
        return $this->response
            ->setContentType('application/json')
            ->setJsonContent([
                'message' => "Hello, {$name}!",
                'powered_by' => 'Phalcon Framework',
            ]);
    }

    /**
     * 原生视图渲染
     */
    public function viewAction(): Response
    {
        $this->view->message = 'Hello from Phalcon View!';
        $this->view->framework = 'Phalcon';
        // 渲染 app/views/hello/view.phtml
        return $this->response;
    }
}

3. 视图 app/views/hello/view.phtml

<!DOCTYPE html>
<html>
<head><title>Phalcon Hello</title></head>
<body>
    <h1><?= $message ?></h1>
    <p>Powered by <strong><?= $framework ?></strong></p>
    <p>PHP <?= PHP_VERSION ?></p>
</body>
</html>

运行步骤

php -S localhost:8080 -t public/ .htrouter.php

预期输出

curl http://localhost:8080/hello
# {"message":"Hello, Vibe!","framework":"Phalcon","php_version":"8.2.15","timestamp":"..."}

curl http://localhost:8080/hello/Vibe
# {"message":"Hello, Vibe!","powered_by":"Phalcon Framework"}

# 浏览器访问 http://localhost:8080/hello/view
# 渲染 HTML 视图

注意：Phalcon 路由匹配不同于传统框架，需在 .htrouter.php 中处理重写规则。`

教程

入门篇 - RESTful API 实战.md

Phalcon 入门教程：RESTful API 实战

1. 背景

Phalcon 以 C 扩展形式提供极致性能。本教程带你构建 RESTful Product API，掌握 Phalcon 的 MVC 模式、模型和验证。

2. 前置概念

概念	说明
DI 容器	Phalcon 依赖注入是框架的核心
Loader	Phalcon 的 PSR-4 自动加载器
Model	ORM 模型，连接数据库
Validation	内置验证器链

3. 分步操作

步骤一：项目结构

my-api/
├── public/
│   └── index.php
├── app/
│   ├── controllers/
│   │   └── ProductController.php
│   ├── models/
│   │   └── Product.php
│   ├── config/
│   │   └── config.php
│   └── migrations/
└── .htrouter.php

步骤二：入口文件 `public/index.php`

<?php

use Phalcon\Autoload\Loader;
use Phalcon\Di\Di;
use Phalcon\Mvc\Application;
use Phalcon\Mvc\Router;
use Phalcon\Db\Adapter\Pdo\Mysql;
use Phalcon\Mvc\Model\Manager as ModelsManager;

$loader = new Loader();
$loader->setDirectories(['../app/controllers/', '../app/models/']);
$loader->register();

$di = new Di();

// 数据库
$di->set('db', function () {
    return new Mysql([
        'host' => 'localhost',
        'username' => 'root',
        'password' => '',
        'dbname' => 'phalcon_api',
    ]);
});

// 路由
$di->set('router', function () {
    $router = new Router();
    $router->add('/api/products', [
        'controller' => 'product',
        'action' => 'list',
    ])->via(['GET']);
    $router->add('/api/products', [
        'controller' => 'product',
        'action' => 'create',
    ])->via(['POST']);
    $router->add('/api/products/{id}', [
        'controller' => 'product',
        'action' => 'show',
    ])->via(['GET']);
    $router->add('/api/products/{id}', [
        'controller' => 'product',
        'action' => 'update',
    ])->via(['PUT']);
    $router->add('/api/products/{id}', [
        'controller' => 'product',
        'action' => 'delete',
    ])->via(['DELETE']);
    return $router;
});

$di->set('modelsManager', new ModelsManager());

$app = new Application($di);
$app->handle($_SERVER['REQUEST_URI'])->send();

步骤三：Model `app/models/Product.php`

<?php

use Phalcon\Mvc\Model;

class Product extends Model
{
    public int $id;
    public string $name;
    public float $price;
    public string $category;
    public int $stock;

    public function initialize()
    {
        $this->setSource('products');
    }
}

步骤四：Controller `app/controllers/ProductController.php`

<?php

use Phalcon\Http\Response;
use Phalcon\Mvc\Controller;

class ProductController extends Controller
{
    public function listAction(): Response
    {
        $products = Product::find();
        return $this->response
            ->setContentType('application/json')
            ->setJsonContent($products->toArray());
    }

    public function createAction(): Response
    {
        $data = $this->request->getJsonRawBody(true);

        $product = new Product();
        $product->name = $data['name'];
        $product->price = $data['price'];
        $product->category = $data['category'] ?? '';
        $product->stock = $data['stock'] ?? 0;

        if ($product->save()) {
            return $this->response
                ->setContentType('application/json')
                ->setStatusCode(201)
                ->setJsonContent(['message' => 'Product created', 'id' => $product->id]);
        }

        return $this->response
            ->setContentType('application/json')
            ->setStatusCode(422)
            ->setJsonContent(['errors' => $product->getMessages()]);
    }

    public function showAction(int $id): Response
    {
        $product = Product::findFirst($id);
        if (!$product) {
            return $this->response->setStatusCode(404)->setJsonContent(['error' => 'Not found']);
        }
        return $this->response->setContentType('application/json')->setJsonContent($product->toArray());
    }

    public function updateAction(int $id): Response
    {
        $product = Product::findFirst($id);
        if (!$product) {
            return $this->response->setStatusCode(404)->setJsonContent(['error' => 'Not found']);
        }

        $data = $this->request->getJsonRawBody(true);
        $product->assign($data, ['name', 'price', 'category', 'stock']);
        $product->save();

        return $this->response->setContentType('application/json')->setJsonContent($product->toArray());
    }

    public function deleteAction(int $id): Response
    {
        $product = Product::findFirst($id);
        if ($product) {
            $product->delete();
            return $this->response->setStatusCode(204);
        }
        return $this->response->setStatusCode(404)->setJsonContent(['error' => 'Not found']);
    }
}

步骤五：数据库

CREATE TABLE products (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(128) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    category VARCHAR(64),
    stock INT DEFAULT 0
);

4. 验证

php -S localhost:8080 -t public/ .htrouter.php

curl -X POST http://localhost:8080/api/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Phalcon Book","price":29.99,"category":"Books","stock":100}'

curl http://localhost:8080/api/products

5. 思考题

Phalcon 的 ORM 和独立 Eloquent 有什么区别？
如何利用 Phalcon 的 C 扩展特性实现缓存优化？
如何在 Phalcon 中实现 JWT 认证中间件？

参考资料

[1] Phalcon Team. Phalcon Documentation. Phalcon Docs, 2026. https://docs.phalcon.io/
[2] Phalcon Team. Phalcon Framework Official Site. phalcon.io, 2026. https://phalcon.io/en-us
[3] Phalcon Team. Phalcon GitHub Organization. GitHub, 2026. https://github.com/phalcon
[4] Phalcon Team. cphalcon GitHub Repository. GitHub, 2026. https://github.com/phalcon/cphalcon/
[5] Phalcon Team. Official Phalcon Documentation Repository. GitHub, 2026. https://github.com/phalcon/documentation
[6] Phalcon Team. Phalcon Releases. GitHub Releases, 2026. https://github.com/phalcon/cphalcon/releases
[7] PHP Extension Community Library. Phalcon PECL Package. PECL, 2026. https://pecl.php.net/package/phalcon
[8] Phalcon Documentation Contributors. Phalcon PHP Read the Docs Mirror. Read the Docs, 2026. https://php-phalcon-docs.readthedocs.io/
[9] Phalcon Team. INVO sample application for Phalcon. GitHub, 2026. https://github.com/phalcon/invo
[10] Phalcon Team. Phalcon Developer Tools. GitHub, 2026. https://github.com/phalcon/phalcon-devtools
[11] Calin Rada. Learning Phalcon PHP. Packt Publishing / Google Books, 2015. https://books.google.com/books/about/Learning_Phalcon_PHP.html?id=EKOECgAAQBAJ
[12] David Schissler, Serghei Iakovlev. Phalcon Cookbook. Packt Publishing, 2015. https://www.amazon.com/Phalcon-Cookbook-David-Schissler/dp/1784396885
[13] Stephan Miller. Getting Started with Phalcon. Packt Publishing, 2014. https://www.stephanmiller.com/so-i-wrote-a-book-on-the-phalcon-framework/
[14] IEEE Authors. Empirical Study of Most Popular PHP Framework. IEEE Xplore, 2021. https://ieeexplore.ieee.org/document/9491679/
[15] Natalya Prokofyeva, Victoria Boltunova. Analysis and Practical Application of PHP Frameworks in Development of Web Information Systems. ResearchGate / Procedia Computer Science, 2017. https://www.researchgate.net/publication/313488649_Analysis_and_Practical_Application_of_PHP_Frameworks_in_Development_of_Web_Information_Systems
[16] Carlos Perez Sanchez, Pablo Solar Vilarino. PHP Microservices. Packt / O'Reilly Learning, 2017. https://www.oreilly.com/library/view/php-microservices/9781787125377/pr01.html
[17] PHP Documentation Group. PHP Manual. PHP.net, 2026. https://www.php.net/manual/en/
[18] PHP Internals Contributors. PHP Internals Book. phpinternalsbook.com, 2026. https://www.phpinternalsbook.com/
[19] Composer Team. Composer Documentation. Composer Docs, 2026. https://getcomposer.org/doc/
[20] PHP-FIG. PHP Standards Recommendations. PHP-FIG, 2026. https://www.php-fig.org/psr/

概览

安装