# Phalcon (cphalcon): a full-stack PHP framework shipped as a C extension

> Phalcon is a PHP framework delivered as a compiled extension rather than a library of PHP files. This review covers how it installs through PIE, what the Zephir/C build implies for upgrades, and when a plain PHP framework is the better choice.

**phalcon/cphalcon** — High performance, full-stack PHP framework delivered as a C extension.

- Repository: https://github.com/phalcon/cphalcon
- Website: https://phalcon.io
- Stars: 10,821 · Forks: 1,932
- Language: PHP
- License: BSD-3-Clause
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/phalcon-cphalcon

## What Phalcon solves, and who it is for

Phalcon is an open-source web framework delivered as a C extension for PHP, described in the README as providing high performance and lower resource consumption. The distinction that matters is packaging. Most PHP frameworks are Composer packages: the framework classes are PHP source files that get parsed and compiled on every request unless an opcache holds them. Phalcon's classes are compiled into a shared library that PHP loads once at startup, so the framework itself is not part of the per-request source tree.

The intended audience is teams running their own PHP runtime: a VM, a container image, or a server where they can install a PHP extension. If your deployment is a shared host that only accepts uploaded files, the model does not fit. The repository is not archived and the last push was on 2026-09-21, with v5.21.0 released on 2026-09-18, so the 5.x line is receiving releases. That says nothing about whether the API surface you depend on is stable across minor versions; the changelog files are where that question gets answered.

## How a C-extension framework actually loads

Phalcon is written in Zephir/C, according to the README, which is why the project can target Microsoft Windows, GNU/Linux, FreeBSD and macOS from one codebase. Zephir is a language that compiles down to C, and the C is then built into the extension that PHP loads. The practical consequence is a two-stage pipeline: framework source in the phalcon/ directory, build configuration in build/ and config.json, and a compiled artifact installed into the PHP extension directory.

That shape determines the upgrade path. A Composer framework upgrade is a dependency resolution step inside the application. A Phalcon upgrade is a change to the runtime that hosts the application, which means the extension version, the PHP version and the application code all have to agree. The repository carries CHANGELOG.md and CHANGELOG-5.0.md for tracking what moved between releases, and the ext/ directory holds the extension-level sources. The docker-compose.yml file confirms the maintenance burden directly: it defines separate development services for PHP 8.1, 8.2, 8.3, 8.4 and 8.5, each built from resources/docker/develop/Dockerfile with a PHP_VERSION build argument. One service per PHP version is a reasonable developer convenience and also an honest picture of what supporting the extension costs.

## Installing Phalcon with PIE and running a request

The README recommends PIE, described there as the modern PHP extension installer. The command is a single line, and the README gives it exactly as follows:

```bash
pie install phalcon/cphalcon
```

After that completes, the extension should be present in your PHP installation; the README does not reproduce the php.ini line, so confirm the extension is loaded with php -m or php -i before writing application code.

PECL still works, but the README marks it as deprecated and says users should switch to PIE, with releases continuing on PECL until PECL is retired or v5.x reaches end of life. The PECL form is:

```bash
pecl install phalcon
```

If neither installer suits your environment, the README points to the installation page in the documentation at docs.phalcon.io for building from source. It does not list the build prerequisites inline, so treat the docs as the source of truth for compiler and dependency requirements rather than guessing from the repository layout.

The repository also documents a documentation-generation script that is useful if you are working against a specific tag:

```bash
php bin/generate-api-docs.php
```

The README states that this produces *.md files containing the API documentation, and that publishing to the Phalcon website uses a separate docs repository. Running it against a checked-out tag is the way to read API docs that match the version you installed rather than the current master.

## The build matrix is the real cost of adoption

The docker-compose.yml is labelled as being for local development only, and it is the clearest statement of the constraint. Each service pins a PHP_VERSION build argument and shares the repository into /srv. Five PHP versions means five build targets to keep working. In production, the equivalent question is how many PHP versions your fleet runs and whether every one of them has a Phalcon build you can install.

This is where the framework differs from a Composer dependency in a way that is not about speed. If a security fix lands in the extension, it has to be rebuilt and redeployed across every PHP version in the fleet, and the application cannot patch around it by pinning a different package version. The README does not document rollback, and the repository material does not describe a rollback procedure for a bad extension build, so plan for that gap before you need it. The same applies to local development: a contributor working on the framework needs the Docker services or a working Zephir/C toolchain, not just a PHP binary.

## Phalcon or a plain-PHP framework like Symfony

The comparison people reach for is Phalcon against Symfony, and the difference is architectural rather than stylistic. Symfony is a set of PHP packages installed through Composer and loaded like any other PHP code; the framework lives inside the application's vendor directory and moves with it. Phalcon lives in the PHP process. That means Symfony can be deployed by uploading files and running composer install, and its version is pinned per application in composer.json. Phalcon's version is pinned per runtime.

The trade-offs run in both directions. A Composer framework can be upgraded on one application without touching the server, and two applications on the same server can run different framework versions. Phalcon cannot do that without separate PHP builds, and in exchange the framework code is not part of the request's source parsing. The README's own framing is performance and resource consumption, not feature parity, and that is the right way to read the choice: pick Phalcon when the runtime is yours to control and the resource profile matters, and pick a Composer-based framework when deployment flexibility matters more.

## Licence and what upgrades commit you to

Phalcon is licensed under the BSD 3-Clause License, copyright 2011-present, Phalcon Team, with the full text in LICENSE.txt. The README notes that additional licences for packages Phalcon uses, is inspired by, or has adapted are located in the 3rdparty/licenses directory. If you redistribute a product that embeds the extension, that directory is the place to read before you ship; this is a description of what the repository contains, not legal advice.

Upgrade cost follows from the packaging. Moving between 5.x releases means rebuilding or reinstalling the extension and then checking the application against the changelog. The repository keeps CHANGELOG.md and CHANGELOG-5.0.md, and the release history shows patch releases such as v5.20.2 and v5.20.3 arriving close together in August 2026, followed by v5.21.0 in September 2026. Frequent patch releases are normal for a project of this age; what matters for planning is that each one is an extension install, not a Composer update, so your deployment pipeline needs a step that can install a PHP extension. If it cannot, the upgrade will be manual.

## Conclusion

Adopt Phalcon when you control the PHP runtime, accept a compiled extension in your deployment pipeline, and want the framework loaded as part of PHP itself. Do not adopt it if your hosting gives you only a filesystem and a composer.json, or if your team cannot rebuild an extension whenever PHP moves. Before committing, verify that pie install phalcon/cphalcon resolves for your exact PHP version, and check the CHANGELOG-5.0.md entries between your current tag and the target tag for breaking changes.

## FAQ

### How do I install Phalcon?

The README recommends PIE and gives the command pie install phalcon/cphalcon. PECL also works with pecl install phalcon, but the README marks PECL as deprecated and says users should switch to PIE. Building from source is covered on the installation page in the documentation.

### What is Phalcon written in?

The README states that Phalcon is written in Zephir/C with platform independence in mind, which is why it is available on Microsoft Windows, GNU/Linux, FreeBSD and macOS. The compiled result is a PHP extension rather than a set of PHP source files.

### Is Phalcon a full-stack PHP framework?

The repository describes Phalcon as an open-source web framework delivered as a C extension for PHP. The README frames the benefit as high performance and lower resource consumption rather than listing components, so check the documentation for the specific features you need.

### What licence does Phalcon use?

Phalcon is open-source software licensed under the BSD 3-Clause License, copyright 2011-present, Phalcon Team, with the text in LICENSE.txt. The README also points to the 3rdparty/licenses directory for licences of packages Phalcon uses, is inspired by, or has adapted.

### Which PHP versions does the Phalcon repository build against?

The docker-compose.yml, which is marked for local development only, defines separate development services for PHP 8.1, 8.2, 8.3, 8.4 and 8.5, each built from resources/docker/develop/Dockerfile with a PHP_VERSION build argument. That reflects the development matrix, not a published support guarantee.

## Sources

- [License: BSD-3-Clause](https://github.com/phalcon/cphalcon/blob/master/LICENSE)
- [phalcon/cphalcon on GitHub](https://github.com/phalcon/cphalcon)
- [Project website](https://phalcon.io)
- [README](https://github.com/phalcon/cphalcon/blob/master/README.md)
- [Releases](https://github.com/phalcon/cphalcon/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/phalcon-cphalcon