Le module Versioning pour OpenMage

Sommaire (v4.6.0)

Présentation du module
Procédure d'installation
Procédure de déploiement
Configuration
Téléchargement du module

N'oubliez pas que cette documentation ne concerne que la dernière version du module.
N'oubliez pas de lire cette page entièrement.

🌟🌟🌟🌟🌟 par Henri,
le 01/04/2020 Ce module n'est pas premium, n'est pas ultimate, n'est pas pro, il ne contient pas un mouchard ni un jolie panneau de publicité, et il n'augmentera pas votre ROI de 165%. Il est tout simplement mieux que tout ce que vous avez pu voir ailleurs. C'est une révolution !

Présentation du module

Description

Ce module permet :

de mettre à jour son site OpenMage via un système de gestion de version (GIT)
d'utiliser une page de maintenance configurable et multilingue
d'afficher les différences entre deux révisions
d'afficher l'état du dépôt
de conserver l'historique des mises à jour

Avant d'aller plus loin, voici une vidéo de présentation : voir la vidéo.

Accès et configuration

Configuration disponible dans Système » Configuration » Outils » Gestionnaire de version.
Disponible dans Outils » Gestionnaire de version.

Très important :

OpenMage doit être à la racine ou dans un sous dossier
tous les changements effectués seront annulés lors du processus de mise à jour (sauf pour les fichiers ignorés)
il est important que l'utilisateur qui exécute le serveur web ait la possibilité de modifier tous les fichiers
il ne faut pas changer de branche via le module
veillez à ce qu'il ne soit pas possible de git clone https://www.votre-site.xyz/.git

Compatible avec OpenFileEditor

Lorsque l'extension pour navigateur OpenFileEditor est installée, lors de l'affichage d'une trace d'erreur PHP, les chemins des fichiers sont cliquables, afin de les ouvrirs dans votre éditeur de fichier préféré.

Installation et désinstallation

Afin de réaliser l'installation complète du module, il faut suivre la procédure d'installation. Après avoir suivi les différentes étapes, il ne reste plus qu'à installer le module avec composer (ou en décompressant l'archive du module) avant de valider/commiter toutes les modifications.

Pour la désinstallation, après avoir désinstallé le module, il ne reste plus qu'à effacer la configuration :

sqlDELETE FROM core_config_data WHERE path LIKE "versioning/%";

Procédure d'installation

1) Pour le fichier gitignore :

gitignore/errors/config/*.ip
/errors/config/*.dat
/errors/config/*.csv
/maintenance.flag
/upgrade.flag

2) Pour les fichiers index.php et api.php :

php// replace
if (file_exists($maintenanceFile)) {
    include_once dirname(__FILE__).'/errors/503.php';
    exit;
}
// by
// @see https://github.com/luigifab/openmage-versioning
if (is_file('./maintenance.flag') && (mb_stripos(getenv('REQUEST_URI'), '/admin/') === false)) {
    $ips = './errors/config/error503.ip';
    $ip = empty(getenv('HTTP_X_FORWARDED_FOR')) ? false : explode(',', getenv('HTTP_X_FORWARDED_FOR'));
    $ip = empty($ip) ? getenv('REMOTE_ADDR') : reset($ip);
    $ip = (preg_match('# ::f{4}:\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$#', $ip) === 1) ? substr($ip, 7) : $ip;
    if (!is_file($ips) || (is_file($ips) && (stripos(file_get_contents($ips), '-'.$ip.'-') === false))) {
        include_once('./errors/503.php');
        exit(0);
    }
}
if (is_file('./upgrade.flag') && (mb_stripos(getenv('REQUEST_URI'), '/admin/') === false)) {
    $ips = './errors/config/upgrade.ip';
    $ip = empty(getenv('HTTP_X_FORWARDED_FOR')) ? false : explode(',', getenv('HTTP_X_FORWARDED_FOR'));
    $ip = empty($ip) ? getenv('REMOTE_ADDR') : reset($ip);
    $ip = (preg_match('# ::f{4}:\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$#', $ip) === 1) ? substr($ip, 7) : $ip;
    if (!is_file($ips) || (is_file($ips) && (stripos(file_get_contents($ips), '-'.$ip.'-') === false))) {
        include_once('./errors/upgrade.php');
        exit(0);
    }
}

3) Pour le fichier app/Mage.php (ce changement n'est pas obligatoire) :

difdiff --git a/app/Mage.php b/app/Mage.php
index 051804580..6210ad9cd 100644
--- a/app/Mage.php
+++ b/app/Mage.php
@@ -647,7 +647,9 @@ final class Mage
             header('Location: ' . self::getBaseUrl());
             die;
         } catch (Mage_Core_Model_Store_Exception $e) {
-            require_once(self::getBaseDir() . DS . 'errors' . DS . '404.php');
+            // @see https://github.com/luigifab/openmage-versioning
+            // require_once(self::getBaseDir().DS.'errors'.DS.'404.php');
+            self::printException($e);
             die;
         } catch (Exception $e) {
             self::printException($e);
@@ -690,7 +692,9 @@ final class Mage
             header('Location: ' . self::getBaseUrl());
             die();
         } catch (Mage_Core_Model_Store_Exception $e) {
-            require_once(self::getBaseDir() . DS . 'errors' . DS . '404.php');
+            // @see https://github.com/luigifab/openmage-versioning
+            // require_once(self::getBaseDir().DS.'errors'.DS.'404.php');
+            self::printException($e);
             die();
         } catch (Exception $e) {
             if (self::isInstalled() || self::$_isDownloader) {

4) Il faut créer le fichier .git/hooks/prepare-commit-msg de manière à enregistrer le nom de la branche dans chaque message de commit. Il faut également que chaque personne qui utilisera le dépôt le crée (sinon, dans le back-office la représentation des branches ne fonctionnera pas ; le fichier doit être exécutable).

bash#!/bin/bash
# https://www.luigifab.fr/openmage/versioning
NAME=$(git branch | grep "*" | cut -c3-)
echo "{$NAME}" >> "$1"

5) Il faut supprimer le dossier errors de OpenMage.

6) Il ne reste plus qu'à installer le module :

shellcomposer require luigifab/openmage-versioning
git add .
git commit
git push

Procédure de déploiement

Sur le serveur de production (ou de préproduction, ou encore en local), lorsque le dépôt GIT requiert une authentification par clef (ci-dessous id_rsa, sans mot de passe), il y a un peu de configuration à faire.

1) Il faut créer le fichier /xyz/.git/ssh/config.sh :

bash#!/bin/bash
ssh -o UserKnownHostsFile=/xyz/.git/ssh/known_hosts -i /xyz/.git/ssh/id_rsa $@

2) Il faut créer le fichier /xyz/.git/ssh/known_hosts :

shellssh-keyscan gitserver.xyz > /xyz/.git/ssh/known_hosts

3) Il faut appliquer les droits :

shellchmod 400 /xyz/.git/ssh/*
chmod 500 /xyz/.git/ssh/config.sh

4) Il ne reste plus qu'à charger la configuration et à cloner le dépôt :

shellexport GIT_SSH=/xyz/.git/ssh/config.sh
git clone gitserver.xyz/repo.git /xyz/
mkdir /xyz/htdocs/media/ /xyz/htdocs/var/
chown www-data. -R /xyz/

Configuration

Dans Système » Configuration » Outils » Gestionnaire de version.

Gestionnaire de projet

En complétant le champ avec par exemple http://www.redmine.org/issues/, alors les numéros des demandes présents dans les messages de commit seront transformés en liens HTML.

Page de connexion

Essayer la nouvelle page de connexion au back-office ou la nouvelle page du mot de passe oublié, c'est les adopter !

Ci-contre la nouvelle page de connexion.

Pages de maintenance

Chaque page est configurable avec ses propres options (principalement le titre et le contenu), la configuration sera sauvegardée automatiquement dans le dossier errors/config.

Lorsque le site est verrouillé, l'accès au back-office est toujours possible :
- les adresses suivantes ne fonctionneront pas : openmage.xyz/admin - openmage.xyz/index.php/admin
- les adresses suivantes fonctionneront : openmage.xyz/admin/ - openmage.xyz/index.php/admin/

Intégrateur, développeur, il est possible de modifier l'apparence des pages de maintenance avec des surcharges.
Pour en savoir plus, lire le fichier readme disponible dans le dossier errors/config.

Erreur 503 (maintenance.flag)

Cette page de maintenance s'active et se désactive dans le back-office dans Outils » Gestionnaire de version, ou manuellement en créant le fichier maintenance.flag. Elle est prioritaire sur la page de mise à jour.

Les options de configuration :

Titres
Contenu texte ou HTML
Texte avec délai du rechargement automatique
Désactiver la page à partir des adresses IP suivantes

Ci-contre la page par défaut.
Exemple : en ligne.

Mise à jour (upgrade.flag)

Cette page de maintenance s'active et se désactive dans le back-office dans Outils » Gestionnaire de version, ou manuellement en créant le fichier upgrade.flag.

Les options de configuration :

Titres
Contenu texte ou HTML
Texte avec délai du rechargement automatique
Désactiver la page à partir des adresses IP suivantes

Ci-contre la page par défaut.
Exemple : en ligne.

Rapport d'erreur

Cette page apparaît lorsque OpenMage rencontre une erreur. Un rapport d'erreur est enregistré dans le dossier var/report.

Les options de configuration :

Titres
Contenu texte ou HTML
Afficher le rapport à partir des adresses IP suivantes
Envoyer le rapport par email à

Ci-contre la page par défaut.
Exemple : en ligne.

Erreur 404 système

Attention, cette page ne correspond pas à la page d'erreur 404 lorsque l'adresse d'une catégorie ou d'un produit n'existe pas.

Les options de configuration :

Titres
Contenu texte ou HTML

Ci-contre la page par défaut.
Exemple : en ligne.

Fonctionnalités cachées

Ces paramètres GET peuvent être modifiés ou ajoutés pour filtrer les résultats des pages de différences et d'état :

from : peut être vide
to : peut être vide
excl : peut être ajouté pour exclure des fichiers (par extension ou par nom)
dir : peut être ajouté pour filtrer les dossiers

Exemple : .../versioning_repository/status/from/xyz/to/xyz/key/.../?dir=../abc/ ../def/&excl=min,csv,gallery.phtml,copyright.

Pour activer le diff au niveau des caractères avec diff-highlight, avec Debian :

bashcd /usr/share/doc/git/contrib/diff-highlight/
sudo make

Événements

Trois événements sont disponibles :

admin_versioning_add_fields : pour ajouter des options à la demande de confirmation
admin_versioning_upgrade_before : pour effectuer des actions avant la mise à jour
admin_versioning_upgrade_after : pour effectuer des actions après la mise à jour

Un exemple est disponible dans les fichiers Demo.php et config.xml.

Téléchargement du module

Installation avec composer : composer require luigifab/openmage-versioning

Téléchargement de la dernière version : openmage-versioning-4.6.0.tar.gz
Voir aussi : github - composer - geany - phpstorm

Version actuelle : 4.6.0 (01/01/2024)
Compatibilité : OpenMage 19.x / 20.x / 21.x, PHP 7.2 / 7.3 / 7.4 / 8.0 / 8.1 / 8.2 / 8.3 (avec exec)
Compatibilité client : Firefox 36+, Chrome 32+, Opera 19+, Edge 16+, Safari 9+
Traductions : allemand (de), anglais (en), espagnol (es), français (fr-FR/fr-CA), italien (it), portugais (pt-PT/pt-BR) / chinois (zh), grec (el), hongrois (hu), japonais (ja), néerlandais (nl), polonais (pl), roumain (ro), russe (ru), slovaque (sk), tchèque (cs), turc (tr), ukrainien (uk)
Licence : GNU GPL 2.0+
À lire absolument : le fichier README

4.6.0: Testé avec Firefox 36/114, Chrome 32/109, Edge 109, Opera 19/95 sur OpenMage 21.3.0 avec PHP 7.2 - 8.3 et MariaDB 10.11.

Si vous aimez ce module, prenez un peu de votre temps pour améliorer les traductions.