Objectif du plugin
Les conversions de documents (audios, videos, textuels ou images) sont en général des traitements lourds qui peuvent prendre de plusieurs minutes à plusieurs heures à s’exécuter et nécessitent énormément de puissance serveur.
Il est donc nécessaire d’éviter le fait que plusieurs conversions ne s’exécutent en même temps, mais plutôt les unes après les autres.
Fonctionnement du plugin
Le plugin installe une nouvelle table dans la base de données composée de 9 champs différents :
-
id_facd_conversion
int : l’identifiant numérique de la conversion ; -
id_document
int : l’identifiant numérique du document à convertir ; -
id_auteur
int : l’identifiant numérique de l’auteur demandant la conversion ; -
fonction
string : le nom de la fonction de conversion (voir le nommage des fonctions de conversions) ; -
options
string : array serialisé des options à passer à la fonction de conversion ; -
extension
string : extension vers laquelle doit être converti notre document ; -
statut
string : statut de la conversion ; -
infos
string ; -
maj
timestamp : date de mise à jour de la conversion ;
Le principe consiste à ce que chaque plugin proposant de convertir un document dans un autre format insère une ligne dans cette table indiquant les différentes informations.
Ensuite, c’est le plugin facd qui lancera la conversion par cron lorsque cela sera possible.
Les statuts de conversion
Un élément de la file d’attente peut avoir 4 statuts différents :
-
non
: la conversion est en attente, statut par défaut ; -
oui
: la conversion a été réalisée avec succès ; -
en_cours
: la conversion est en cours ; -
erreur
: la conversion a échoué ;
Nommage des fonctions de conversion
Le plugin accepte plusieurs noms de fonctions de conversion, dans l’ordre :
-
convertir_nom_fonction()
qui se situerait dans un fichierconvertir/nom_fonction.php
de votre plugin ; -
inc_nom_fonction
qui se situerait dans un fichierinc/nom_fonction.php
de votre plugin ; -
convertir_extension_entree_extension_sortie()
oùextension_entree
est l’extension de fichier d’entrée etextension_sortie
l’extension du fichier de sortie souhaitée. Cette fonction devrait se situer dans le fichierconvertir/extension_entree_extension_sortie.php
, par exemple une fonctionconvertir_kml_geojson()
dans le fichierconvertir/kml_geojson.php
qui convertirait des fichiers de type.kml
en.geojson
; -
convertir_extension_entree()
dans un fichierconvertir/extension_entree.php
de votre plugin oùextension_entree
est l’extension du fichier d’entrée. Par exemple, une fonctionconvertir_flv()
dans un fichierconvertir/flv.php
qui pourrait convertir les fichiers .flv en.mp4
et.webm
;
La fonction de conversion reçoit deux arguments :
-
$id_document
qui est l’identifiant numérique du document à convertir ; -
$options
qui sont les options de conversions ;
L’argument $options
est un tableau comprenant :
-
id_facd_conversion
, qui est l’identifiant numérique de la conversion dans la table de la base de données de la file d’encodage (inséré automatiquement) ; -
format
, qui est la valeur du champextension
de la table de la file d’encodage (doit être inséré par votre plugin appelant FACD) ; -
debut_conversion
, qui est le timestamp du début de la conversion ;
Il est ensuite complété de la déserialisation du champs options
de la table de la file d’encodage qui doit être un tableau serialisé (doit être inséré par votre plugin appelant FACD) ;
Voir le fichier inc/facd_convertir.php
du plugin pour plus d’informations.
Retour des fonctions de conversion
Les retours des fonctions de conversions doivent respecter un le formalisme suivant.
Une fonction doit retourner « false » (booléen) ou un tableau (array) de la sorte :
- success bool true/false ;
- erreur string : le message d’erreur en cas d’erreurs ;
- id_document int : l’identifiant du nouveau document si possible ;
- info array : un array des informations à mettre dans le champ
infos
en base ; - statut string oui|non : le statut à donner à l’identifiant de la file d’encodage par exemple, si on souhaite ne pas le considérer comme fini (oui)
Si votre fonction renvoie bien ce tableau, avec la valeur de success
à true
, la conversion est considérée comme réussie et son statut passe à oui
. Dans le cas contraire, si la valeur success
est à false
ou si votre fonction ne retourne pas un tableau, la conversion est considérée comme échouée et son statut passe à erreur
..
Réussite d’une conversion
Vous pouvez, dans le retour de la fonction de conversion, retourner un tableau infos
.
Celui ci sera ajouté au tableau $infos
passé en paramètre de la fonction d’encodage, il peut vous servir pour stocker diverses informations sur la conversion pouvant vous être utile par la suite.
Un élément fin_conversion
, de type timestamp, est également ajouté à ce tableau. Il correspond au timestamp de la fin de la conversion (debut_conversion
et fin_conversion
peuvent ensuite être utile à des fins de statistiques par exemple)
Ce tableau est serialisé et inséré dans le champ infos
de la conversion.
Échec d’une conversion
Même en cas d’erreur, la valeur de infos
sera ajoutée à la précédente ainsi que fin_conversion
.
Vous pouvez également ajouter une chaîne erreur
qui peut par exemple être le log de retour du binaire servant à convertir votre fichier. Il sera inséré dans le tableau du champ options
également.
Insérer une demande de conversion
Pour demander l’ajout de la conversion d’un fichier dans la file d’encodage ces lignes suffisent :
include_spip('action/facd_ajouter_conversion');
facd_ajouter_conversion_file($id_document,'nom_fonction',$extension_sortie,$options,$mode_document);
Lancer une conversion manuellement
Les conversions sont lancées par le CRON à intervalle régulier.
Cependant si vous souhaitez forcer le début d’un conversion, vous pouvez utiliser ce code :
$conversion_directe = charger_fonction('facd_convertir_direct','inc');
$conversion_directe();
La conversion se lancera en asynchrone en utilisant la fonction PHP fsockopen()
, elle rendra donc directement la main sans devoir attendre la fin de la conversion qui peut prendre beaucoup de temps (dans le cas d’une vidéo par exemple).
Et visuellement ? Dans l’espace privé
Le plugin ajoute une page ?exec=facd
dans l’espace privé du site, accessible depuis le bouton File d'attente de conversion
sous le menu Maintenance
.
Cette page liste dans un premier bloc les conversions qui ne sont pas encore achevées. Si une ou plusieurs conversions sont en erreur, il sera possible de relancer sa conversion depuis ce bloc.
Dans un second bloc, l’ensemble des conversions achevées sont affichées.
Exemples de plugins utilisant FACD :
Les plugins suivants nécessitent FACD pour leur bon fonctionnement :
- doc2img ;
- SPIPmotion ;
Aucune discussion
Ajouter un commentaire
Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :
Merci d’avance pour les personnes qui vous aideront !
Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.
Suivre les commentaires : |