So you have decided to upgrade to v5! Congratulations!!
Phalcon v5 contains a lot of changes in components and interfaces. Upgrading is going to be a time-consuming task, depending on how big and complex your application is. We hope that this document will make your upgrade journey smoother and also offer insight as to why certain changes were made and how it will help the framework in the future.
We will outline the areas that you need to pay attention to and make necessary changes so that your code can run as smoothly as it has been with v4. Although the changes are significant, it is more of a methodical task than a daunting one.
Phalcon v5 supports only PHP 7.4 and above. PHP 7.4 active support expired roughly a month before the release of Phalcon 5, but support for security patches etc. will continue until November 2022. After that time, we will drop support for PHP 7.4 also.
Since Phalcon 4, we have been following the PHP releases and adjusting Phalcon accordingly to work with those releases.
Phalcon can be installed using PECL.
pecl install phalcon-5.0.0
Download the latest zephir.phar from here. Add it to a folder that can be accessed by your system.
Clone the repository
git clone https://github.com/phalcon/cphalcon
git checkout tags/5.0.0 ./
Check the module
php -m | grep phalcon
One of the biggest changes with this release is that we no longer have top level classes. All top level classes have been moved into relevant namespaces (except Phalcon\Tag). For instance Phalcon\Loader has been moved to Phalcon\Autoload\Loader. This change was necessary for the future expansion of the project.
The Autoload\Loader component has been moved from the parent namespace. Some method names have been changed and new functionality introduced.
__construct(bool $isDebug = false)
The constructor now accepts a boolean, which allows the loader to collect and store debug information during the discovery and loading process of files, classes etc. If the variable is set to true, getDebug() will return an array with all the debugging information during the autoload operation. This mode is only for debugging purposes and must not be used in production environments.
The Config component has been moved to the Config namespace.
Moved Phalcon\Config to Phalcon\Config\Config
A new interface has been introduced (Phalcon\Config\ConfigInterface) to offer more flexibility when extending the config object.
The Container component has been removed from the framework. It is in our roadmap to develop a new container that will support auto wiring, as well as providers. Additionally, the container will be designed and implemented in such a way that could be used as a PSR-11 container (with the help of a Proxy class).
Phalcon\Forms\Element\* classes now use the new Phalcon\Html\TagFactory to generate HTML code. As a result, the functionality has changed slightly. The main difference is that a Phalcon\Html\TagFactory has to be set in the form object, so that elements can be rendered. If the Phalcon\Html\TagFactory is not set, then the component will search the Di container (Phalcon\Di\DiInterface) for a service with the name tag. If you are using Phalcon\Di\FactoryDefault as your container, then the tag service is already defined for you.
Added getTagFactory() to return the Phalcon\Html\TagFactory object used internally, as well as setTagFactory(TagFactory $tagFactory): AbstractElement to set it.
This class has been moved to this namespace from the top level one. The names of the methods have been changed to be a lot simpler and verbose. Finally, the flags protected property that controls the flags for htmlspecialchars() is set to 11 which corresponds to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
A new method attributes(string input) can be used to escape HTML attributes (replaces escapeHtmlAttr())
A new method css(string $input) can be used to escape CSS (replaces escapeCss()
escapeCss() now raises a deprecated warning
escapeJs() now raises a deprecated warning
escapeHtml() now raises a deprecated warning
escapeUrl() now raises a deprecated warning
A new method html(string $input = null) can be used to escape HTML attributes (replaces escapeHtml())
A new method js(string $input) can be used to escape HTML attributes (replaces escapeJs())
A new method setFlags(int $flags) can be used to set the flags for htmlspecialchars() (replaces setHtmlQuoteType())
setHtmlQuoteType() now raises a deprecated warning
A new method url(string $input) can be used to escape URL strings (replaces escapeUrl())