Documentation nouveaux helpers

packaging_apps_helpers_fr.md

@@ -20,6 +20,32 @@ Le script helpers va exécuter tout les scripts présent dans helpers.d et donc
 
 ### Liste non exhaustive des helpers disponibles
 #### Base de données
+```bash
+ynh_mysql_setup_db USER NAME [PWD]
+```
+> Créer l'utilisateur sql `USER` et lui octroie tout les droits sur une nouvelle base de donnée `NAME`.  
+Si aucun mot de passe n'est indiqué, un nouveau est généré et stocké dans la variable $db_pwd ainsi que dans la configuration de l'application sous le nom "mysqlpwd"  
+**Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_mysql_remove_db USER NAME
+```
+> Supprime l'utilisateur sql `USER` et sa base de donnée `NAME`.  
+**Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_sanitize_dbid NAME
+```
+> Corrige le nom d'une base de donnée pour s'assurer qu'il ne contient pas de caractères interdits.  
+Et renvoi ce nom corrigé.
+> ```bash
+> dbname=$(ynh_sanitize_dbid $app)
+> ```
+> **Nécessite YunoHost version 2.6.4**
+
+
 ```bash
 ynh_mysql_execute_as_root SQL DB
 ```
@@ -81,29 +107,21 @@ ynh_package_update
 > Met à jour la liste des paquets disponibles de manière silencieuse et non interactive.  
 > C'est un `apt-get update` avec les options -y -qq et noninteractive.
 
-<br/>
-
-**Attention, les commandes suivantes sont à éviter autant que possible. Il n'est pas sain d'installer et encore moins de supprimer un paquet sans en gérer les conflits et dépendances. Ceci sera bientôt facilité dans les prochaines versions de YunoHost...**
 
 ```bash
-ynh_package_install PACKAGE1 PACKAGE2
+ynh_install_app_dependencies DEPENDANCE1 DEPENDANCE2 ...
 ```
-> Installe les paquets `PACKAGE1`, `PACKAGE2`, etc de manière non interactive et silencieuse.  
+> Installe les paquets requis par une app sous forme de dépendance. De cette manière les paquets supplémentaires installés sont gérés en tant que dépendances par apt.  
-> C'est un `apt-get install` avec les options -y -qq et noninteractive.
+Il est préférable d'installer les paquets nécessaire par ce helper plutôt que par apt directement.  
+**Nécessite YunoHost version 2.6.4**
 
 
 ```bash
-ynh_package_remove PACKAGE1 PACKAGE2
+ynh_remove_app_dependencies
 ```
-> Supprime les paquets `PACKAGE1`, `PACKAGE2`, etc de manière non interactive et silencieuse.  
+> Supprime les dépendances de l'application, précédemment installées avec ynh_install_app_dependencies.  
-> C'est un `apt-get remove` avec les options -y -qq et noninteractive.
+Les paquets ne seront supprimés que si aucune application ou paquet ne les utilisent encore, selon apt.  
-
+**Nécessite YunoHost version 2.6.4**
-
-```bash
-ynh_package_autoremove PACKAGE1 PACKAGE2
-```
-> Supprime les paquets `PACKAGE1`, `PACKAGE2`, etc ainsi que tous les paquets qui ne semblent plus utilisé, de manière non interactive et silencieuse.  
-> C'est un `apt-get autoremove` avec les options -y -qq et noninteractive.
 
 
 #### Configuration des applications
@@ -242,6 +260,160 @@ ynh_find_port BEGIN_PORT
 > **Nécessite YunoHost version 2.6**
 
 
+#### Configuration système
+```bash
+ynh_use_logrotate [LOGFILE] [--non-append]
+```
+> Créer un fichier de configuration logrotate pour cette application.  
+Si `LOGFILE` est renseigné, ce fichier de log sera utilisé. Sinon, la configuration concernera le dossier de log /var/log/${app}.  
+Si `--non-append` est ajouté, le fichier de configuration logrotate sera effacé puis recréé.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_remove_logrotate
+```
+> Supprime la configuration logrotate pour cette application.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_add_systemd_config
+```
+> Utilise la configuration systemd présente dans conf/systemd.service pour configurer un service.  
+Les termes `__APP__` et `__FINALPATH__` sont remplacés respectivement par $app et $final_path.  
+Le fichier de configuration est copié dans /etc/systemd/system/$app.service et le service est activé.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_remove_systemd_config
+```
+> Supprime la configuration systemd pour cette application.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_add_nginx_config
+```
+> Utilise la configuration nginx présente dans conf/nginx.conf.  
+Les termes suivant sont remplacés `__PATH__` par $path_url, `__DOMAIN__` par $domain, `__PORT__` par $port, `__NAME__` par $app et `__FINALPATH__` par $final_path.  
+Le fichier de configuration est copié dans /etc/nginx/conf.d/$domain.d/$app.conf et nginx est rechargé.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_remove_nginx_config
+```
+> Supprime la configuration nginx pour cette application.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_add_fpm_config
+```
+> Utilise la configuration phpfpm présente dans conf/php-fpm.conf.  
+Les termes suivant sont remplacés `__NAMETOCHANGE__` par $app, `__FINALPATH__` par $final_path et `__USER__` par $app.  
+Le fichier de configuration est copié dans /etc/php5/fpm/pool.d/$app.conf.  
+Le fichier conf/php-fpm.ini est copié dans /etc/php5/fpm/conf.d/20-$app.ini et php-fpm est rechargé.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_remove_fpm_config
+```
+> Supprime la configuration php-fpm pour cette application.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+#### Backup/restore
+```bash
+ynh_backup DEST
+```
+> Ajoute le fichier ou dossier `DEST` à la liste des fichiers à ajouter au backup de l'application.  
+`DEST` doit être un chemin absolu.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_restore_file DEST
+```
+> Restaure le fichier ou dossier `DEST`.  
+`DEST` doit être un chemin absolu.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_restore
+```
+> Restaure tous les fichiers archivés par le script backup.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+#### Gestion des erreurs
+```bash
+ynh_abort_if_errors
+```
+> Stop immédiatement l'exécution du script si une commande échoue ou si une variable non initialisée est utilisée.  
+> **Nécessite YunoHost version 2.6.4**  
+> Si le script risque de laisser des résidus lors de son arrêt, il est possible d'utiliser la fonction `ynh_clean_setup` pour exécuter des commandes avant l'arrêt effectif du script.  
+> ```bash
+> ynh_clean_setup () {
+>        instructions...
+> }
+> ```
+
+
+```bash
+ynh_backup_before_upgrade
+```
+> Créer un backup de l'application avant de démarrer l'upgrade.  
+> **Nécessite YunoHost version 2.6.4**
+```bash
+ynh_restore_upgradebackup
+```
+> Restaure le backup créé par ynh_backup_before_upgrade en cas d'échec de l'upgrade.  
+> **Nécessite YunoHost version 2.6.4**  
+> Ces 2 helpers s'utilisent de la manière suivante:  
+> ```bash
+> ynh_backup_before_upgrade
+> ynh_clean_setup () {
+> 	ynh_restore_upgradebackup
+> }
+> ynh_abort_if_errors
+> ```
+
+
+#### Vérification du path
+```bash
+ynh_normalize_url_path PATH
+```
+> Corrige le path et renvoi le résultat.
+> ```bash
+> url_path=$(ynh_normalize_url_path $url_path)
+> ```
+> Le path est corrigé de la manière suivante  
+> example -> /example  
+> /example -> /example  
+> /example/ -> /example  
+> / -> /  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_webpath_available DOMAIN PATH
+```
+> Vérifie la disponiblité du path demandé.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_webpath_register APP DOMAIN PATH
+```
+> Réserve le path demandé pour cette application.  
+> **Nécessite YunoHost version 2.6.4**
+
+
 #### Autres commandes
 ```bash
 ynh_string_random LENGTH
@@ -254,6 +426,53 @@ ynh_die MSG RETCODE
 ```
 > Affiche le message `MSG` (sur stderr) et termine le script avec le code `RETCODE` (par défaut 1).
 
+
+```bash
+ynh_store_file_checksum FILE
+```
+> Calcule la somme de contrôle du fichier FILE et la stocke dans la configuration de l'app.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_backup_if_checksum_is_different FILE
+```
+> Compare la somme de contrôle du fichier FILE avec la somme de contrôle précédemment stockée par ynh_store_file_checksum.  
+> Si la somme de contrôle est différente, un backup du fichier est fait.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_secure_remove FILE
+```
+> Supprime le fichier ou dossier FILE en vérifiant que ce n'est pas un dossier système sensible.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_replace_string MATCH_STRING REPLACE_STRING TARGET_FILE
+```
+> Remplace toute les occurences de la chaine `MATCH_STRING` par `REPLACE_STRING` dans le fichier `TARGET_FILE`.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_local_curl URL KEY1=VALUE1 KEY2=VALUE2 ...
+```
+> Effectue une requête curl sur la page `URL` et renseigne les champs POST `KEY1`, `KEY2`, etc par `VALUE1`, `VALUE2`, etc.  
+> Ce helper est surtout utilisé pour remplir les formulaires d'installation des applications.  
+> `URL` ne doit pas contenir le domaine et le path.  
+> **Nécessite YunoHost version 2.6.4**
+
+
+```bash
+ynh_setup_source DEST_DIR [SOURCE_ID]
+```
+> Télécharge la source de l'application, vérifie la somme de contrôle, la décompresse et la copie dans le dossier `DEST_DIR`.  
+> Si SOURCE_ID n'est pas renseigné, il prend la valeur `app`.  
+> Ce helper nécessite un fichier [conf/SOURCE_ID.src](https://github.com/YunoHost/example_ynh/blob/master/conf/app.src) indiquant les informations sur la source à télécharger.  
+> **Nécessite YunoHost version 2.6.4**
+
 <br/>
 
 **Les commandes suivantes sont amenées à être remplacées (voir supprimées) dans les prochaines versions de YunoHost.**