# La classe MongoGridFS

(PECL mongo >=0.9.0)

## Introduction

Utilitaires de stockage et lecture de fichiers dans la base de données

GridFS est une spécification de stockage que tous les pilotes implémentent. Simplement, il définit deux collections: files, pour les métadonnées du fichier, et chunks pour le contenu du fichier. Si le fichier est volumineux, il sera automatiquement scindé en sous-parties et chacune sera sauvée comme document dans la collection 'chunks' représentant le contenu du fichier.

Chaque document dans la collection 'files' est caractérisé par un nom, une date d'envoi et un hash md5. Il contient aussi un champ unique _id, qui peut être utilisé pour requêter la collection 'chunks' et obtenir le contenu du fichier. Chaque document dans la collection 'chunks' contient des données binaires, un champ files_id qui correspond au _id du fichier, et la position de ce document dans le fichier.

Par exemple, la collection 'files' ressemble à:

`<?php
array("_id" => 123456789, "filename" => "foo.txt", "chunkSize" => 3, "length" => 12);
?>`
et la collection 'chunks' à:
`<?php
array("files_id" => 123456789, "n" => 0, "data" => new MongoBinData("abc"));
array("files_id" => 123456789, "n" => 1, "data" => new MongoBinData("def"));
array("files_id" => 123456789, "n" => 2, "data" => new MongoBinData("ghi"));
array("files_id" => 123456789, "n" => 3, "data" => new MongoBinData("jkl"));
?>`
Bien sur la taille par défaut des segments est de plusieurs milliers d'octets, non représentatif pour notre exemple.

## Compatibilité entre les différentes langages

Vous devriez être capable d'utiliser n'importe quel fichier créé par MongoGridFS avec n'importe quel driver et vis versa. Cependant, quelques drivers s'attendent à ce que toutes les méta-données associées avec un fichier soivent dans un champ "metadata". Si vous souhaitez utiliser un autre langage, ce peut être une bonne idée de placer les informations souhaitées dans un champ "metadata". Par exemple, au lieu de :

`<?php
$grid->storeFile("somefile.txt", array("date" => new MongoDate()));
?>`

utilisez quelque chose comme :

`<?php
$grid->storeFile("somefile.txt", array("metadata" => array("date" => new MongoDate())));
?>`

## La famille MongoGridFS

MongoGridFS représente les collections 'files' et 'chunks'. MongoGridFS étend MongoCollection, et une instance de MongoGridFS a accès à toutes les méthodes de MongoCollection, qui agissent sur la collection 'files':

`<?php
$grid = $db->getGridFS();
$grid->update(array("filename" => "foo"), $newObj); // update on the files collection
?>`

Un autre exemple de manipulation des méta-données:

`<?php
// Sauvegarde un fichier
$id = $grid->storeFile("game.tgz");
$game = $grid->findOne();
// Ajoute un compteur de téléchargement
$game->file['downloads'] = 0;
$grid->save($game->file);
// Incrémente le compteur
$grid->update(array("_id" => $id), array('$inc' => array("downloads" => 1)));
?>`

Vous pouvez aussi accéder aux objets dans la collection 'chunks' depuis une instance de MongoGridFS:

`<?php
$chunks = $grid->chunks; // $chunks est une MongoCollection
$chunks->insert(array("x" => 4));
?>`

Il existe des méthodes dans MongoGridFS qui ont le même no que dans MongoCollection mais elles se comportent différement. Par exemple, MongoGridFS::remove() suppriment les objets qui correspondent au critère depuis la collection des fichiers ('files'), ainsi que leur contenu depuis la collection des données ('chunks').

Pour stocker un nouvel enregistrement dans GridFS, il y a plusieurs options. Si vous possédez un nom de fichier, agissez comme cela:

`<?php
$grid->storeFile($filename, array("whatever" => "metadata", "you" => "want"));
?>`

Si vous avez une chaine d'octets qui n'est pas un fichier, vous pouvez la stocker grâce à MongoGridFS::storeBytes():

`<?php
$grid->storeBytes($bytes, array("whatever" => "metadata", "you" => "want"));
?>`

Requêter une collection MongoGridFS retourne un MongoGridFSCursor, qui se comporte comme un MongoCursor normal sauf qu'il retourne des MongoGridFSFiles plutôt que des tableaux associatifs.

MongoGridFSFiles peut être écrit sur le disque en utilisant MongoGridFSFile::write() ou récupéré de la mémoire avec MongoGridFSFile::getBytes(). Il n'y a pas de méthode actuellement qui guide les données d'un à l'autre, mais ce n'est pas très difficile à écrire en utilisant $grid->chunks de la collection.

Les objets MongoGridFSFile contiennent un champ file qui contient les méta-données du fichier.

## Synopsis de la classe

étend MongoCollection {
/* Fields */
public MongoCollection $chunks = `NULL` ;
protected string $filesName = `NULL` ;
protected string $chunksName = `NULL` ;
/* Méthodes */
public __construct ( MongoDB `$db` [, string `$prefix` = "fs" [, mixed `$chunks` = "fs" ]] )
public delete ( mixed `$id` ) : bool|array
public drop ( void ) : array
public find ([ array `$query` = array() [, array `$fields` = array() ]] ) : MongoGridFSCursor
public findOne ([ mixed `$query` = array() [, mixed `$fields` = array() ]] ) : MongoGridFSFile
public get ( mixed `$id` ) : MongoGridFSFile
public put ( string `$filename` [, array `$metadata` = array() [, array `$options` = array() ]] ) : mixed
public remove ([ array `$criteria` = array() [, array `$options` = array() ]] ) : bool|array
public storeBytes ( string `$bytes` [, array `$metadata` = array() [, array `$options` = array() ]] ) : mixed
public storeFile ( string|resource `$filename` [, array `$metadata` = array() [, array `$options` = array() ]] ) : mixed
public storeUpload ( string `$name` [, array `$metadata` ] ) : mixed
}

## Voir aussi

- Documentation coeur de MongoDB sur » GridFS
- Article sur les solutions LightCube sur » la sauvegarde des téléchargements utilisateurs
- Article sur les solutions LightCube sur » l'ajout de méta-données aux fichiers

## Sommaire

- MongoGridFS::__construct — Crée une nouvelle collection de fichiers
- MongoGridFS::delete — Efface un fichier et ces morceaux depuis la base de données
- MongoGridFS::drop — Efface les collections de fichiers
- MongoGridFS::find — Interroge un fichier
- MongoGridFS::findOne — Lit un fichier unique satisfaisant les critères
- MongoGridFS::get — Récupère un fichier depuis la base de données
- MongoGridFS::put — Stocke un fichier dans la base de données
- MongoGridFS::remove — Efface des fichiers et leurs morceaux de la base de données
- MongoGridFS::storeBytes — Stocke une chaîne d'octets dans la base de données
- MongoGridFS::storeFile — Stocke un fichier dans la base de données
- MongoGridFS::storeUpload — Stocke un fichier téléchargé dans la base de données