Quick links: Content - sections - sub sections
EN FR
Jelix 1.7.7

Chapter: Migrating from a previous version

« New features ^ Introduction
Switch to language: FR

When you migrate from an old version of jelix to a newer one, you always must do these tasks:

  • replace the lib/ directory by the one provided in the new version. Since Jelix 1.7, the standard process is to use Composer and to change the version of Jelix into the composer.json file of your project. Or to create a composer.json to migrate to 1.7.
  • remove all the files in the temp/yourapp/ directory
  • update your code as specified hereafter.
  • launch the migration tool which will probably modify some files and directories
  • In each instance of the application, launch the configurator and the installer of Jelix

Updating from Jelix 1.5 or lower

Migrate to Jelix 1.6 first.

Read the upgrade instructions of all previous versions and then follow instructions below.

Upgrading from jelix 1.6.x

Here are all steps to follow to migrate your application.

Requirements

Jelix 1.7 needs PHP 5.6 minimum. Verify that you have this version of PHP on your server, or an higher one. PHP 7.3 or higher is recommended.

Backup

First, do a backup of your databases, and of your application files (modules, configuration etc.).

Temp directories

As usual, you must remove every files into the temp/yourapp/ directory. In Jelix 1.7, by default the temp directory is in the application (yourapp/temp/). But if this is not the case, you can keep the temp directory anywhere.

Installing files of Jelix

Since version 1.7, you can install Jelix with Composer. Composer is a package manager for PHP, usable on the command line.

Some of modules provided into Jelix 1.6 packages are now installable separately with Composer.

However, if you prefer to install Jelix from a traditional archive (zip or tar.gz), this is still possible.

So to migrate to Jelix 1.7, you have two choices: with Composer, or "by hand".

If you want to use Composer

Install Composer by reading its instructions.

In the directory of your project, create a composer.json file. It should indicate the package jelix/jelix as a dependency, in the require section. It is recommended to indicate ^1.7.2.

Exemple :


{
    "name": "mycompany/myapp",
    "type": "application",
    "require": {
        "jelix/jelix": "^1.7.2"
    }
}

Of course, you should replace here "mycompany/myapp" by your own id. The file can contain many other data. See the manual of Composer.

Now delete the lib/ directory, except librairies stored in it which were not provided by Jelix.

Then on the command line, type:


composer install

You should then see a new vendor directory and a composer.lock file. It is not recommended to include this directory in your git/mercurial/svn repository. So indicate it into the .gitignore, .hgignore file, or into a property snv:ignore.

In the application.init.php file, you should then replace the include of lib/jelix/init.php by two other files, vendor/autoload.php and vendor/jelix_app_path.php. You should then have an application.init.php like this:


require (__DIR__.'/vendor/autoload.php');
jApp::initPaths(
    /* no change here */
);
jApp::setTempBasePath(/* no change here */);

require (__DIR__.'/vendor/jelix_app_path.php');

Skip the following section.

If you don't want to use Composer

Download the Jelix package from the download site of Jelix, as usual.

Replace the lib/ directory by the new one. Take care about librairies stored in the previous lib/ that were not provided by Jelix.

In the application.init.php file, you should then replace the include of lib/jelix/init.php by two other files, ../lib/vendor/autoload.php and ../lib/vendor/jelix_app_path.php. You should then have an application.init.php like this:


require (__DIR__.'/../lib/vendor/autoload.php');
jApp::initPaths(
    /* no change here */
);
jApp::setTempBasePath(/* no change here */);

require (__DIR__.'/../lib/vendor/jelix_app_path.php');

Changes into the modules and plugins declarations

In previous version of Jelix, directories containing modules and plugins should be declared into the configuration (mainconfig.ini.php or the configuration file of the entry point), into parameters modulesPath or pluginsPath.

These parameters are not supported anymore. Modules and plugins directories should be declared into the application.init.php file (or into the composer.json file if you are using Composer, for package containing only modules).

In application.init.php, you should call jApp::declareModulesDir and/or jApp::declarePluginsDir with the list of directories.


jApp::declareModulesDir(array(
                        __DIR__.'/modules/'
                    ));
jApp::declarePluginsDir(array(
                        __DIR__.'/plugins'
                    ));

In this example, modules/ and plugins/ directories of the application are declared. Note that directories lib/jelix-modules, lib/jelix-admin-modules and lib/jelix-plugins are declared automatically (via the file vendor/jelix_app_path.php).

About Simpletest

Simpletest and the module junittests are not provided by Jelix anymore. If you didn't migrate yet your tests to PHPUnit, you can still install the module junittests with its archive or with Composer ("jelix/simpletest-module" in your composer.json).

However, it is highly recommended to migrate to PHPUnit (or any other modern tests framework like Atoum), as Simpletest is a dead project, as well as the junittests module.

Changes into profiles.ini.php

jDb drivers "sqlite" and "mysql" are not provided anymore with Jelix, because there are deprecated and they are using deprecated PHP API. They should be replaced by the "sqlite3" and the "mysqli" drivers.

For "mysql", it is automatically replaced with "mysql" by the migration script of Jelix.

For "sqlite", you must migrate by hand, sqlite2 databases are not compatible with sqlite3. So you should convert your sqlite2 files. For example, in your system that have both sqlite (2) and sqlite3, you can do: sqlite OLD.db .dump | sqlite3 NEW.db.

Even it is not recommended, you can still use old drivers, by installing them from the dedicated repository or with Composer ("jelix/legacy-db-plugins" package). You should install also the PECL extension for sqlite2 and the old mysql PHP extension.

About ldap with jAuth

If you are using the ldap plugin for jAuth, informations about the connection (host, login, password etc) are now into profiles.ini.php instead of into auth.coord.ini.php. The migration script does the change for you.

Changes in the url engine settings

There is no more several URL engines. There is only one engine, inherited from the old "significant" engine, and improved to support urls managed by the old "basic_significant" engine. Parameters "module" and "action" in urls are not supported anymore. If you have urls in your template or your code that have such parameters, you should change them to this syntax: /my_module/my_controller/my_method.

Example: /index.php?module=foo&action=ctrl:act becomes /index.php/foo/ctrl/act.

If urls does not work after the migration, verify that your server is well configured to support the pathinfo.

About your scripts using jCmdLineRequest

If a script is dedicated to a specific action, you have to indicate the module and the action to execute to the jCmdLineRequest constructor, in addition of the true parameter. In 1.6, module and action values were those stored into the configuration parameters startModule et startAction. These parameters are not supported anymore.

However, it is recommended to migrate your scripts controllers to new commands by using Symfony Console, as jCmdLineCoordinator and jCmdLineController are deprecated. See the chapter to develop a command with Symfony Console.

Custom plugin for jDb and jDao

Classes *daobuilder* in plugins for jDb are not supported anymore. If you made your own jDb plugin, you should migrate this class to a daobuilder plugin for jDao, which is a new type of plugin. See jDao documentation.

Same thing for dbtools classes, which are not anymore into drivers. They are completely integrated into jDb. If you have a driver with a such class that support a SQL language not supported by jDb, you should propose a patch to the Jelix project.

Changes in installation scripts of your modules

Because of changes in the organization of configuration files and the change in how the installation is done, some new classes \Jelix\Installer\Module\Installer, \Jelix\Installer\Module\Uninstaller, and \Jelix\Installer\Module\Configurator are available for your install scripts.

In future version, old classes jInstallerModule and jInstallerEntryPoint will be deprecated so your are encouraged to migrate your install script to the new API, even if your current script still work with Jelix 1.7.

Removing of the json.js and json2.js files

If your javascript are still using functions toJSONString() or parseJSON() from the scripts json.js and json2.js, replace them by the use of the JSON object of Javascript.

Remove all links to json.js and json2.js in your templates and controllers.

Upgrading your modules

Update sources of vendor's modules that you have installed, with version compatible with Jelix 1.7.

For your own modules, in module.xml files, indicate that the module is compatible with Jelix 1.7 (change the attribute maxversion). Example:


        <jelix minversion="1.6" maxversion="1.7.*"/>

Updating your code

See the detailed changelog to know what are the new classes and methods you can use, deprecated components, and which API have been removed etc...

There are also changes in some API, so you have to modify your code if you are using them:

  • jQueryPath from the configuration, is deprecated. Prefer to use the new webassets system.
  • If you process requests having JSON content (application/json mime type), the JSON is now automatically deserialized with json_encode. You have to change your controller to avoid to deserialized your self the JSON content.
  • jDb: if you are using bindValue() et bindParam(), you should modify calls to them, as parameters have changed.
  • jDao: the driver attribute on a <binary_op> element is deprecated and replaced by a dbtype attribute. Remove the use of the groupby attribute on <method> elements. It is deprecated and its implementation was not well supported by databases. Replace your method by an other SQL query.

Some features, API and modiles have been removed. See the full list in the detailed changelog. Be sure to modify the code that use them.

Update the cmd.php script

Replace the content of the script cmd.php which is in the same directory as application.init.php by this content:


require (__DIR__.'/application.init.php');
\Jelix\DevHelper\JelixCommands::launch();

Launch of the migration script

The migration system will do many changes for you:

  • Move configuration files to a new directory app/system:
    • mainconfig.ini.php, urls.xml, preferences.ini.php
    • entry point configuration files
    • configuration files of plugins for the coordinator
    • classmap file for soap
  • Move the directory responses/ to app/responses
  • Update of the configuration of the url engine
    • migration of the Url configuration
    • migration of configuration parameters startModule and startAction into urls.xml
    • Remove old configuration parameters of the url engine
  • Update of the content of ini configuration files
    • Move [modules] sections of entry point configuration to mainconfig.ini.php
    • in the [modules] section, rename properties *.access to *.enabled
    • move configuration of coordinator plugins to mainconfig.ini.php
    • migrate wikieditor and htmleditor configuration to webassets
    • remove parameters modulesPath and pluginsPath
  • Update of profiles.ini.php
    • migrate ldap connexion parameters to profiles.ini.php
    • replace driver mysql by mysqli
  • update project.xml file
  • create script console.php, and rename cmd.php to dev.php
    • create install/configurator.php and update install/installer.php

Launch now php cmd.php jelix:migrate -v.

Move of the themes files, overload files...

Contents that are not dynamics (so files created by the developer, not files created by the application during its life), should be moved from the var/ directory to the app/ directory:

  1. var/overloads/* goes to app/overloads/
  2. var/themes/* goes to app/themes/
  3. var/locales/* goes to app/locales/

This is not done by the migration script because it cannot guess which files are generated by the developer, and those generated by the application itself.

Installation and configuration of external modules

If you use the response objects Atom or RSS, you should now that they are moved to a dedicated module, jfeeds, which is provided with Jelix. You should activate it:


php dev.php module:configure jfeeds -v

Some few classes, modules and plugins are now available separately, with Composer or with a zip file. If you are using them, you have to install them with Jelix 1.7.

After installing the source code of these modules, you should execute for each module:


php dev.php module:configure module_name

This command configure and activate the module into the application.

Changes in your SOAP controllers

You must replace code comments "@param" by "@externalparam".

Before:


    /**
     * Test with a simple parameter
     * @param string $name
     * @return string
     */
    function hello() {
        $rep = $this->getResponse('soap');
        $rep->data = "Hello ".$this->param('name');
        return $rep;
    }
}

After:


    /**
     * Test with a simple parameter
     * @externalparam string $name
     * @return string
     */
    function hello() {
        $rep = $this->getResponse('soap');
        $rep->data = "Hello ".$this->param('name');
        return $rep;
    }
}

Update of Jelix instances

Now that the source code and main configuration of the application have been updated, you should save files into your source code manager, deploy sources to your test server (in particularly your local server).

Each time you deploy new sources on a server, you should launch the local configurator (new step with Jelix 1.7), and the installer.

In the current specific case, the local configurator will end the configuration and the migration of some configuration parameters tied to the server context. The installer will launch the update of data into the database.

So, erase any files from your temp directory, then launch:


php install/configurator.php -v

php install/installer.php -v

Changes about the cmd.php script, renamed to dev.php

Commands of cmd.php have been rewritten by using the Symfony Console component. So all parameters and options names have changed. And its name too, which is now dev.php.

If you are using the cmd.php script into other scripts, cron or else were, you should change its name, parameters and options. See php dev.php help to know the new syntax.

Moreover, the script createapp.php has been moved to bin/create-jelix-app or to vendor/bin/create-jelix-app if your are using Composer.

Update of your web server

If you had an alias to lib/jelix-www/ in the configuration of your web server, and if you are using Composer, you must change the path to vendor/jelix/jelix/lib/jelix-www/.

About session and cookies

Data of jForms instances are not stored anymore in session, but now in a cache managed by jCache. Some users may loose their forms data edited during the migration.

Users may also be disconnected, and should authenticate themselves again, as the key to encrypt data in the cookie for the authentication persistance, has changed.

The end

After all these operations, your application should work.