Quick links: Content - sections - sub sections
Jelix 1.7.0-rc.1

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.
  • If you put your own libraries into the lib/ directory, don't forget to move them from the old lib/ directory to the new one.
  • remove all the files in the temp/yourapp/ directory
  • update your code as specified hereafter.
  • laucnh the Jelix installer

Updating from Jelix 1.5 or lower

Migrate to Jelix 1.6 first.

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

Upgrading from jelix 1.6.x

Here are all steps to follow to migrate your application.


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 is recommanded.


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 separatly with Composer.

However, if you prefer to install Jelix from a traditionnal 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 recommanded to indicate ^1.7.0.

Exemple :

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

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 recommanded 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:

require (__DIR__.'/../lib/jelix/init.php');


require (__DIR__.'/vendor/autoload.php');
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:

require (__DIR__.'/../lib/jelix/init.php');


require (__DIR__.'/../lib/vendor/autoload.php');
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).

Delete modulesPath and pluginsPath parameters.

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


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 recommanded 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 become /index.php/foo/ctrl/act.

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

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.

About your scripts using jCmdLineRequest

If a script is dedicated to a specific action, you have to indicate now, to the jCmdLineRequest constructor, the module and the action to execute, 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.

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.

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 crypt data in the cookie for the authentication persistance, has changed.

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.

The main difference between the old and the new API is about the visibility of some properties (from public to protected), about methods first*() which have gone, and about the access to the configuration files.

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/

Removing of the json.js and json2.js

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.*"/>

Some few classes, modules and plugins are now available separatly, with Composer or with a zip file. If you are using them, you have to install them with Jelix 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 unstable. Replace your method by an other SQL query.

Jelix update

You must modify the file install/installer.php, to include instructions to migrate. It should be:

require_once (__DIR__.'/../application.init.php');


// launch the low-level migration
$migrator = new \Jelix\Installer\Migration(new \Jelix\Installer\Reporter\SimpleConsole('notice', 'Low-level migration'));

// we can now launch the installer/updater
$installer = new \Jelix\Installer\Installer(new \Jelix\Installer\Reporter\SimpleConsole());
if (!$installer->installApplication()) {
    exit (1);
try {
catch(Exception $e) {
    echo "WARNING: temporary files cannot be deleted because of this error: ".$e->getMessage().".\nWARNING: Delete temp files by hand immediately!\n";
    exit (1);
exit (0);

After all these modifications, you should run your install/installer.php script.

php install/installer.php

The migration system will do many changes for you:

  • migration of the Url configuration
  • migration of configuration parameters startModule and startAction into urls.xml
  • Remove useless configuration parameters
  • Move [modules] sections of entry point configuration to mainconfig.ini.php
  • in the [modules] section, rename properties *.access to *.enabled
  • Move the directory responses/ to app/responses
  • move configuration files to 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
  • rename persistant_crypt_key to persistant_encryption_key
  • migrate wikieditor and htmleditor configuration to webassets
  • migrate ldap connexion parameters to profiles.ini.php