Base de données

Persistez le contenu et les paramètres générés par l’utilisateur avec l’API de stockage générique de Elgg.

Contenu

Entités
Fonctionnalité de base de données personnalisée
Systemlog
- Conservation du journal système
- Création de votre propre journal système

Pour créer un objet dans votre code, vous devez instancier un ElggObject. La définition des données est simplement une question d’ajout de variables ou de propriétés d’instance. Les propriétés intégrées sont :

``guid`` Le GUID de l’entité ; défini automatiquement
``owner_guid`` Le GUID de l’utilisateur propriétaire
``subtype`` Une chaîne arbitraire en un seul mot qui définit de quel type d’objet il s’agit, par exemple blog`
``access_id`` Un entier qui représente le niveau d’accès de l’objet
``title`` Le titre de l’objet
``description`` La description de l’objet

Le sous-type d’objet est une propriété spéciale. Il s’agit d’une chaîne arbitraire qui décrit ce qu’est l’objet. Par exemple, si vous écriviez un plugin de blog, votre chaîne de sous-type pourrait être blog. C’est une bonne idée de faire en sorte que cette chaîne soit unique, de sorte que d’autres plugins n’essaient et n’utilisent pas accidentellement le même sous-type. Pour les besoins de ce document, supposons que nous construisons un forum simple. Par conséquent, le sous-type sera forum :

$object = new ElggObject();
$object->setSubtype('forum');
$object->access_id = 2;
$object->save();

access_id est une autre propriété importante. Si vous ne la définissez pas, votre objet sera privé, et seul l’utilisateur qui l’a créé sera en mesure de le voir. Elgg définit des constantes pour les valeurs spéciales de access_id :

ACCESS_PRIVATE Seul son propriétaire peut le voir
ACCESS_LOGGED_IN Tout utilisateur connecté peut le voir
ACCESS_PUBLIC Même les visiteurs non connectés peuvent le voir

L’enregistrement de l’objet remplira automatiquement la propriété $object->guid en cas de succès. Si vous modifiez d’autres propriétés de base, vous pouvez appeler à nouveau $object->save(), ce qui va mettre à jour la base de données pour vous.

Vous pouvez définir des métadonnées sur un objet comme une propriété standard. Disons que nous voulons définir le SKU - référence unique pour les stocks - d’un produit :

$object->SKU = 62784;

Si vous affectez un tableau, toutes les valeurs seront définies pour ces métadonnées. C’est ainsi que, par exemple, vous définissez des balises.

Les métadonnées ne peuvent pas être conservées dans la base de données tant que l’entité n’a pas été enregistrée, mais pour plus de commodité, ElggEntity peut la mettre en cache en interne et l’enregistrer lors de l’enregistrement de l’entité.

Charger un objet 

Par GUID

$entity = get_entity($guid);
if (!$entity) {
    // The entity does not exist or you're not allowed to access it.
}

Mais que faire si vous ne connaissez pas le GUID ? Il y a plusieurs options.

Par utilisateur, sous-type ou site

Si vous connaissez l’ID de l’utilisateur pour lequel vous souhaitez obtenir des objets, ou leur sous-type, vous disposez de plusieurs options. Le plus simple est probablement d’appeler la fonction procédurale elgg_get_entities :

$entities = elgg_get_entities(array(
    'type' => $entity_type,
    'subtype' => $subtype,
    'owner_guid' => $owner_guid,
));

Celle-ci renvoie un tableau d’objets ElggEntity que vous pouvez parcourir. elgg_get_entities dispose d’une pagination par défaut, avec une limite de 10, et un décalage - offset - de 0.

Vous pouvez laisser de côté owner_guid pour obtenir tous les objets, et laisser de côté le sous-type ou le type pour obtenir des objets de tous types/sous-types.

Si vous avez déjà un ElggUser – par exemple via elgg_get_logged_in_user_entity, qui renvoie toujours l’objet de l’utilisateur actuel lorsque vous êtes connecté – vous pouvez simplement utiliser :

$objects = $user->getObjects($subtype, $limit, $offset)

Mais comment fait-on pour obtenir des objets avec une valeur de métadonnée particulière ?

Par propriétés

Vous pouvez récupérer des entités par leurs propriétés en utilisant elgg_get_entities. En utilisant des paramètres spécifiques passés au tableau $options, vous pouvez récupérer des entités par leurs attributs, métadonnées, annotations et relations.

Affichage des entités 

Pour que les entités s’affichent dans les fonctions de liste, vous devez fournir une vue pour l’entité dans le système de vues.

Pour afficher une entité, créez une vue EntityType/subtype où EntityType a l’une des valeurs suivantes :

object : pour les entités dérivées de ElggObject, user : pour les entités dérivées de ElggUser, site : pour les entités dérivées de ElggSite, group : pour les entités dérivées de ElggGroup

Une vue par défaut pour toutes les entités a déjà été créée, elle s’appelle EntityType/default.

Icônes des entités

Les icônes d’entité peuvent être enregistrées à partir de fichiers téléchargés, de fichiers locaux existants, ou d’objets ElggFile existants. Ces méthodes enregistrent la taille master de l’icône définie dans le système. Les autres tailles définies seront générées sur demande.

$object = new ElggObject();
$object->title = 'Example entity';
$object->description = 'An example object with an icon.';

// from an uploaded file
$object->saveIconFromUploadedFile('file_upload_input');

// from a local file
$object->saveIconFromLocalFile('/var/data/generic_icon.png');

// from a saved ElggFile object
$file = get_entity(123);
if ($file instanceof ElggFile) {
        $object->saveIconFromElggFile($file);
}

$object->save();

Les tailles d’images suivantes existent par défaut :

master - 10240px dans la plus grande longueur (sans agrandissement)
large - 200px dans la plus grande dimension (sans agrandissement)
medium - carré de 100px de côté
small - carré de 40px de côté
tiny - carré de 25px de côté
topbar - carré de 16px de côté

Utilisez elgg_get_icon_sizes() pour obtenir toutes les tailles d’icône possibles pour un type et un subtype d’entité spécifiques. La fonction déclenche l’événement entity:icon:sizes event.

Pour vérifier si une icône est définie, utilisez $object->hasIcon($size).

Vous pouvez récupérer l’URL de l’icône générée avec la méthode ElggEntity::getIconURL($params). Cette méthode accepte un argument $params comme tableau qui spécifie la taille, le type et fournit un contexte supplémentaire pour l’événement afin de déterminer l’icône à servir. La méthode déclenche l’événement entity:icon:url event.

Utilisez elgg_view_entity_icon($entity, $size, $vars) pour afficher une icône. Cela analysera les emplacements suivants pour trouver une vue et inclura la première qui correspond.

views/$viewtype/icon/$type/$subtype.php
views/$viewtype/icon/$type/default.php
views/$viewtype/icon/default.php

Où

$viewtype: Type de vue, par ex. 'default' ou 'json'.
$type: Type d’entité, par ex. 'group' ou 'user'.
$subtype: Sous-type d’entité, par ex. 'blog' ou 'page'.

Vous n’êtes pas obligé de renvoyer une icône de secours du gestionnaire d’événements. Si aucune icône téléchargée n’est trouvée, le système de visualisation analysera les vues (dans cet ordre spécifique) :

views/$viewtype/$icon_type/$entity_type/$entity_subtype.svg
views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.gif
views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.png
views/$viewtype/$icon_type/$entity_type/$entity_subtype/$size.jpg

Où

$viewtype: Type de vue, par ex. 'default' ou 'json'.
$icon_type: Type d’icône, par ex. 'icon' ou 'cover_image'.
$entity_type: Type d’entité, par ex. 'group' ou 'user'.
$entity_subtype: Sous-type d’entité, par ex. 'blog' ou 'page' (ou 'default' si l’entité n’a pas de sous-type).
$size: Taille de l’icône (notez que nous n’utilisons pas la taille avec les icônes svg)

Les méthodes des icônes permettent de passer un type d’icône si une entité possède plus d’une icône. Par exemple, un utilisateur peut avoir un avatar et une icône de photo de couverture. Vous passeriez 'cover_photo' comme type d’icône :

$object->saveIconFromUploadedFile('uploaded_photo', 'cover_photo');

$object->getIconUrl([
        'size' => 'medium',
        'type' => 'cover_photo'
]);

Note

Les types d’icônes personnalisées (par ex. les photos de couverture) n’ont qu’un préréglage pour la taille master, pour ajouter des tailles personnalisées, utilisez l”événement entity::url pour les configurer.

Par défaut, les icônes seront stockées dans /icons/<icon_type>/<size>.jpg par rapport au répertoire de l’entité sur le répertoire de fichiers. Pour fournir un autre emplacement, utilisez l”événement entity:<icon_type>:file.

Ajout, lecture et suppression des annotations 

Les annotations peuvent être utilisées, par exemple, pour suivre les évolutions des notes. Pour annoter une entité, vous pouvez utiliser la méthode annotate() de l’objet. Par exemple, pour donner à un article de blog une note de 5, vous pouvez utiliser :

$blog_post->annotate('rating', 5);

Pour récupérer les notes sur l’article de blog, utilisez $blogpost->getAnnotations('rating') et si vous souhaitez supprimer une annotation, vous pouvez opérer sur la classe ElggAnnotation, par ex. $annotation->delete().

La récupération d’une seule annotation peut être faite avec get_annotation() si vous avez l’ID de l’annotation. Si vous supprimez une ElggEntity de quelque nature que ce soit, toutes ses métadonnées, annotations et relations seront également supprimées automatiquement.

Étendre ElggEntity 

Si vous dérivez de l’une des classes du noyau Elgg, vous devrez dire à Elgg comment instancier correctement le nouveau type d’objet afin que get_entity() et assimilés renvoient la classe PHP appropriée. Par exemple, si je personnalise ElggGroup dans une classe appelée Committee, je dois faire connaître à Elgg le nouveau mappage. Voici un exemple d’extension de classe :

// Class source
class Committee extends ElggGroup {

    protected function initializeAttributes() {
        parent::initializeAttributes();
        $this->attributes['subtype'] = 'committee';
    }

    // more customizations here
}

Dans votre fichier elgg-plugin.php ajoutez la section entities.

<?php // mod/example/elgg-plugin.php
return [
    // entities registration
    'entities' => [
                    [
                            'type' => 'group',
                            'subtype' => 'committee',
                            'class' => 'Committee',
                            'capabilities' => [
                                    'searchable' => true,
                            ],
                    ],
            ],
];

Les entités seront enregistrées lors de l’activation du plugin.

Maintenant, si vous invoquez get_entity() avec le GUID d’un objet de comité, vous récupérerez un objet de type Comité - Committee.

Fonctionnalités avancées 

URLs des entités

Les URLs d’entité sont fournies par l’interface getURL() et fournissent au framework Elgg un moyen commun de diriger les utilisateurs vers le gestionnaire d’affichage approprié pour n’importe quel objet donné.

Par exemple, une page de profil dans le cas des utilisateurs.

L’URL est définie à l’aide de la fonction elgg\_register\_entity\_url\_handler(). La fonction que vous enregistrez doit renvoyer l’URL appropriée pour le type donné - qui peut elle-même être une adresse configurée par un gestionnaire de page.

Le gestionnaire par défaut doit utiliser l’interface d’export par défaut.

Performance de chargement des entités

elgg_get_entities dispose de quelques options qui peuvent être utiles pour améliorer les performances.

preload_owners : Si les entités récupérées sont affichées dans une liste avec des informations sur le propriétaire, vous pouvez définir cette option sur true pour charger efficacement les utilisateurs propriétaires des entités récupérées.
preload_containers : Si les entités récupérées sont affichées dans une liste avec des informations sur leurs conteneurs, vous pouvez définir cette option sur true pour les charger efficacement.
distinct : Quand Elgg récupère des entités à l’aide d’une requête SQL, Elgg doit être sûr que chaque ligne d’entité n’apparaît qu’une seule fois dans le jeu de résultats. Par défaut, il inclut un modificateur DISTINCT sur la colonne GUID pour l’appliquer, mais certaines requêtes renvoient naturellement des entités uniques. La définition de l’option distinct sur false supprime ce modificateur et s’appuie sur la requête pour s’assurer de l’unicité des résultats.

Le fonctionnement interne des requêtes d’entités Elgg est un sujet complexe et il est recommandé de demander de l’aide sur le site de la communauté Elgg avant d’utiliser l’option distinct.

Fonctionnalité de base de données personnalisée 

Il est fortement recommandé d’utiliser des entités dans la mesure du possible. Toutefois, Elgg prend en charge les requêtes SQL personnalisées à l’aide de l’API de base de données.

Systemlog 

Note

Cette section requiert une certaine attention et risque de contenir des informations obsolètes

Le journal système de Elgg par défaut est un moyen simple d’enregistrer ce qui se passe dans un système Elgg. Il est visible et consultable directement à partir du panneau d’administration.

Conservation du journal système 

Une ligne de journal système est stockée chaque fois qu’un événement concernant un objet dont la classe implémente l’interface Loggable est déclenché. ElggEntity et ElggExtender implémentent Loggable, de sorte qu’une ligne de journal système est créée chaque fois qu’un événement est effectué sur tous les objets, utilisateurs, groupes, sites, métadonnées et annotations.

Les événements courants comprennent :

create
update
delete
login

Création de votre propre journal système 

Il y a quelques raisons pour lesquelles vous pouvez vouloir créer votre propre journal système. Par exemple, vous pourriez avoir besoin de stocker une copie complète des entités lorsqu’elles sont mises à jour ou supprimées, à des fins d’audit. Vous pourriez aussi avoir besoin d’aviser un administrateur lorsque certains types d’événements se produisent.

Pour ce faire, vous pouvez créer une fonction qui écoute tous les événements pour tous les types d’objets :

register_elgg_event_handler('all','all','your_function_name');

Votre fonction peut alors être définie comme :

function your_function_name($object, $event) {
   if ($object instanceof Loggable) {
      ...
   }
}

Vous pouvez ensuite utiliser les méthodes supplémentaires définies par Loggable pour extraire les informations dont vous avez besoin.