Guía de Actualización


Upgrading to V5

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. A pesar de que los cambios son considerables, la tarea de actualización será más metódica que abrumadora.

Requerimentos

PHP 7.4

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.

PSR (Recomendaciones Estándar de PHP)

Phalcon requiere la extensión PSR. The extension can be installed with PECL:

pecl install psr

If you do not wish to install it with PECL, you can download and compile OSR from this GitHub repository. Las instrucciones de instalación están disponibles en el archivo README del repositorio. Una vez que la extensión haya sido compilada y esté disponible en su sistema, necesitará cargarla a su php.ini. Necesitarás añadir esta línea:

extension=psr.so

before

extension=phalcon.so

Alternativamente algunas distribuciones añaden un prefijo numérico en los archivos ini. Si ese es el caso, elija un número alto para Phalcon (por ejemplo 50-phalcon.ini).

Instalación

Phalcon can be installed using PECL.

pecl install phalcon-5.0.0

It is important to check your php.ini file (both for your web server and CLI) and make sure that phalcon is loaded after psr. Your php.ini should look something like this:

extension=psr.so

extension=phalcon.so

Alternative installation

Download the latest zephir.phar from here. Añada a una carpeta a la que puede acceder su sistema.

Clonar el repositorio

git clone https://github.com/phalcon/cphalcon

Compilación de Phalcon

cd cphalcon/
git checkout tags/5.0.0 ./
zephir fullclean
zephir build

Comprueba el módulo

php -m | grep phalcon

Notas generales

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. For instance Phalcon\Loader has been moved to Phalcon\Autoload\Loader. This change was necessary for the future expansion of the project.

Summary

v4 v5
Phalcon\Cache Phalcon\Cache\Cache
Phalcon\Collection Phalcon\Support\Collection
Phalcon\Config Phalcon\Config\Config
Phalcon\Container Phalcon\Container\Container
Phalcon\Crypt Phalcon\Encryption\Crypt
Phalcon\Debug Phalcon\Support\Debug
Phalcon\Di Phalcon\Di\Di
Phalcon\Escaper Phalcon\Html\Escaper
Phalcon\Exception Eliminado
Phalcon\Filter Phalcon\Filter\Filter
Phalcon\Helper Removed in favor of Phalcon\Support\Helper
Phalcon\Loader Phalcon\Autoload\Loader
Phalcon\Logger Phalcon\Logger\Logger
Phalcon\Kernel Eliminado
Phalcon\Registry Phalcon\Support\Registry
Phalcon\Security Phalcon\Encryption\Security
Phalcon\Tag Removed in favor of Phalcon\Html\Helper
Phalcon\Text Removed in favor of Phalcon\Support\Helper
Phalcon\Url Phalcon\Mvc\Url
Phalcon\Validation Phalcon\Filter\Validation
Phalcon\Version Phalcon\Support\Version

Changes

Acl

Status: changes required

Usage: ACL Documentation

En componente ACL se le ha cambiado el nombre a algunos métodos y componentes. La funcionalidad sigue siendo la misma que en versiones anteriores.

  • Renamed Phalcon\Acl\ComponentAware to Phalcon\Acl\ComponentAwareInterface
  • Renamed Phalcon\Acl\RoleAware to Phalcon\Acl\RoleAwareInterface

Acl\Adapter\Memory - Acl\Adapter\AdapterInterface

  • Added getInheritedRoles() to return an array of the inherited roles in the adapter.

Anotaciones

Status: no changes

Usage: Annotations Documentation

Application

Status: no changes

Usage: Application Documentation

The getEventsManager() now returns a Phalcon\Events\ManagerInterface or null

Recursos Activos

Status: changes required

Usage: Assets Documentation

The Assets component has had changes to the interface as well as some methods were renamed. La funcionalidad sigue siendo la misma que en versiones anteriores.

Phalcon\Assets\Asset

  • getAssetKey() now uses sha1 to compute the key
  • Renamed getLocal() to isLocal()
  • Renamed setLocal() to setIsLocal()

Phalcon\Assets\Collection

  • The class now uses ArrayIterator instead of `Iterator
  • Renamed getLocal() to isLocal()
  • Renamed setLocal() to setIsLocal()
  • Renamed getTargetLocal() to getTargetIsLocal()
  • Renamed setTargetLocal() to setTargetIsLocal()
  • Removed getPosition(), current(), key(), next(), rewind(), valid()

Phalcon\Assets\Inline

  • getAssetKey() now uses sha1 to compute the key

Phalcon\Assets\Manager

  • __construct() requires a Phalcon\Html\TagFactory as the first parameter
public function __construct(Phalcon\Html\TagFactory $tagFactory, array $options = [])
  • addCss() now requires $local to be bool and $attributes to be an array
public function addCss(
    string $path,
    bool $local = true,
    bool $filter = true,
    array $attributes = [],
    string $version = null,
    bool $autoVersion = false
): Manager
  • addInlineCss() now requires $filter to be bool and $attributes to be an array
public function addInlineCss(
    string $content,
    bool $filter = true,
    array $attributes = []
): Manager 
  • addJs() now requires $local to be bool and $attributes to be an array
public function addJs(
    string $path,
    bool $local = true,
    bool $filter = true,
    array $attributes = [],
    string $version = null,
    bool $autoVersion = false
): Manager
  • addInlineJs() now requires $filter to be bool and $attributes to be an array
public function addInlineJs(
    string $content,
    bool $filter = true,
    array $attributes = []
): Manager 
  • Added has() method to return if a collection exists

Cache

Status: changes required

Usage: Cache Documentation

The Cache component has been moved to the Cache namespace.

Phalcon\Cache\AdapterFactory

  • The constructor now requires a Phalcon\Storage\SerializerFactory to be passed as the first parameter
  • The getAdapters() protected method has been renamed to getServices()
  • A new protected method getExceptionClass() was introduced to return the exception class to throw from this factory when necessary

Phalcon\Cache\CacheFactory

  • A new protected method getExceptionClass() was introduced to return the exception class to throw from this factory when necessary

Phalcon\Cache\Cache

  • Moved Phalcon\Cache to Phalcon\Cache\Cache

CLI

Status: no changes

Usage: Cli Documentation

Coleccion

Status: changes required

Usage: Collection Documentation

Configuración

Status: changes required

Usage: Assets Documentation

Container

Status: changes required

Usage: Assets Documentation

DataMapper

Status: changes required

Usage: Assets Documentation

Db

Status: changes required

Usage: Assets Documentation

Di

Status: changes required

Usage: Assets Documentation

Dispatcher

Status: changes required

Usage: Assets Documentation

Domain

Status: changes required

Usage: Assets Documentation

Encriptación

Status: changes required

Usage: Assets Documentation

Eventos

Status: changes required

Usage: Assets Documentation

Fábrica (Factory)

Status: changes required

Usage: Assets Documentation

Filtro

Status: changes required

Usage: Assets Documentation

Flash

Status: changes required

Usage: Assets Documentation

Formularios

Status: changes required

Usage: Assets Documentation

Html

Status: changes required

Usage: Assets Documentation

Http

Status: changes required

Usage: Assets Documentation

Imagen

Status: changes required

Usage: Assets Documentation

Loader

Status: changes required

Usage: Loader Documentation

The Loader component has been moved to the Autoload namespace. Some method names have been changed and new functionality introduced.

Phalcon\Autoload\Loader

  • __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.

use Phalcon\Autoload\Loader;
use Adapter\Another;

$loader = new Loader(true);

$loader
    ->addNamespace('Base', './Namespaces/Base/')
    ->addNamespace('Adapter', './Namespaces/Adapter/')
    ->addNamespace('Namespaces', './Namespaces/')
;

$loader->autoload(Another::class);

var_dump($loader->getDebug());

// [
//     'Loading: Adapter\Another',
//     'Class: 404: Adapter\Another',
//     'Require: 404: ./Namespaces/Adapter/Another.php',
//     'Require: ./Namespaces/Another.php',
//     'Namespace: Namespaces\Adapter - ./Namespaces/Another.php',
// ];
  • add* methods have been introduced to help with the setup of the autoloader
    • addClass(string $name, string $file): Loader
    • addDirectory(string $directory): Loader
    • addExtension(string $extension): Loader
    • addFile(string $file): Loader
    • addNamespace(string $name, string|array $directories, bool $prepend = false): Loader
  • getCheckedPath() now returns either a string or a null (if not populated yet)
  • getDebug() returns an array of debug information, if the Loader has been instantiated with $isDebug = true
  • getDirs() has been renamed to getDirectories()
  • getFoundPath() now returns either a string or a null (if not populated yet)
  • registerClasses() has been renamed to setClasses()
  • registerDirs() has been renamed to setDirectories()
  • registerExtensions() has been renamed to setExtensions()
  • setExtensions() now accepts a second parameter (bool $merge) which allows you to merge the data set with what is already set in the Loader
  • registerFiles() has been renamed to setFiles()
  • registerNamespaces() has been renamed to setNamespaces()

Logger

Status: changes required

Usage: Assets Documentation

Messages

Status: changes required

Usage: Assets Documentation

Mvc

Status: changes required

Usage: Assets Documentation

Paginator

Status: changes required

Usage: Assets Documentation

Session

Status: changes required

Usage: Assets Documentation

Storage

Status: changes required

Usage: Assets Documentation

Soporte

Status: changes required

Usage: Assets Documentation

Tag

Status: changes required

Usage: Assets Documentation

Traducciones

Status: changes required

Usage: Assets Documentation

Tag.zep

Status: changes required

Usage: Assets Documentation