Suivez les indications de migration de chaque version intermédiaire pour migrer à la dernière version de Jelix 1.6, avant de mettre à jour pour jelix 1.7.

Voir les instructions de migration des manuels de chacune de ces versions.

Voici les instructions à suivre dans l'ordre.

Prérequis ¶

Sauvegarde ¶

Répertoires temporaires ¶

Installation des sources de Jelix ¶

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

composer install
# ou si vous aviez déjà un fichier composer.json et des paquets installés :
composer update

require (__DIR__.'/vendor/autoload.php');
jApp::initPaths(
    /* ici pas de changements, garder vos chemins existants */
);
jApp::setTempBasePath(/* ici pas de changements, garder le chemins existant */);

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

require (__DIR__.'/../lib/vendor/autoload.php');
jApp::initPaths(
    /* ici pas de changements, garder vos chemins existants */
);
jApp::setTempBasePath(/* ici pas de changement, garder le chemin existant */);

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

Dans les versions précédentes de Jelix, il fallait déclarer les répertoires contenant des modules ou de plugins, dans des paramètres modulesPath ou pluginsPath de la configuration (indiqués dans mainconfig.ini.php ou le fichier de configuration du point d'entrée).

Ces paramètres ne sont plus reconnus. Les répertoires de modules et de plugins doivent maintenant être déclarés dans le fichier application.init.php (ou dans le fichier composer.json si vous utilisez Composer pour réaliser des paquets Composer de modules).

À la fin du fichier application.init.php, vous devez appeler jApp::declareModulesDir et/ou jApp::declarePluginsDir, avec la liste des repertoires contenant des plugins et modules :

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

Dans cet exemple, les répertoires modules/ et plugins/ de l'application sont déclarés. Notez que les répertoires lib/jelix-modules, lib/jelix-admin-modules et lib/jelix-plugins fournis avec Jelix sont déclarés automatiquement (via l'inclusion du fichier vendor/jelix_app_path.php).

Simpletest (et le module junittests) n'est plus fourni avec Jelix. Si vous n'avez pas encore migré vos tests vers PHPUnit, vous pouvez installer le module junittests en le téléchargeant ou en le déclarant ("jelix/simpletest-module") dans votre fichier composer.json.

Cependant, Simpletest et le module junittests n'étant plus maintenue, il est fortement recommandé d'utiliser d'autres outils de tests unitaires comme PHPUnit ou Atoum.

Les drivers jDb "sqlite" et "mysql" ne sont plus fournis (le premier utilisant une API PHP pour le vieux sqlite 2, et le deuxième utilisant l'API php mysql qui est dépréciée). Utilisez donc à la place respectivement "sqlite3" et "mysqli".

Pour mysqli, c'est modifié automatiquement par le script de migration de Jelix.

Mais pour sqlite3, il faut le faire à la main. Attention : pour passer de sqlite 2 à sqlite 3, il faut d'abord convertir votre base au format sqlite3 (en ayant donc installé sqlite 2 et sqlite 3 sur votre système), par exemple en tapant dans votre console : sqlite OLD.db .dump | sqlite3 NEW.db.

Une alternative est d'installer les drivers sqlite et mysql séparément, en les téléchargeant ou en déclarant le paquet "jelix/legacy-db-plugins" dans votre fichier composer.json. Et en installant l'extension PECL de sqlite 2 et la vieille extension de mysql dans PHP.

Si vous utilisez le plugin ldap pour jAuth, les informations de connexion doivent être maintenant dans le fichier profiles.ini.php au lieu du fichier auth.coord.ini.php. Le script de migration fait ce changement pour vous.

Il n'y a plus le choix dans le moteur d'URL. Il s'agit maintenant uniquement du moteur anciennement nommé "significant" et amélioré pour prendre en charge les urls de "basic_significant". Les paramètres "module" et "action" des urls ne sont plus pris en charge. Si vous avez des urls en dur dans votre code (contrôleurs, configurations ou templates par exemple) qui contiennent ces paramètres (parce que vous utilisiez le moteur "simple"), changez-les sous la forme /mon_module/mon_controleur/ma_methode.

Exemple : /index.php?module=foo&action=ctrl:act devient /index.php/foo/ctrl/act.

Si ces urls ne fonctionnent pas après la migration, vérifiez que votre serveur web est bien configuré pour prendre en charge le "pathinfo".

Si le script est dédié à une action particulière, il ne faut plus seulement indiquer true au constructeur de jCmdLineRequest, mais aussi le module et l'action. Vous y mettrez donc les valeurs des paramètres de configuration startModule et startAction du script. Ces derniers ne sont en effet plus utilisés.

Cependant, nous vous recommandons de migrer vos contrôleurs de scripts en ligne de commande vers des commandes implémentées avec Symfony Console. jCmdLineCoordinator et jCmdLineController sont déclarés obsolètes. Voyez le chapitre pour développer une commande avec Symfony Console.

Les classes *daobuilder* des plugins de jDb ne sont plus pris en charge. Si vous aviez fait votre propre plugin pour jDb, il faut migrer la classe de type daobuilder vers un plugin spécifique pour jDao. Voir la doc de jDao.

Idem pour les classes dbtools, qui ne sont plus dans les drivers, mais complètement intégrées à jDb. Si vous avez un plugin avec sa propre classe dbtools qui ne correspond pas à un langage SQL pris en charge par jDb, il vous faudra proposer un patch à Jelix.

Étant donné les changements dans l'organisation des fichiers de configuration, et le changement de fonctionnement général de l'installateur, des nouvelles classes \Jelix\Installer\Module\Installer, \Jelix\Installer\Module\Uninstaller, et \Jelix\Installer\Module\Configurator ont fait leur apparition.

Bien que cela ne soit pas obligatoire pour Jelix 1.7 (mais cela le deviendra pour les futures versions, jInstallerModule disparaitra), vous devriez modifier vos scripts d'installation et de mise à jour en utilisant la classe \Jelix\Installer\Module\Installer. Probablement aussi que vous devrez migrer des parties de votre classe d'installation vers une classe de configuration basée sur \Jelix\Installer\Module\Configurator.

Si vos scripts javascript utilisaient la fonction toJSONString() ou parseJSON(), il faut remplacer ces appels par l'utilisation de l'objet JSON standard en javascript.

Il faut aussi retirer tout chargement des scripts jelix/js/json.js, jelix/js/json2.js et jelix/xul/jsonrpc.js.

Mettez à jour les sources des modules tiers que vous avez installés, et qui sont compatibles avec Jelix 1.7.

Et pour vos propres modules, vous devez adapter le code source en faisant les modifications suivantes :

• Dans les fichiers module.xml, indiquez que le module est compatible avec Jelix 1.7 (changer l'attribut maxversion). Exemple :

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

Lisez la liste détaillée des changements pour savoir la liste des nouvelles classes et méthodes que vous pouvez utiliser.

Il y a eu aussi des changements dans certaines API, que vous devriez donc modifier dans votre code si vous les utilisez :

• jQueryPath dans la configuration est obsolète. Préférez l'utilisation des webassets.

• si vous traitez des requêtes avec du contenu JSON (type application/json) le JSON est maintenant automatiquement désérialisé avec json_decode. Vous devez donc changer vos contrôleurs pour ne plus faire vous même la déserialisation.

• jDb : si vous utilisiez bindValue() et bindParam() (mais il y a peu de chance, vu que cela ne fonctionnait pas très bien) il faut modifier ces appels, en utilisant les bons arguments.

• jDao : l'attribut "driver" sur la balise de condition "binary_op" est déprécié et remplacé par un attribut "dbtype". Vous devez également supprimer l'attribut groupby sur les élements <method>. Il n'est plus pris en charge depuis Jelix 1.6.

Des fonctionnalités, API et modules ont été supprimés. Voir la liste complète dans les nouveautés. Veillez donc à modifier votre code pour ne plus les utiliser et éventuellement les remplacer par des alternatives.

Remplacer le contenu du script cmd.php qui se trouve au même niveau que application.init.php par celui-ci :

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

Vous devez maintenant lancer le script de migration de Jelix, qui va faire beaucoup de changements à votre place.

En particulier :

• Déplacement des fichiers de configuration suivants vers un nouveau répertoire app/system :
  • mainconfig.ini.php, urls.xml, preferences.ini.php
  • ceux des points d'entrées
  • fichiers de configuration des plugins du coordinateur
  • fichier de classmap pour soap
• Déplacement du répertoire responses/ vers app/responses
• Mise à jour de la configuration du moteur d'Url
  • Migration de la configuration des moteurs d'url "simple" et "basic_significant" vers le fichier urls.xml
  • Migration des paramètres startModule et startAction vers urls.xml
  • Suppression des paramètres et section obsolètes liés au moteur d'url
• mise à jour du contenu des fichiers de configuration ini :
  • Deplacement des sections [modules] des configurations des points d'entrée vers mainconfig.ini.php
  • Dans la section [modules], renommage des propriétés *.access en *.enabled
  • migration de persistant_crypt_key vers persistant_encryption_key (liveconfig.ini.php)
  • deplacement du contenu de la plupart des fichiers de configuration des plugins de coordinateur vers mainconfig.ini.php
  • migration de la declaration des assets des widgets wikieditor et htmleditor vers le nouveau système d'assets
  • Suppression des paramètres modulesPath et pluginsPath
• Mise à jour du fichier profiles.ini.php
  • migration des paramètres de connexions ldap dans le fichier profiles.ini.php, si vous utilisez ldap pour l'authentification.
  • remplacement du driver mysql par mysqli
• mise à jour du fichier project.xml
• creation du script console.php, renommage de cmd.php en dev.php
• creation de install/configurator.php et mise à jour de install/installer.php

Lancez donc maintenant : php cmd.php jelix:migrate -v.

Puis dans application.init.php, décommentez la ligne qui inclus jelix_app_path.php, et lancer composer update.

Il faut déplacer les contenus qui ne sont pas dynamiques (donc ceux d'origine, pas ceux créés par l'application) :

1. de var/overloads/* vers app/overloads/
2. de var/themes/* vers app/themes/
3. de var/locales/* vers app/locales/

Ce n'est pas fait automatiquement par le script de migration, car il n'est pas possible pour lui de déterminer ce qui est "statique" ou "dynamique".

Si vous utilisez les objets réponses Atom ou Rss, ils ont été déplacé dans un module dédié jfeeds qui est livré avec Jelix. Il faut l'activer pour que vos flux Atom et Rss fonctionnent :

php dev.php module:configure jfeeds -v

Certaines classes, certains modules et plugins sont maintenant livrés séparément, soit installable avec Composer, soit via un zip. Si vous les utilisiez, il faudra donc les récupérer en plus de Jelix. Il s'agit de :

• Le module jSoap : jelix/soap-server-module
• Le module jtcpdf : jelix/tcpdf-module.
• Le plugin Minify pour les réponses HTML (maintenant dans un module) : jelix/minify-module.
• Le plugin Redis reposant sur la classe PhpRedis pour jKVDb et jCache : jelix/php-redis-plugin. (inutile si vous avez installé l'extension redis dans PHP, auquel cas vous pouvez utiliser le plugin redis_ext fourni dans Jelix)
• Le module jsitemap : jelix/sitemap-module, contenant l'objet réponse pour générer un sitemap.
• la classe jHttp : jelix/jhttp. Il est préconisé d'utiliser d'autres composants plus modernes comme GuzzleHttp.

Pour chacun des modules nouvellement téléchargé, il faudra faire un :

php dev.php module:configure nom_du_module

Cela les configurera et les activera dans l'application.

Il faut remplacer les commentaires de code "@param" par "@externalparam".

Avant :

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

Après :

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

Maintenant que les sources de Jelix et de votre application ont été mise à jour, vous pouvez sauvegarder tout cela dans votre gestionnaire de code source, et déployer les sources sur vos serveurs de tests (en particulier votre serveur local si vous en avez un).

Comme à chaque fois que déployez les sources d'une application Jelix sur un serveur, il faut lancer le configurateur local (nouvelle étape de Jelix 1.7) et l'installateur de Jelix.

Dans le cas présent, le configurateur local terminera le paramétrage et la migration des informations de configuration spécifiques au contexte du serveur. Et l'installateur lancera les scripts de mises à jour des données si il y en a.

Supprimez tout ce qu'il y a dans le répertoire temp/ de votre application, puis lancez :

php install/configurator.php -v

php install/installer.php -v

Les commandes de cmd.php ont été réimplémentée en utilisant le composant Symfony Console. De ce fait, tous les paramètres et options ont changé. Et cmd.php a été renommé en dev.php.

Si vous utilisez ces commandes dans des scripts, cron ou autre, il vous faut changer les paramètres, en particulier le nom de la commande. Faire un php dev.php help pour avoir l'aide.

De plus le script createapp.php a été déplacé dans un répertoire bin, et disponible sous le nom create-jelix-app dans vendor/bin de votre application si vous installez Jelix avec Composer.

Si vous aviez un alias vers lib/jelix-www/ dans la configuration de votre serveur web, et que vous utilisez Composer, il faut changer le chemin puisque jelix-www est maintenant dans vendor/jelix/jelix/lib/jelix-www/.

Les données des instances des formulaires ne sont plus stockés en session, mais dans un cache géré par jCache. Il faut donc savoir que certains de vos utilisateurs qui utilisaient des formulaires au moment de la migration de votre application perdront donc les données de leurs formulaires (si elles n'ont pas été sauvées par ailleurs).

Idem pour la persistance de l'authentification : la clé de chiffrement de cookie étant changée, les utilisateurs devront obligatoirement se ré-authentifier si ils avaient choisie d'être "reconnu" par votre application.

Après cela, votre application est de nouveau opérationnelle.