Migrate to Jelix 1.6 first.

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

Here are all steps to follow to migrate your application.

Requirements ¶

Backup ¶

Temp directories ¶

Installing files of Jelix ¶

{
    "name": "mycompany/myapp",
    "type": "application",
    "require": {
        "jelix/jelix": "~1.7.18"
    },
    "extra": {
        "jelix": {
             "target-jelix-version": "1.7"
        }
    }
}

composer install

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

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

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

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

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).

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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();

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.

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.

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.

• jSoap module: jelix/soap-server-module
• jtcpdf module: jelix/tcpdf-module.
• plugin Minify plugin for jResponseHtml: jelix/minify-module.
• plugin Redis using PhpRedis, for jKVDb and jCache: jelix/php-redis-plugin. (useless if the Redis extension for PHP is installed, and in this case, you can use the plugin redis_ext from Jelix)
• jsitemap module: jelix/sitemap-module
• jHttp class: jelix/jhttp. But it is not maintened anymore and you should use more modern classes like GuzzleHttp.

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.

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;
    }
}

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

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.

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

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.

After all these operations, your application should work.