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 d’Elgg.

Contenus

Entités
Fonctionnalité de base de données personnalisée
- Exemple : exécuter un script SQL lors de l’activation du plugin
Systemlog
- Conservation du journal système
- Créer 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 les suivantes :

``guid`` Le GUID de l’entité ; défini automatiquement
``owner_guid`` Le GUID de l’utilisateur propriétaire
``site_guid`` Le GUID du site contenant l’entité. Défini automatiquement quand une instance de ElggObject est créée
``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 peut ê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 pas accidentellement d’utiliser 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->subtype = "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_FRIENDS Seuls son propriétaire et ses contacts peuvent 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, le sous-type ou le site, 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,
));

Ceci renvoie un tableau d’objets ElggEntity que vous pouvez itérer. elgg_get_entities a une pagination par défaut, avec une limite de 10, et un et 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 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 qu’en est-il d’obtenir des objets ayant une valeur de métadonnée particulière ?

Par métadonnée¶

La fonction elgg_get_entities_from_metadata permet d’extraire des entités avec des métadonnées de diverses manières.

Par annotation¶

La fonction elgg_get_entities_from_annotations permet d’extraire des entités avec des métadonnées de différentes manières.

Note

À partir de Elgg 1.10, le comportement par défaut de elgg_get_entities_from_annotations a été aligné avec le reste des fonctions elgg_get_entities*.

Avant Elgg 1.10 le tri des entités été basé sur le dernier ajout d’une annotation (dans les $options vous pourriez ajouter $options[“order_by”] = “maxtime ASC” ou $options[“order_by”] = “maxtime DESC”. À partir de Elgg 1.10, cela a été changé pour l’heure de création de l’entité, tout comme pour le reste des fonctions elgg_get_entities*. Pour retrouver l’ancien comportement, ajoutez ce qui suit à vos $options :

$options['selects'] = array('MAX(n_table.time_created) AS maxtime');
$options['group_by'] = 'n_table.entity_guid';
$options['order_by'] = 'maxtime ASC'

or

$options['order_by'] = 'maxtime DESC'

Afficher 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 toutes les tailles d’icônes définies dans le système.

$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 - 550px pour le bord le plus long (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ônes possibles pour un type d’entité et un sous-type spécifiques. La fonction déclenche le hook entity:icon:sizes.

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 comme argument le tableau $params qui spécifie la taille, le type, et fournit un contexte supplémentaire pour que le hook détermine l’icône à servir. La méthode déclenche le hook entity:icon:url.

Utilisez elgg_view_entity_icon($entity, $size, $vars) pour afficher une icône. Cela analysera les emplacements suivants pour 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'.

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'
]);

Notez que les types d’icônes personnalisés (par ex. les photos de couverture) n’ont pas de tailles et de coordonnées prédéfinies. Utilisez le hook entity:<icon_type>: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é dans le répertoire des données. Pour fournir un emplacement alternatif, utilisez le hook entity::file.

Ajouter, lire et supprimer des annotations ¶

Les annotations peuvent être utilisées, par exemple, pour suivre les évolutions des notations. 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 notations 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 exemple $annotation->delete().

La récupération d’une seule annotation peut se faire 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 renvoie 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
}

function committee_init() {

    register_entity_type('group', 'committee');

    // Tell Elgg that group subtype "committee" should be loaded using the Committee class
    // If you ever change the name of the class, use update_subtype() to change it
    add_subtype('group', 'committee', 'Committee');
}

register_elgg_event_handler('init', 'system', 'committee_init');

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

Ce modèle a été extrait de la définition de ElggFile.

Fonctionnalités avancées ¶

URLs des entités¶

Les URLs d’entité sont fournies par l’interface getURL() et fournissent à l’infrastructure 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 lui-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 parfois ê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.

Notes pré-1.8 ¶

update_subtype() : cette fonction est nouvelle dans 1.8. Dans les versions antérieures, vous deviez modifier la base de données à la main si vous changiez le nom de classe associé à un sous-type donné.

elgg_register_entity_url_handler() : cette fonction est nouvelle dans 1.8. Elle déprécie register_entity_url_handler(), que vous devez utiliser si vous développez pour une version pré-1.8 de Elgg.

elgg_get_entities_from_metadata() : cette fonction est nouvelle dans 1.8. Elle déprécie get_entities_from_metadata(), que vous devez utiliser si vous développez pour une version pré-1.8 de Elgg.

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.

Exemple : exécuter un script SQL lors de l’activation du plugin ¶

Cet exemple montre comment remplir votre base de données lors de l’activation du plugin.

my_plugin/activate.php :

if (!elgg_get_plugin_setting('database_version', 'my_plugin') {
    run_sql_script(__DIR__ . '/sql/activate.sql');
    elgg_set_plugin_setting('database_version', 1, 'my_plugin');
}

my_plugin/sql/activate.sql :

-- Create some table
CREATE TABLE prefix_custom_table(
    id INTEGER AUTO_INCREMENT,
    name VARCHAR(32),
    description VARCHAR(32),
    PRIMARY KEY (id)
);

-- Insert initial values for table
INSERT INTO prefix_custom_table (name, description)
VALUES ('Peter', 'Some guy'), ('Lisa', 'Some girl');

Notez que Elgg exécute des instructions par le biais des fonctions intégrées de PHP et qu’il dispose d’une prise en charge limitée des commentaires. C’est-à-dire que seuls les commentaires d’une seule ligne sont pris en charge et qu’ils doivent être préfixés par « – » ou « # « . Un commentaire doit commencer au tout début d’une ligne.

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 design/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éer 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.