Aller au contenu
XOOPS 2.7 Docs

Classe XoopsObject

La classe XoopsObject est la classe de base fondamentale pour tous les objets de données du système XOOPS. Elle fournit une interface standardisée pour gérer les propriétés d’objets, la validation, le suivi des modifications et la sérialisation.

Vue d’ensemble de la classe

Section intitulée « Vue d’ensemble de la classe »
namespace Xoops\Core;


class XoopsObject
{
    protected array $vars = [];
    protected array $cleanVars = [];
    protected bool $isNew = true;
    protected array $errors = [];
}

Hiérarchie des classes

Section intitulée « Hiérarchie des classes »
XoopsObject
├── XoopsUser
├── XoopsGroup
├── XoopsModule
├── XoopsBlock
├── XoopsComment
├── XoopsNotification
├── XoopsConfig
└── [Objets de modules personnalisés]

Propriétés

Section intitulée « Propriétés »
PropriétéTypeVisibilitéDescription
$varsarrayprotégéStocke les définitions et valeurs de variables
$cleanVarsarrayprotégéStocke les valeurs nettoyées pour les opérations base de données
$isNewboolprotégéIndique si l’objet est nouveau (pas encore dans la base de données)
$errorsarrayprotégéStocke les messages d’erreur et de validation

Constructeur

Section intitulée « Constructeur »
public function __construct()

Crée une nouvelle instance XoopsObject. L’objet est marqué comme nouveau par défaut.

Exemple :

$object = new XoopsObject();
// L'objet est nouveau et n'a pas de variables définies

Méthodes principales

Section intitulée « Méthodes principales »

initVar

Section intitulée « initVar »

Initialise une définition de variable pour l’objet.

public function initVar(
    string $key,
    int $dataType,
    mixed $value = null,
    bool $required = false,
    int $maxlength = null,
    string $options = ''
): void

Paramètres :

ParamètreTypeDescription
$keystringNom de la variable
$dataTypeintConstante de type de données (voir Types de données)
$valuemixedValeur par défaut
$requiredboolSi le champ est obligatoire
$maxlengthintLongueur maximale pour les types string
$optionsstringOptions supplémentaires

Types de données :

ConstanteValeurDescription
XOBJ_DTYPE_TXTBOX1Entrée boîte texte
XOBJ_DTYPE_TXTAREA2Contenu textarea
XOBJ_DTYPE_INT3Valeur entière
XOBJ_DTYPE_URL4String URL
XOBJ_DTYPE_EMAIL5Adresse email
XOBJ_DTYPE_ARRAY6Tableau sérialisé
XOBJ_DTYPE_OTHER7Type personnalisé
XOBJ_DTYPE_SOURCE8Code source
XOBJ_DTYPE_STIME9Format horodatage court
XOBJ_DTYPE_MTIME10Format horodatage moyen
XOBJ_DTYPE_LTIME11Format horodatage long
XOBJ_DTYPE_FLOAT12Nombre décimal
XOBJ_DTYPE_DECIMAL13Nombre décimal
XOBJ_DTYPE_ENUM14Énumération

Exemple :

class MyObject extends XoopsObject
{
    public function __construct()
    {
        parent::__construct();
        $this->initVar('id', XOBJ_DTYPE_INT, null, false);
        $this->initVar('title', XOBJ_DTYPE_TXTBOX, '', true, 255);
        $this->initVar('content', XOBJ_DTYPE_TXTAREA, '', false);
        $this->initVar('email', XOBJ_DTYPE_EMAIL, '', true, 100);
        $this->initVar('created', XOBJ_DTYPE_INT, time(), false);
        $this->initVar('status', XOBJ_DTYPE_INT, 1, true);
    }
}

setVar

Section intitulée « setVar »

Définit la valeur d’une variable.

public function setVar(
    string $key,
    mixed $value,
    bool $notGpc = false
): bool

Paramètres :

ParamètreTypeDescription
$keystringNom de la variable
$valuemixedValeur à définir
$notGpcboolSi true, la valeur ne vient pas de GET/POST/COOKIE

Retour : bool - True si succès, false sinon

Exemple :

$object = new MyObject();
$object->setVar('title', 'Hello World');
$object->setVar('content', '<p>Contenu ici</p>', true); // Pas de saisie utilisateur
$object->setVar('status', 1);

getVar

Section intitulée « getVar »

Récupère la valeur d’une variable avec formatage optionnel.

public function getVar(
    string $key,
    string $format = 's'
): mixed

Paramètres :

ParamètreTypeDescription
$keystringNom de la variable
$formatstringFormat de sortie

Options de format :

FormatDescription
's'Affichage - Entités HTML échappées pour l’affichage
'e'Édition - Pour les valeurs d’entrée de formulaire
'p'Aperçu - Similaire à l’affichage
'f'Données formulaire - Brutes pour le traitement de formulaires
'n'Aucun - Valeur brute, sans formatage

Retour : mixed - La valeur formatée

Exemple :

$object = new MyObject();
$object->setVar('title', 'Hello <World>');


echo $object->getVar('title', 's'); // "Hello &lt;World&gt;"
echo $object->getVar('title', 'e'); // "Hello &lt;World&gt;" (pour valeur input)
echo $object->getVar('title', 'n'); // "Hello <World>" (brut)


// Pour les types de données tableaux
$object->setVar('options', ['a', 'b', 'c']);
$options = $object->getVar('options', 'n'); // Retourne le tableau

setVars

Section intitulée « setVars »

Définit plusieurs variables à la fois à partir d’un tableau.

public function setVars(
    array $values,
    bool $notGpc = false
): void

Paramètres :

ParamètreTypeDescription
$valuesarrayTableau associatif de paires clé => valeur
$notGpcboolSi true, les valeurs ne viennent pas de GET/POST/COOKIE

Exemple :

$object = new MyObject();
$object->setVars([
    'title' => 'My Title',
    'content' => 'My content',
    'status' => 1
]);


// Depuis la base de données (pas de saisie utilisateur)
$object->setVars($row, true);

getValues

Section intitulée « getValues »

Récupère toutes les valeurs de variables.

public function getValues(
    array $keys = null,
    string $format = 's',
    int $maxDepth = 1
): array

Paramètres :

ParamètreTypeDescription
$keysarrayClés spécifiques à récupérer (null pour toutes)
$formatstringFormat de sortie
$maxDepthintProfondeur maximale pour les objets imbriqués

Retour : array - Tableau associatif de valeurs

Exemple :

$object = new MyObject();


// Obtenir toutes les valeurs
$allValues = $object->getValues();


// Obtenir des valeurs spécifiques
$subset = $object->getValues(['title', 'status']);


// Obtenir les valeurs brutes pour la base de données
$rawValues = $object->getValues(null, 'n');

assignVar

Section intitulée « assignVar »

Assigne une valeur directement sans validation (utiliser avec prudence).

public function assignVar(
    string $key,
    mixed $value
): void

Paramètres :

ParamètreTypeDescription
$keystringNom de la variable
$valuemixedValeur à assigner

Exemple :

// Assignation directe depuis une source de confiance (ex. base de données)
$object->assignVar('id', $row['id']);
$object->assignVar('created', $row['created']);

cleanVars

Section intitulée « cleanVars »

Nettoie toutes les variables pour les opérations base de données.

public function cleanVars(): bool

Retour : bool - True si toutes les variables sont valides

Exemple :

$object = new MyObject();
$object->setVar('title', 'Test');
$object->setVar('email', 'user@example.com');


if ($object->cleanVars()) {
    // Les variables sont nettoyées et prêtes pour la base de données
    $cleanData = $object->cleanVars;
} else {
    // Des erreurs de validation se sont produites
    $errors = $object->getErrors();
}

isNew

Section intitulée « isNew »

Vérifie ou définit si l’objet est nouveau.

public function isNew(): bool
public function setNew(): void
public function unsetNew(): void

Exemple :

$object = new MyObject();
echo $object->isNew(); // true


$object->unsetNew();
echo $object->isNew(); // false


$object->setNew();
echo $object->isNew(); // true

Méthodes de gestion des erreurs

Section intitulée « Méthodes de gestion des erreurs »

setErrors

Section intitulée « setErrors »

Ajoute un message d’erreur.

public function setErrors(string|array $error): void

Exemple :

$object->setErrors('Le titre est obligatoire');
$object->setErrors(['Erreur champ 1', 'Erreur champ 2']);

getErrors

Section intitulée « getErrors »

Récupère tous les messages d’erreur.

public function getErrors(): array

Exemple :

$errors = $object->getErrors();
foreach ($errors as $error) {
    echo $error . "\n";
}

getHtmlErrors

Section intitulée « getHtmlErrors »

Retourne les erreurs formatées en HTML.

public function getHtmlErrors(): string

Exemple :

if (!$object->cleanVars()) {
    echo '<div class="error">' . $object->getHtmlErrors() . '</div>';
}

Méthodes utilitaires

Section intitulée « Méthodes utilitaires »

toArray

Section intitulée « toArray »

Convertit l’objet en tableau.

public function toArray(): array

Exemple :

$object = new MyObject();
$object->setVar('title', 'Test');
$data = $object->toArray();
// ['title' => 'Test', ...]

getVars

Section intitulée « getVars »

Retourne les définitions des variables.

public function getVars(): array

Exemple :

$vars = $object->getVars();
foreach ($vars as $key => $definition) {
    echo "Champ : $key, Type : {$definition['data_type']}\n";
}

Exemple d’utilisation complet

Section intitulée « Exemple d’utilisation complet »
<?php
/**
 * Objet Article personnalisé
 */
class Article extends XoopsObject
{
    /**
     * Constructeur - Initialiser toutes les variables
     */
    public function __construct()
    {
        parent::__construct();


        // Clé primaire
        $this->initVar('article_id', XOBJ_DTYPE_INT, null, false);


        // Champs obligatoires
        $this->initVar('title', XOBJ_DTYPE_TXTBOX, '', true, 255);
        $this->initVar('author_id', XOBJ_DTYPE_INT, 0, true);


        // Champs optionnels
        $this->initVar('summary', XOBJ_DTYPE_TXTAREA, '', false);
        $this->initVar('content', XOBJ_DTYPE_TXTAREA, '', false);
        $this->initVar('category_id', XOBJ_DTYPE_INT, 0, false);


        // Horodatages
        $this->initVar('created', XOBJ_DTYPE_INT, time(), false);
        $this->initVar('updated', XOBJ_DTYPE_INT, time(), false);


        // Indicateurs de statut
        $this->initVar('published', XOBJ_DTYPE_INT, 0, false);
        $this->initVar('views', XOBJ_DTYPE_INT, 0, false);


        // Métadonnées comme tableau
        $this->initVar('meta', XOBJ_DTYPE_ARRAY, [], false);
    }


    /**
     * Obtenir la date de création formatée
     */
    public function getCreatedDate(string $format = 'Y-m-d H:i:s'): string
    {
        return date($format, $this->getVar('created', 'n'));
    }


    /**
     * Vérifier si l'article est publié
     */
    public function isPublished(): bool
    {
        return $this->getVar('published', 'n') == 1;
    }


    /**
     * Incrémenter le compteur d'affichages
     */
    public function incrementViews(): void
    {
        $views = $this->getVar('views', 'n');
        $this->setVar('views', $views + 1);
    }


    /**
     * Validation personnalisée
     */
    public function validate(): bool
    {
        $this->errors = [];


        // Validation du titre
        $title = trim($this->getVar('title', 'n'));
        if (empty($title)) {
            $this->setErrors('Le titre est obligatoire');
        } elseif (strlen($title) < 5) {
            $this->setErrors('Le titre doit avoir au moins 5 caractères');
        }


        // Validation de l'auteur
        if ($this->getVar('author_id', 'n') <= 0) {
            $this->setErrors('L\'auteur est obligatoire');
        }


        return empty($this->errors);
    }
}


// Utilisation
$article = new Article();
$article->setVar('title', 'My First Article');
$article->setVar('author_id', 1);
$article->setVar('content', '<p>Contenu de l\'article ici...</p>', true);
$article->setVar('meta', [
    'keywords' => ['xoops', 'cms', 'php'],
    'description' => 'Un exemple d\'article'
]);


if ($article->validate() && $article->cleanVars()) {
    // Enregistrer dans la base de données via gestionnaire
    $handler = xoops_getModuleHandler('article', 'mymodule');
    $handler->insert($article);


    echo "Article enregistré avec ID : " . $article->getVar('article_id');
} else {
    echo "Erreurs : " . $article->getHtmlErrors();
}

Meilleures pratiques

Section intitulée « Meilleures pratiques »

  1. Toujours initialiser les variables : Définir toutes les variables dans le constructeur avec initVar()

  2. Utiliser les types de données appropriés : Choisir la constante XOBJ_DTYPE_* correcte pour la validation

  3. Gérer les entrées utilisateur avec soin : Utiliser setVar() avec $notGpc = false pour les saisies utilisateur

  4. Valider avant enregistrement : Toujours appeler cleanVars() avant les opérations base de données

  5. Utiliser les paramètres de format : Utiliser le format approprié dans getVar() pour le contexte

  6. Étendre pour la logique personnalisée : Ajouter des méthodes spécifiques au domaine dans les sous-classes

Documentation connexe

Section intitulée « Documentation connexe »
  • XoopsObjectHandler - Modèle gestionnaire pour la persistance des objets
  • ../Database/Criteria - Construction de requêtes avec Criteria
  • ../Database/XoopsDatabase - Opérations base de données

Voir aussi : Code source XOOPS