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/phalconUpgrading 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
.phtmlpartial.
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())beforepartial(). - The calling template does not get the variables that the partial set. To get these variables, call
extract($this->getScope())afterpartial().
In v6, these variables are available without an additional call:
- The variables that your controller sets with
setVar()orsetVars()of the view. - The variables in the
$paramsarray ofpartial(). - 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 errorCall to undefined method. partial()has the same signature as in v5. A class that extendsAbstractEngineand overridespartial()does not need a change.getScope(): arrayreturns the set of the view, andsetScope(array $scope): staticreplaces it.Phalcon\Mvc\ViewandPhalcon\Mvc\View\Simpleuse 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:
- Find the extension.
- Remove the extension with the tool that you used to install it.
- Remove the INI entries.
- Restart PHP.
- 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 phalconIf 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 phalconFor other web servers, look for phalcon in the output of phpinfo().
Get the list of INI files that PHP reads:
php --iniGet 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/cphalconPIE 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/cphalconTo see the extensions that PIE installed, run pie show.
PECL
sudo pecl uninstall phalconPECL 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-phalcon5Change 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-phalcon5Change 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-phalcon5Change 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 deinstallmacOS
Homebrew:
brew list | grep -i phalcon
brew uninstall phalcon
brew untap phalcon/extensionChange phalcon to the formula name that the first command shows.
MacPorts:
port installed | grep -i phalcon
sudo port uninstall php80-phalconChange 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 phalconThen delete the extension file. Use the instructions in Compiled From Source.
Windows
- Delete
php_phalcon.dllfrom theextfolder of your PHP installation. - Remove the
extension=php_phalcon.dllline fromphp.ini. - 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 phalconIf 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-cacheShared 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.soPHP 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/cphalconStep 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.dllFor 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 phalconStep 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 apache2Step 5: Make Sure That PHP Does Not Load the Extension
Do a check of the CLI:
php --ri phalconThe 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.