Skip to content

Draft: Dossier 'includes/'

Mise en place d'un dossier includes/ et réorganisation/réécriture de certaines logiques du plugin en respectant les WordPress Coding Standards (avec ce fichier de configuration).

L'utilisation de ce dossier est une convention officieuse, utilisée par bon nombre de plugins (dont WooCommerce), qui aide à respecter la recommandation suivante :

The root level of your plugin directory should contain your plugin-name.php file and, optionally, your uninstall.php file. All other files should be organized into sub folders whenever possible.

-- Plugin Best Practices / File Organization

Objectifs

Les objectifs sont nombreux et certains peut-être idéalistes, l'idée n'est pas non plus de changer-pour-changer.
Voici tout de même une petite liste non exhaustive des buts de ce merge request.

Prise en main plus facile pour les développeurs WP

Une normalisation plus conventionnelle permettra aux développeurs WordPress de s'y retrouver plus facilement, même sans connaissance de la logique "métier" du plugin.

Uniformisation

Les coding standards peuvent être discutable, leur intérêts parfois subjectifs et leur application très souvent contraignante.

Utiliser les mêmes directives lors du développement permet toutefois de s'assurer que les différents contributeurs vont procéder de façon similaire.

Documentation

Les coding standards imposent que chaques fichiers, fonctions et arguments soit documentés.

C'est là encore très contraignant mais cela permet de comprendre rapidement les buts, et parfois les particularités, de ces différents éléments. Encore plus quand on revient dessus longtemps après leurs implémentations.

Extensibilité

WordPress est extensible, cela est possible principalement grâce aux Hooks (actions et filtres) mis en place.
Ceci permet d'étendre ou modifier son fonctionnement, d'où le large choix de plugins et thèmes disponibles.

En utilisant autant que possible les fonctions natives (qui utilisent souvent des hooks; ex. get_posts()) et des hooks "personnalisés", il devient alors possible de rendre le plugin également extensible.
C'est le cas par exemple du plugin WooCommerce, pour lesquels une multitude de plugins existent.

Cette possibilité d'extensibilité permet également aux "webmasters" de modifier les comportements par défaut de WordPress et des plugins/themes selon leurs besoins.

En procédant ainsi, il devient plus facile de répondre à une demande de fonctionnalité :
"Ce n'est pas prévu, mais vous pouvez le faire via ceci ou cela".

Fonctionnements à la WordPress

Ce point est assez vague mais je vais prendre en exemple l'utilisation massive d'Ajax par le plugin.
Cela engendre (selon moi; c'est encore une fois très sugestif) les problèmes suivants :

  • Provenance/origine de la requête
    Face à une fonction déclarée wp_ajax, rien ne permet d'en connaitre facilement l'origine
  • Extensibilité
    Enregistrer le contenu d'un post type en Ajax (et donc en contournant les méthodes standard pour cette action) enlève les possibilité de modifications éventuelles lors de cette action (à moins de les réimplémenter soi-même)
  • Sécurité
    Même exemple que pour le point 2, il faut réimplémenter soi-même les vérifications/validations pour cette action
  • Débogage
    Je prend pour exemple le plugin Debug Bar qui permet (si configuré correctement) de lister les requêtes SQL de la page. Ceci ne fonctionnera hélas pas avec les requêtes Ajax.

Les points intéressants

Une fois encore, ceci est sugestif. Cette section sert aussi à documenter brièvement les gros éléments de ce merge request.

La classe Next_WPOF

(nommée provisoirement "Next_" car une classe WPOF existe déjà)

Elle est en charge d'initialiser le reste du plugin et (progressivement) alléger le fichier principal du plugin.
Elle devrait (à terme) être accessible via la globale $wpof et être une des seules variables globales du plugin.

Les autres gros composants du plugin seront accessibles en tant que propriétés/attributs, comme c'est le cas actuellement pour la classs WPOF_Admin (accessible le cas échéant via $wpof->admin).

Nous pourons éventuellement envisager un composant WPOF_Gestion qui ne serait chargé que si l'utilisateur est identifié en tant que gestionnaire, et qui serait accessible via $wpof->gestion.

La classe WPOF_Admin

Chargée conditionnellement, elle a un rôle similaire à la classe Next_WPOF et initialise les éléments nécessaires au backoffice.

Ce fonctionnement par composants permet une organisation et un chargement des éléments par arborescence, et peut être étendu à d'autres composants, si nécessaire, comme évoqué plus haut.

Les meta boxes

(ne concerne actuellement que les modèles; peut être considéré comme un sous-composant Admin)

La classe WPOF_Admin_Meta_Boxes

Centralise les meta boxes du plugin et gère d'une part l'affichage des champs et l'enregistrements des valeurs.

Elle effectue une partie des opérations de vérifications et validations (nonce, permissions) avant d'émettre une action personnalisée wpof_process_{$post-post_type}_meta.

Les classes WPOF_Admin_Meta_Box_xxx

Ces classes (utilisées conjointement avec WPOF_Admin_Meta_Boxes) gèrent chacune l'affichage d'une box (méthode output) et l'enregistrement de ses valeurs (méthode save).
Cette approche à l'avantage de retrouver dans le même fichier tout ce qui concerne chaques meta boxes.

Dans le cas où une meta box doit afficher/générer beaucoup d'HTML, l'utilisation d'une view permet de gagner en lisibilité (comme c'est le cas avec le fichier views/html-modele-data.php).

La classe WPOF_Post

Classe générique et destinée à être étendue par les différents CPT (actuellement seul WPOF_Modele l'utilise).
Elle devrait faciliter l'accès aux propriétés et metas des CPT.

On peut étendre le principe aux autres CPT du plugin.

Les fonctions de récupération des modèles

Il y en a plusieurs : wpof_get_modeles(), wpof_get_modele() et wpof_get_modele_by_slug().

La fonction wpof_get_modeles() est un exemple concret d'extensibilité.
Bien que inutile dans l'utilisation par le plugin, cette fonction accepte un tableau de paramètres et utilise la fonction native get_posts().

Cela permet du coup à quiconque de récupérer des modèles selon ses critères (quantité, ordre, propriétés, metas).
(on aurait même pu envisager de mettre en place un hook/filter wpof_get_modeles_args)

On peut étendre le principe aux autres CPT du plugin (voire même adapter pour les non CPT; ex. aide).

Merge request reports