KnpLabs/Gaufrette — pull request #122 by TomiS (2013-01-09 09:40:46+00:00)
Title: Refactoring, metadata and adapter specific files

Ok, here's a new one. I think I managed to do this with a lot less BCBs, maybe even none.

Here's what I did:

- Added File folder that contains storage specific file objects. Some adapters may not need them so they can use ```File``` class directly but some adapters definitely benefit from customized File object.
- Removed metadata related code from adapters as it's a feature of a file (not BCB because it didn't work before)
- Added ```get``` function into adapters for retrieving the file object, altered logic in ```Filesystem::get()``` to support this.
- Changed the meaning of ```createFile```. Now it's purely a factory method for creating a new file object.
- Added ```writeFile``` function into adapters for writing files
- Added metadata as optional parameter for write function. (I think this really must be here to enable any kind of metadata support for old write function. It does not break BC because it's optional.)
- Moved all interfaces to root folder from Adapter folder. (This is not mandatory, but I really think it's nice to reserve Adapter folder only for adapters, not interfaces)
- Changed ```MetadataSupporter``` to contain method isMetadataKeyAllowed($metaKey);

This is how it can be used now:

```php
//Object-oriented write
$f = $filesystem->createFile($key);
$f->setMetadataItem('metaKey1', 'metaValue1');
$f->setMetadataItem('metaKey2', 'metaValue2');
$f->setContent($fileContentBytes);
$f->setName('myfile.jpg'); //human-readable name
$f = $filesystem->writeFile($f);

//Object-oriented get, returns file object
$g = $filesystem->get($key);

//Procedural write
$filesystem->write($key, $content, [$metadata]);

//Procedural read (does not support metadata)
$filesystem->read($key)

//Delete
$filesystem->delete($key);
```

And finally, as before, I only implemented GridFS and Local as a proof of concept. More work has to be done before merging in any case...