Skip to content

Upgrade Guide

Upgrading to V6

So you have decided to upgrade to v6! Congratulations!!

Phalcon v6 contains a near identical code with v5, to make the upgrade process as simple and painless as possible.

There are a couple of areas that have been reworked and changed that you should be aware of - and if you do not use that functionality, the upgrade can be a simple composer require command, after you remove the Phalcon v5 extension.

Requirements

PHP 8.1

Phalcon v6 has the same requirements as v5. PHP 8.1 active support has already expired, including security fixes. We will be supporting this version for a while longer, offering developers more time to upgrade their applications.

Since Phalcon 4, we have been following the PHP releases and adjusting Phalcon accordingly to work with those releases.

Installation

Remove Phalcon v5 before you install Phalcon v6. See Remove Phalcon v5.

Phalcon can be installed using composer.

composer require phalcon/phalcon

Upgrading from v5 to v6

Phalcon v6 has the same classes and methods as Phalcon v5. The changes below can affect your application.

Mvc View

Template Variables in Partials

In Phalcon v5 and v6, these rules apply to the variables of the templates:

  • A variable that the view of the action sets is visible in the layout.
  • A variable that a template sets is visible in a partial without parameters that the template calls after it sets the variable.
  • A variable that a partial without parameters sets is visible in the template that called the partial, after the call.
  • A partial with an array of parameters gets a new set. The set has only the variables of the view and the parameters of the partial. The variables that this partial sets are not visible in the template that called it.
  • Each render starts with a new set. A variable that a template sets in one render is not visible in the next render.
  • All the template engines of a view use the same set. For example, a variable that a Volt template sets is visible in a .phtml partial.

Phalcon v6 is written in PHP, and PHP runs each template in its own scope. When a template ends, Phalcon v6 copies the variables of the template to the set of the render. The layout and the other templates that the view renders after the template can then use these variables. Two cases need an additional call in v6:

  • A partial does not get the variables that the calling template set or changed before the call. To give these variables to the partial, call withScope(get_defined_vars()) before partial().
  • The calling template does not get the variables that the partial set. To get these variables, call extract($this->getScope()) after partial().

In v6, these variables are available without an additional call:

  • The variables that your controller sets with setVar() or setVars() of the view.
  • The variables in the $params array of partial().
  • The variables that a template sets, in the templates that the view renders after this template ends, in the same render. For example, the layout can use the variables that the view of the action sets.

Volt

Volt templates do not need a change. For partial() and {% include %}, the Volt compiler adds the withScope() call before the partial and the extract() call after it, where it is necessary. In this example, partials/header.volt can use title, and the template can use subtitle after the call if partials/header.volt sets it:

{% set title = 'Invoices' %}
{{ partial('partials/header') }}
{{ subtitle }}

A partial with an array of parameters, for example {{ partial('partials/header', ['page': 1]) }}, does not get title, and the variables that it sets are not visible after the call. This is the same in v5 and v6.

The templates that Phalcon v5 compiled do not have these calls. Remove the compiled templates after the upgrade, so that the compiler makes them again.

PHP Templates

A .phtml template needs a change in two cases only.

In the first case, the template sets or changes a variable, and then calls $this->partial() for a partial that uses this variable. Call withScope(get_defined_vars()) before partial():

<?php $title = 'Invoices'; ?>

<!-- v5 -->
<?php $this->partial('partials/header'); ?>

<!-- v6 -->
<?php $this->withScope(get_defined_vars())->partial('partials/header'); ?>

Without the withScope() call, partials/header.phtml does not get $title in v6. If an earlier template of the same render set $title, the partial gets the value from that template.

In the second case, the template uses a variable that the partial sets. Call extract($this->getScope()) after partial(). In this example, partials/totals.phtml sets $total:

<!-- v5 -->
<?php $this->partial('partials/totals'); ?>
<?= $total ?>

<!-- v6 -->
<?php
$this->partial('partials/totals');
extract($this->getScope());
?>
<?= $total ?>

If both cases apply, call withScope() before the partial and extract() after it:

<?php
$this->withScope(get_defined_vars())->partial('partials/header');
extract($this->getScope());
?>

withScope(), getScope() and setScope()

The variables that the templates share are one set for each view. All the template engines of the view use this set.

Phalcon\Mvc\View\Engine\AbstractEngine::withScope(array $scope): static adds the variables in $scope to the set of the view. A variable in $scope replaces the variable with the same name in the set. The method returns the engine. Thus, you can call partial() on the result.

  • Phalcon v5 does not have withScope(). On v5, a template that calls it stops with the error Call to undefined method.
  • partial() has the same signature as in v5. A class that extends AbstractEngine and overrides partial() does not need a change.
  • getScope(): array returns the set of the view, and setScope(array $scope): static replaces it. Phalcon\Mvc\View and Phalcon\Mvc\View\Simple use these methods to start a new set for each render and for each partial with an array of parameters. Phalcon v5 does not have these methods.

Remove Phalcon v5

Phalcon v5 is a PHP extension that is written in C. Phalcon v6 is a Composer package that is written in PHP. The two versions use the same Phalcon namespace and the same class names.

PHP loads the classes of an extension when PHP starts. The Composer autoloader loads a class only when PHP does not have that class. Thus, if the v5 extension is loaded, PHP uses the v5 classes, and Composer does not load the v6 classes that have the same names. Your application then runs a mix of v5 and v6 code. PHP does not show an error or a warning for this condition.

The procedure has five steps:

  1. Find the extension.
  2. Remove the extension with the tool that you used to install it.
  3. Remove the INI entries.
  4. Restart PHP.
  5. Make sure that PHP does not load the extension.

Step 1: Find the Extension

Run this command to see if the CLI loads Phalcon:

php --ri phalcon

If the extension is loaded, the output shows the Phalcon version and its settings. If the extension is not loaded, the output is:

Extension 'phalcon' not present.

The CLI and the web server can use different INI files. Thus, also do a check of the web server. For PHP-FPM, change the version in the command to agree with your installation:

php-fpm8.3 -m | grep -i phalcon

For other web servers, look for phalcon in the output of phpinfo().

Get the list of INI files that PHP reads:

php --ini

Get the folder that contains the extension file (phalcon.so, or php_phalcon.dll on Windows):

php -r 'echo ini_get("extension_dir"), PHP_EOL;'

Step 2: Remove the Extension

Use the instructions for the method that you used to install Phalcon v5. If you do not know the method, use the commands that list the installed packages (pie show, pecl list, dpkg -l, rpm -qa, brew list). If no tool shows Phalcon, use the instructions in Compiled From Source.

PIE
pie uninstall phalcon/cphalcon

PIE disables the extension and removes it. The command can ask for your password, because it can need elevated privileges.

To select a PHP version, add the --with-php-config option:

pie uninstall --with-php-config=/usr/bin/php-config8.3 phalcon/cphalcon

To see the extensions that PIE installed, run pie show.

PECL
sudo pecl uninstall phalcon

PECL deletes the extension file. PECL does not always remove the extension=phalcon.so line from the INI files. Do step 3 to remove it.

Linux Packages

Debian and Ubuntu (Ondřej Surý repository):

dpkg -l | grep -i phalcon
sudo apt-get purge php-phalcon5

Change php-phalcon5 to the package names that the first command shows. The purge command also removes the INI files of the package.

RPM based distributions (Remi repository):

rpm -qa | grep -i phalcon
sudo dnf remove php80-php-phalcon5

Change php80-php-phalcon5 to the package names that the first command shows. On old systems, use yum instead of dnf.

FreeBSD
pkg info | grep -i phalcon
sudo pkg delete php80-phalcon5

Change php80-phalcon5 to the package name that the first command shows. If you installed Phalcon from ports, use these commands:

cd /usr/ports/www/phalcon5
sudo make deinstall
macOS

Homebrew:

brew list | grep -i phalcon
brew uninstall phalcon
brew untap phalcon/extension

Change phalcon to the formula name that the first command shows.

MacPorts:

port installed | grep -i phalcon
sudo port uninstall php80-phalcon

Change php80-phalcon to the port name that the first command shows. Then do step 3 to remove the extension=php_phalcon.so line from php.ini.

PHPBrew
phpbrew ext disable phalcon

Then delete the extension file. Use the instructions in Compiled From Source.

Windows
  1. Delete php_phalcon.dll from the ext folder of your PHP installation.
  2. Remove the extension=php_phalcon.dll line from php.ini.
  3. Restart your web server.
Docker

Remove the lines that install or enable Phalcon v5 from your Dockerfile. These lines are similar to:

RUN pie install phalcon/cphalcon
RUN pecl install phalcon && docker-php-ext-enable phalcon

If your base image includes Phalcon v5, change to an image that does not include it. Then build the image again without the cache:

docker compose build --no-cache
Shared Hosting

Disable the Phalcon module in your control panel. For example, in cPanel & WHM, remove the Phalcon module from EasyApache 4. If you cannot change the PHP extensions, ask your hosting provider to disable Phalcon.

Compiled From Source

Use these instructions if you compiled Phalcon v5 with the install script, with phpize and make install, or on a Raspberry Pi. Also use them if you do not know how Phalcon v5 was installed.

The build copies phalcon.so into the extension folder of PHP. A PHP extension does not have a make uninstall command. Thus, you must delete the file manually.

Get the extension folder:

php -r 'echo ini_get("extension_dir"), PHP_EOL;'

The output is similar to /usr/lib/php/20230831. Delete phalcon.so from that folder:

sudo rm /usr/lib/php/20230831/phalcon.so

PHP does not use the source folder after the build. You can delete it. Make sure that the path is correct before you run the command:

sudo rm -rf /usr/local/src/cphalcon

Step 3: Remove the INI Entries

PIE and the package managers usually remove the INI entries. PECL and manual installations do not. If an INI entry points to a deleted file, PHP shows a warning each time it starts.

Find the INI files that contain Phalcon. On Debian and Ubuntu, this command searches the files of all PHP versions:

grep -rli phalcon /etc/php/

On other systems, search the files and the folders that php --ini shows.

The line that loads Phalcon has one of these forms:

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

For each file that you find:

  • If the file contains only the Phalcon line (for example 30-phalcon.ini), delete the file.
  • If the file contains other settings (for example php.ini), delete the Phalcon line, or put a ; at the start of the line.

On Debian and Ubuntu, you can also disable the extension for all PHP versions with this command:

sudo phpdismod phalcon

Step 4: Restart PHP

PHP reads the INI files only when it starts. Restart PHP-FPM, or the web server if it runs the PHP module. Change the service names to agree with your system:

sudo systemctl restart php8.3-fpm
sudo systemctl restart apache2

Step 5: Make Sure That PHP Does Not Load the Extension

Do a check of the CLI:

php --ri phalcon

The output must be:

Extension 'phalcon' not present.

Do a check of the web server. Put this file in the public folder of your application:

<?php

var_dump(extension_loaded('phalcon'));

Open the file in your browser. The output must be bool(false). Delete the file after the check.

After you install Phalcon v6, make sure that your application uses the v6 classes. Run this command in the root folder of your application:

php -r 'require "vendor/autoload.php"; echo (new Phalcon\Support\Version())->get(), PHP_EOL;'

The output must start with 6. If it starts with 5, PHP still loads the v5 extension.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close