Download the PHP package amphibee/wordpress-eloquent-models without Composer

WordPress Eloquent Models

Le composant WordPress Eloquent Model est une boîte à outils complète fournissant un ORM et un générateur de schéma. Il prend en charge MySQL, Postgres, SQL Server et SQLite. Elle traduit les tables WordPress en modèles compatibles avec Eloquent.

La bibliothèque est idéale pour une utilisation avec Bedrock / Sage de Roots.

Plus besoin d'utiliser la vieille classe moisie WP_Query, on entre dans le monde du futur en produisant du code lisible et ré-utilisable ! Des fonctionnalités supplémentaires sont également disponibles pour une expérience d'utilisation personnalisée à WordPress.

La librairie assurant la compatibilité avec Eloquent, vous pouvez consulter la documentation de l'ORM si vous êtes un peu perdu :)

Sommaire

• Installation
• Mise en place
• Modèles supportés
  • Posts
  • Comments
  • Terms
  • Users
  • Options
  • Menus
• Images
• Alias de champs
• Scope personnalisés
• Pagination
• Meta
• Requête d'un Post à partir d'un champs personnalisé (Meta)
• Advanced Custom Fields
• Création de table
• Requètes avancées
• Type de contenu personnalisés
• Modèles personnalisés
  • Définition du modèle Eloquent
  • Requètes sur modèles personnalisés
• Shortcode
• Logs des requêtes

Installation

La méthode d'installation recommandée est Composer.

Mise en place

La connection à la base de données (via $wpdb) s'effectue au première appel d'un modèle Eloquent. Si vous avez besoin de récupérer l'instance de connection, lancer simplement le code suivant (privilégiez l'usage de use) :

Modèles supportés

Posts

Status

Par défaut, Post retourne l'ensemble des articles quelque soit leur status. Cela peut être modifié via un scope local published pour ne retourner que les articles publiés.

Il est également possible de définir le statut en question via le scope local status.

Post Types

Par défaut, Post retourne l'ensemble des types de contenu. Cea peut être surchargé via le scope local type.

Comments

Terms

Dans cette version Term est accessible en tant que modèle mais n'est accessible que par le biais d'article. Néanmoins, il suffit d'étendre Term pour l'appliquer aux autres types de contenus personnalisés.

Users

Options

Dans WordPress, la récupération d'options s'effectue avec la fonction get_option. Avec Eloquent, pour se passer d'un chargement inutile du Core WordPress, vous pourrez utiliser la fonction get du modèle Option.

Vous pouvez également ajouter d'autres options :

Vous pouvez récupérez l'ensemble des options en tant que tableau (attention aux performances...) :

Vous pouvez également spécifier les options spécifiques à récupérer :

Menus

Pour récupérer un menu à partir de son alias, utiliser la syntaxe ci-dessous. Les éléments du menu seront retournés dans une variable items (c'est une collection d'objet de type AmphiBee\Eloquent\Model\MenuItem).

Les types de menu supportés actuellements sont : Pages, Posts, Custom Links et Categories.

Une fois que vous avez le modèle MenuItem, si vous souhaitez utiliser l'instance d'origine (tels que Page ou Term, par exemple), appelez juste la méthode MenuItem::instance(). L'objet MenuItem est juste un post dont le post_type est égal à nav_menu_item:

La méthode instance() retournera les objets correspondant :

• Post instance pour un élément de menu de type post;
• Page instance pour un élément de menu de type page;
• CustomLink instance pour un élément de menu de type custom;
• Term instance pour un élément de menu de type category.

Multi-levels Menus

Pour gérer les menus à multi-niveaux, vous pouvez effectuer des itérations pour les placer au bon niveau, par exemple.

Vous pouvez utiliser la méthode MenuItem::parent() pour récupérer l'instance parent de l'élément du menu :

Pour grouper les menus par parent, vous pouvez utiliser la méthode ->groupBy()dans la collection $menu->items, qui rassemblera les éléments selon leur parent ($item->parent()->ID).

Pour en savoir plus sur la méthode groupBy(), consulter la documentation de Eloquent.

Alias de champs

Le modèle Post support les alias, donc si vous inspectez un objet Post vous pourrez retrouvez des alias dans le tableau statique $aliases (tels que title pour post_title et content pour post_content.

Vous pouvez étendre le modèle Post pour créer vos propres. Ajoutez juste vos alias dans le modèle étendu, il héritera automatiquement de ceux définis dans le modèle Post:

Scopes personnalisés

Pour ordonner les modèles de type Post ou User, vous pouvez utiliser les scopes newest() et oldest():

Pagination

Pour paginer les résultats, utiliser simplement la méthode paginate() de Eloquent :

Pour afficher les liens de paginations, utiliser la méthode links() :

Meta

L'ensemble de modèles Eloquent intègre une gestion des méta-données de WordPress.

Voici un exemple pour récupérer des metas-données :

Pour créer ou mettre à jour les metas données d'un utilisateur, utilisez juste les méthodes saveMeta() ou saveField(). Elles retourne un booléen à l'instar de la méthode save() de Eloquent.

Il est possible de sauvegarder plusieurs metas données en un seul appel :

La libraire met également les méthodes createMeta() et createField(), qui fonctionnement comment les méthodes saveX(), mais elles ne sont utilisées que pour la création et retourne l'objet de type PostMeta créé par l'instance, au lieu d'un booléen.

Requête d'un Post à partir d'un champs personnalisé (Meta)

Il existe différent moyen d'effectuer une requête à partir d'une méta-donnée (meta) en utilisant des scopes sur un modèle Post (ou tout autre modèle utilisant le trait HasMetaFields) :

Pour vérifier qu'une méta-donnée existe, utiliser le scope hasMeta() :

Si vous souhaiter cible une méta-donnée avec une valeur spécifique, il est possible d'utiliser le scope hasMeta() avec une valeur.

Il est également possible d'effectuer une requête en définissant plusieurs meta-données et plusieurs valeurs associées en passant un tableau de valeur au scope scope hasMeta() :

Si vous devez faire correspondre une chaîne de caractère insensible à la casse ou une correspondance avec des caractères génériques, vous pouvez utiliser le scope hasMetaLike() avec une valeur. Cela utilisera l'opérateur SQL LIKE, il est donc important d'utiliser l'opérateur générique '%'.

Images

Récupération d'une image depuis un modèle Post ou Page.

Pour récupérer une taille d'image spécifique, utiliser la méthode ->size() sur l'objet et renseigner l'alias de taille dans la paramètre (ex. thumbnail ou medium). Si la miniature a été générée, la méthode retourne un objet avec les méta-données, à défaut, c'est l'url d'origine qui est renvoyée (comportement WordPress).

Advanced Custom Fields

La librairie met à disposant la quasi-totalité des champs ACF (à l'exception du champs Google Map). Il permet de récupérer les champs de manière optimale sans passer par le module ACF.

Utilisation basique

Pour récupérer une valeur d'un champs, il suffit d'initialiser un modèle de type Post et d'invoquer le champs personnalisé :

Performance

Lorque l'on utilise $post->acf->website_url, des requètes additionnels sont exécutées pour récupérer le champs selon l'approche de ACF. Il est possible d'utiliser une méthode spécifique pour éviter ces requêtes additionnelles. Il suffit de renseigner le type de contenu personnalisé utilisé en tant que fonction :

PS: La méthode doit être appelée au format camel case. Part eemple, pour le champs de type date_picker vous devez écrire $post->acf->datePicker('fieldName'). La libraire effectue la conversion de camel casse vers snake case pour vous.

Création de table

Doc à venir

Requètes avancées

La librairie étant compatible avec Eloquent, vous pouvez sans problème effectuer des requètes complexes sans tenir compte du contexte WordPress.

Par exemple, pour récupérer les clients dont l'age est supérieur à 40 ans :

Modèles personnalisés

Définition du modèle Eloquent

Pour ajouter vos propres méthode à un modèle existant, vous pouvez réaliser des "extends" de ce modèles. Par exemple, pour le modèle User, vous pourriez produire le code suivant :

Un autre exemple serait de définir une nouvelle taxonomie à un article, par exemple country

Pour accéder au modèle d'un nouveau type de contenu, voici un exemple de ce qui pourrait être proposé :

Requètes sur modèles personnalisés

Il est également possible de travailler avec des types de contenus personnalisés. Vous pouvez utiliser la méthode type(string) ou créer vos propres classes :

En utilisant la méthode type(), l'objet retourné sera de type AmphiBee\Eloquent\Model\Post. En utilisant son propre modèle, cela permet d'aller plus loin dans les possibilités en pouvant y associer des méthodes et des propriétés personnalisés et en retournant le résultat en tant qu'objet Video par exemple.

Type de contenu personnalisé et méta-données :

Shortcode

Implémentation en cours

Logs des requêtes

La Capsule de connexion étant directement rattachée à wpdb, l'ensemble des requètes pourront être visualiser sur des outils de debugs tels que Query Monitor.