PHPillow : Manipulez facilement CouchDB avec PHP

PHPillow est un client PHP orienté objet pour CouchDB. Le dernier release supporte les versions de PHP supérieures a 5.2. Le client bénéficie aussi de 96% de test coverage. PHPillow est un client leger qui dispose de contraintes de validation de document, une synchronisation automatique des vues ainsi qu’un versionning automatique de documents.
Dans l’article suivant nous allons voir comment nous pouvons facilement manipuler CouchDB avec PHPillow.

Connection a CouchDB

Pour se connecter, utilisez la classe phpillowConnection. Exemple:

phpillowConnection::createInstance('localhost', 5984, 'user', 'password');

Une fois créée, cette connection va etre utilisée dans vos classes documents et vues automatiquement.

Definir un document personnalisee

Dans cet exemple, nous allons representer un article, qui peut avoir cette definition :

class ArticleDocument extends phpillowDocument
{
    protected static $type = 'article';
    protected $requiredProperties = array(
        'title',
        'abstract',
        'author'
    );

    public function __construct()
    {
        $this->properties = array(
            'title'     => new phpillowStringValidator(),
            'abstract'      => new phpillowTextValidator(),
            'author'      => new phpillowStringValidator(),
        );

        parent::__construct();
    }
    protected function generateId()
    {
        return $this->stringToId( $this->storage->title );
    }
    protected function getType()
    {
        return self::$type;
    }
}

La propriété $type definit le type de document (article dans notre cas). Elle doit être unique dans toute l’application.
Si vous n’êtes pas encore sous PHP 5.3, (qu’attendez vous pour migrer ? ;-)), vous devez implémenter la methode getType() afin de retourner le type de votre document, sinon, le late static binding vous simplifiera la vie, vous pourrez alors implémenter cette methode dans votre classe de base.
Le constructeur associe des validateurs aux propriétés de l’article qui sont déclarées dans la propriété $requiredProperties. PHPillow dispose de plusieurs types de validateurs comme phpillowStringValidator et phpillowTextValidator. Vous comprenez que vous pouvez eventuellement créer des validateurs personnalisées pour votre application par la suite.
Le dernier truc que vous aurez besoin de faire est de générer un identifiant de document. la méthode stringToId() verifiera les requis de CouchDB pour un id de document comme l’unicité.

Utiliser un document

La création du document se fait comme suit :

$doc = new ArticleDocument();
$doc->title = 'Mon premier article';
$doc->abstract  = 'Ceci est mon premier article';
$doc->author  = 'Anis Berejeb';
$doc->save();

La méthode save() rendra disponible la propriété _id :

echo $doc->_id;
> article-mon_premier_article

Pour récupérer un Article :

$doc = new ArticleDocument();
$doc->fetchById( 'article-mon_premier_article' );

Les propriétés _id et _rev représentent respectivement l’identitfiant et la version courante de l’article. L’ensemble des versions est aussi disponible dans un tableau :

echo $doc->revisions[0]['title'];
> Mon premier article

La propriété $versioned permet d’activer ou de désactiver le versionning d’un document.

Les vues

Dans CouchDB, les vues représentent un moyen d’accéder les documents par leurs propriétés ou par des clés complexes. Vous pouvez créer une vue en étendant la classe phpillowView comme suit :

class ArticleView extends phpillowView
{
    protected $viewDefinitions = array(
        // Indexer les articles par leur titre et afficher leur auteur
        'entries' => 'function( doc )
{
    if ( doc.type == "article" )
    {
        emit( doc.title, doc._id );

        emit( [doc._id, 0], doc._id );

        if ( doc.author )
        {
                emit( [doc._id, 1], doc.author );
        }
    }
}',
    );

    protected function getViewName()
    {
        return 'vue_auteur';
    }
}

Les définitions de vues sont stockées dans la propriété $viewDefinitions et sont automatiquement écrits dans la base de données. Chaque vue a un nom. Dans la vue, Le code qui effectue l’indexation est écrit en EcmaScript. La fonction emit() de CouchDB prend une clé et du contenu comme paramètres, elle indexe le contenu avec la clé donnée. Normalement, vous ne devez pas stocker des documents complets parce que les vues sont générées. Vous pourrez récupérer le document  via son titre comme suit :

$doc = ArticleView::entries( array( 'key' => 'Mon premier article' ) );

Le gestionnaire

Le gestionnaire phpillowManager est un point central pour manipuler vos documents :

phpillowManager::setDocumentClass( 'article', 'ArticleDocument' );
$doc = phpillowManager::createDocument( 'article' );
// ...

$doc = phpillowManager::fetchDocument(
    'article', 'article-mon_premier_aricle'
);
// ....

Plus d’informations, téléchargement et documentation sur

• Phpillow
• CouchDB