Phalcon is one of the most powerful and performance-centric PHP frameworks available today. Unlike traditional PHP frameworks that rely on PHP source files and namespaces, Phalcon is installed as a C-extension directly into the PHP environment. This unique design gives it exceptional speed and memory efficiency. However, because Phalcon is not installed like a typical PHP library through Composer or manual project-level file placement, developers often need to verify that the extension is properly enabled in the server’s PHP configuration.

This article explores in approximately every detail of checking whether Phalcon is installed, how to validate its configuration, how to troubleshoot issues, and how to ensure your PHP-FPM or Apache/Nginx environment recognizes the extension. Whether you are new to Phalcon or a server administrator working with multiple PHP versions, this guide walks you through every aspect of confirming the installation.

1. Introduction Why Checking Phalcon Installation Matters

Before you launch a Phalcon application into development or production, you must ensure the extension is actually loaded in PHP. Since Phalcon operates at the extension level, if PHP cannot detect the module, the framework will not function at all. Unlike Laravel, Symfony, or CodeIgniter, which consist of application-level classes, Phalcon is deeply integrated into PHP’s core runtime. This makes verifying installation not just helpful—but absolutely essential.

When the extension is correctly installed, it becomes visible inside the PHP modules list. If it does not appear, your application will generate errors such as:

Class ‘Phalcon\Mvc\Application’ not found
Unable to load dynamic library: phalcon.so
Unknown extension phalcon in unknown on line 0

These errors clearly indicate that PHP cannot detect the extension.

Therefore, one of the simplest and most reliable ways to confirm the installation is by running the following command:

php -m | grep phalcon

If the output shows the word phalcon, then the extension has been successfully loaded into your environment.

But this is only the beginning. A thorough verification requires several additional checks—configuration, PHP-FPM pools, version compatibility, environment variables, and more. This article dives deeply into all of these areas.

2. Understanding How Phalcon Works Inside PHP

Before verifying installation, it helps to understand how Phalcon interacts with PHP.

2.1 Phalcon as a Shared Library

Phalcon is not a normal PHP package. Instead, it is compiled into a shared object file (phalcon.so on Linux and macOS, php_phalcon.dll on Windows). This file must be placed in your PHP extension directory.

2.2 Loaded via php.ini or mods-enabled

To activate the extension, PHP reads configuration files such as:

/etc/php.ini
/etc/php.d/phalcon.ini
/etc/php/8.1/mods-available/phalcon.ini
/usr/local/etc/php/conf.d/phalcon.ini

Inside these files, the extension is loaded like this:

extension=phalcon.so

If the entry is missing or incorrect, PHP won’t load Phalcon.

2.3 PHP-FPM vs CLI Environments

It’s important to note that:

Running php -m checks the CLI environment.
PHP-FPM may use a different php.ini.
Apache with mod_php may use yet another configuration.

Thus, confirming installation requires checking both CLI and server runtimes.

3. The Primary Method: Using `php -m | grep phalcon`

3.1 What the Command Does

The command:

php -m | grep phalcon

performs two actions:

php -m lists all loaded PHP modules.
grep phalcon filters the results to only show lines containing “phalcon”.

If Phalcon is installed correctly, the output will simply be:

phalcon

If nothing appears, the extension is not loaded.

3.2 Why This Method Is Reliable

This command queries the modules that PHP has actually loaded at runtime. It’s not checking your configuration files—it’s checking the active runtime environment, which is the most accurate source of truth.

4. Alternative Commands to Confirm Installation

Although the primary command is the most common, several other commands help verify and troubleshoot the installation. Here are detailed explanations of each.

4.1 Using `php --ri phalcon`

Running:

php --ri phalcon

will display detailed information about the extension, such as:

Version
Author
Build date
Directive settings
Configuration values

Example output:

phalcon

Phalcon Framework => enabled
Version => 5.0.0
Author => Phalcon Team

If the extension isn’t installed, you’ll receive:

Extension 'phalcon' not present.

This method is useful for retrieving version and meta information.

4.2 Using `php -v` to See Loaded Configuration Files

Sometimes Phalcon is installed correctly, but PHP reads a different php.ini file.

Use:

php -v

This will show something like:

PHP 8.1.2 (cli) (built: ...)
Configuration File (php.ini) Path: /etc/php/8.1/cli
Loaded Configuration File: /etc/php/8.1/cli/php.ini

If Phalcon is enabled in a different file path (e.g., PHP-FPM config), PHP CLI won’t see it.

4.3 Using `locate phalcon.so`

If you’re unsure whether Phalcon is installed anywhere on the system:

sudo updatedb
locate phalcon.so

This command finds the file itself. If no results appear, the extension is not installed at all.

4.4 Checking Loaded Extensions via PHP Script

Create a file named info.php in your web server directory:

<?php phpinfo(); ?>

Open it in the browser:

http://localhost/info.php

Search for “phalcon” in the output. If present, it confirms installation for the web server PHP service (Apache or PHP-FPM), not just CLI.

5. Step-by-Step Verification for All Environments

Since PHP can run under multiple modes, each environment must be checked separately.

5.1 Step 1: Check CLI Environment

Run:

php -m | grep phalcon

If the extension loads, this confirms CLI usage is correct.

5.2 Step 2: Check PHP-FPM

PHP-FPM often loads its configuration files from:

/etc/php/8.x/fpm/php.ini
/etc/php-fpm.d/*.conf
/etc/php-fpm.conf

To check the version used by FPM:

php-fpm -i | grep phalcon

Alternatively:

systemctl restart php8.1-fpm
php-fpm -m | grep phalcon

If Phalcon is missing here, your CLI and FPM configurations differ.

5.3 Step 3: Check Apache (If Using mod_php)

If you’re using Apache with mod_php, test using a phpinfo() script via web browser.

Apache may use:

/etc/php/8.x/apache2/php.ini

Thus, enabling Phalcon in CLI does not automatically enable it in Apache.

5.4 Step 4: Confirm the Extension Is Enabled in INI Files

Search for all ini files:

grep -R "phalcon" /etc/php /etc/php.d /usr/local/etc/php

You should see a file like:

/etc/php/8.1/mods-available/phalcon.ini:extension=phalcon.so

If missing, create it manually.

6. Troubleshooting If Phalcon Does Not Appear

If the command does not return any output, the extension is not active. Here are the possible issues.

6.1 Missing Extension File

Run:

php --ini

Find your extension directory:

extension_dir => /usr/lib/php/20210902

Check if Phalcon exists:

ls /usr/lib/php/20210902/phalcon.so

If missing, reinstall Phalcon.

6.2 Incorrect Extension Name

Make sure your ini file uses:

extension=phalcon.so

Not:

extension=php_phalcon.dll
extension=phalcon
ext=phalcon.so

6.3 Wrong PHP Version Compatibility

Each PHP version requires a unique Phalcon build.

For example:

PHP 7.4 requires Phalcon 4.x
PHP 8.1 requires Phalcon 5.x
PHP 8.2 requires compatible updates

If versions mismatch, the extension will not load.

6.4 PHP-FPM Not Restarted

Always restart services:

sudo systemctl restart php8.1-fpm
sudo systemctl restart nginx

Failing to do so means PHP-FPM will continue using outdated configurations.

6.5 Multiple PHP Versions Installed

Systems may have:

PHP 7.4 CLI
PHP 8.0 FPM
PHP 8.1 Apache module

You must ensure the extension is enabled for the correct PHP version.

7. Detailed Explanation of `php -m` and Why It Matters

The php -m command is a powerful diagnostic tool. Understanding it helps ensure your PHP environment is configured correctly.

7.1 What `php -m` Actually Does

Loads PHP in command-line mode.
Reads configuration files.
Loads all extensions.
Outputs them alphabetically.

This includes:

Built-in modules (Core, PDO, Spl, etc.)
Zend extensions (Opcache)
Shared extensions (Phalcon, Redis, Xdebug)

7.2 Why We Pipe Through `grep`

grep filters results. Without it, you would see:

[PHP Modules]
bcmath
calendar
ctype
curl
phalcon
pdo
pdo_mysql

[Zend Modules]
Opcache

Piping makes the result clear.

8. Best Practices for Verifying Phalcon Installation

To ensure long-term stability:

8.1 Always Check Both CLI and FPM

Example:

php -m | grep phalcon
php-fpm -m | grep phalcon

8.2 Document Your Extension Loading Files

Keep notes on whether Phalcon is enabled in:

/etc/php.d/phalcon.ini
/etc/php/8.x/mods-available/phalcon.ini
/usr/local/etc/php/conf.d/phalcon.ini

8.3 Use Version Control for Server Configurations

Track ini files in Git if possible.

8.4 Avoid Mixing PHP Versions

Always use:

update-alternatives --config php

to select a unified version.

9. Advanced Techniques for Verification

For expert users, there are more advanced checks available.

9.1 Using `strace` to See Loaded Modules

strace php -m 2>&1 | grep phalcon

This confirms if PHP attempts to load the file.

9.2 Using `nm` to Inspect the Binary

nm phalcon.so | grep phalcon

This confirms symbols within the extension.

9.3 Using Docker Container Debugging

docker exec -it myphpcontainer php -m | grep phalcon

10. Examples of Common Output Scenarios

Below are possible scenarios and what they mean.

Scenario 1: Output Shows “phalcon”

phalcon

✔ Success.

Scenario 2: No Output

Output:

(blank)

Indicates:

Not installed
Not enabled
Wrong ini
Wrong PHP version

Scenario 3: Warning Messages

PHP Warning: Module 'phalcon' already loaded in Unknown on line 0

Means duplication in ini files.

Scenario 4: Fatal Error

PHP Warning: Unable to load dynamic library 'phalcon.so'

Possible issues:

Wrong version
Wrong architecture
Missing dependencies

Checking if Phalcon Is Installed