Fixes #14: Added documentation for version 2

README.md

@@ -2,17 +2,30 @@
 
 [![Build Status](https://api.travis-ci.org/sroze/SRIORestUploadBundle.png)](https://travis-ci.org/sroze/SRIORestUploadBundle)
 
-## Version 2
+This bundle provide a simple ways to handle uploads on the server side.
 
-The new major version 2.0.0 introduce a lot of new features such as:
+Currently, it supports the simple, form-data, multipart and resumable ways.
 
-- Using Gaufrette as storage, which allow you to push files on local filesystem, Amazon S3 or any provider...
-- Add a NamingStrategy that allow to have a custom naming convention
-- Add a DirectoryStrategy that allow to vote and create a sub-directory ordering system
-- ...
+## Getting started
 
-The code is in the current `master` branch but **documentation is coming soon...**
+Using [Gaufrette](https://github.com/KnpLabs/Gaufrette) as storage layer, you can handle file uploads and store files on many places such as a local file system, an Amazon S3 bucket, ...
 
-## Legacy
+- [Installation](Resources/doc/installation.md)
+- [Usage](Resources/doc/usage.md)
+- [Advanced usage](Resources/doc/advanced.md)
+- [Upload ways summary](Resources/doc/upload-ways.md)
+- [Configuration reference](Resources/doc/reference.md)
 
-* <a href="http://sroze.github.com/SRIORestUploadBundle/">Read documentation of 1.1.1</a>
+## Testing
+
+Tests are run with [PHPUnit](http://phpunit.de). Once you installed dependencies with composer, then:
+
+- Create a database, allow access to a user, and set configuration in `Tests/Fixtures/App/app/config/parameters.yml` file
+- Create the database schema for the `test` environment
+  ```sh
+  php Tests/Fixtures/App/app/console doctrine:schema:update --force --env=test
+  ```
+- Run PHPUnit
+  ```sh
+  phpunit
+  ```

Resources/doc/advanced.md

@@ -0,0 +1,84 @@
+# Advanced usage
+
+## Strategies
+
+You can set naming and storage strategies for each defined storage.
+```yml
+srio_rest_upload:
+    storages:
+        default:
+            filesystem: gaufrette.default_filesystem
+            naming_strategy: your_naming_strategy_service
+            storage_strategy: your_storage_strategy_service
+```
+
+### Naming strategy
+
+The naming strategy is responsible to set the name that the stored file will have. The [default naming strategy](../../Strategy/DefaultNamingStrategy.php) create a random file name.
+
+To create your own strategy you just have to create a class that implements the `NamingStrategy` interface. Here's an example with a strategy that generate a random file name but with its extension or the default one as fallback.
+
+```php
+namespace Acme\Storage\Strategy;
+
+use SRIO\RestUploadBundle\Upload\UploadContext;
+use SRIO\RestUploadBundle\Strategy\NamingStrategy;
+
+class DefaultNamingStrategy implements NamingStrategy
+{
+    const DEFAULT_EXTENSION = 'png';
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getName(UploadContext $context)
+    {
+        $name = uniqid();
+        $extension = self::DEFAULT_EXTENSION;
+
+        if (($request = $context->getRequest()) !== null) {
+            $files = $request->files->all();
+
+            /** @var $file \Symfony\Component\HttpFoundation\File\UploadedFile */
+            $file = array_pop($files);
+
+            if ($file !== null) {
+                $parts = explode('.', $file->getClientOriginalName());
+                $extension = array_pop($parts);
+            }
+        }
+
+        return $name.'.'.$extension;
+    }
+}
+```
+
+Then, define a service and change the `naming_strategy` of your storage configuration with the created service ID.
+
+### Storage strategy
+
+It defines the (sub)directory in which the file will be created in your filesystem.
+
+The storage strategy is working the same way than the naming strategy: create a service with a class that implements `StorageStrategy` and set the `storage_strategy` configuration of your storage with the created service.
+
+## Create a custom handler
+
+You can easily create your custom upload providers (and feel free to _PR_ them on GitHub) by creating a [tagged service](http://symfony.com/doc/current/components/dependency_injection/tags.html) with the `rest_upload.processor` tag
+
+```yml
+<parameters>
+    <parameter key="acme.my.processor.class">Acme\AcmeBundle\Processor\MyUploadProcessor</parameter>
+</parameters>
+
+<services>
+    <service id="acme.my.processor" class="%acme.my.processor.class%">
+        <argument type="service" id="doctrine.orm.entity_manager" />
+        <tag name="rest_upload.processor" uploadType="acme" />
+    </service>
+</services>
+```
+
+Note the `uploadType` attribute that define the unique name of the upload way, set in the `uploadType` query parameters.
+
+Your `MyUploadProcessor` class should then implements the [`ProcessorInterface`](../../Processor/ProcessorInterface.php) or extends the [`AbstractUploadProcessor`](../../Processor/AbstractUploadProcessor.php)
+

Resources/doc/installation.md

@@ -0,0 +1,63 @@
+# Installation
+
+First, you need to install [KnpGaufretteBundle](https://github.com/KnpLabs/KnpGaufretteBundle), a Symfony integration of Gaufrette which will handle the file storage on places your want.
+
+## Add SRIORestUploadBundle in your dependencies
+
+In your `composer.json` file, add `srio/rest-upload-bundle`:
+```json
+{
+    "require": {
+        "srio/rest-upload-bundle": "~2.0.0"
+    }
+}
+```
+
+Then, update your dependencies:
+```
+composer update srio/rest-upload-bundle
+```
+
+## Enable the bundle in your kernel
+
+```php
+// app/AppKernel.php
+public function registerBundles()
+{
+    $bundles = array(
+        // ...
+        new SRIO\RestUploadBundle\SRIORestUploadBundle(),
+    );
+}
+```
+
+## Create the Gaufrette filesystem
+
+In your configuration file, create your Gaufrette filesystem. Let's start with a local filesystem storage in the `web/uploads` directory.
+
+```yml
+# app/config/config.yml
+
+knp_gaufrette:
+    adapters:
+        local_uploads:
+            local:
+                directory: %kernel.root_dir%/../web/uploads
+    filesystems:
+        uploads:
+            adapter: local_uploads
+```
+
+## Configure the bundle
+
+Then, we just have to configure the bundle to use the Gaufrette storage:
+```
+srio_rest_upload:
+    storages:
+        default:
+            filesystem: gaufrette.uploads_filesystem
+```
+
+If you want to use the resumable upload way, you have to [configure it](upload-ways.md#resumable-configuration).
+
+Then, [start using it](usage.md).

Resources/doc/reference.md

@@ -0,0 +1,32 @@
+# Configuration reference
+
+```yml
+srio_rest_upload:
+    # Define the available storages
+    storages:
+        name:
+            # Filesystem service created by Gaufrette (or your own matching the Gaufrette's interface)
+            filesystem: fs_service_id
+
+            # Naming strategy service
+            naming_strategy: srio_rest_upload.naming.default_strategy
+
+            # Storage strategy service
+            storage_strategy: srio_rest_upload.storage.default_strategy
+
+    # The storage voter, that chose between storage based on upload context
+    storage_voter: srio_rest_upload.storage_voter.default
+
+    # The default storage name. With the default storage voter, it'll use
+    # the first defined storage if value is null
+    default_storage: ~
+
+    # If you want to use the resumable upload way, you must set
+    # the class name of your entity which store the upload sessions.
+    resumable_entity: ~
+
+    # Parameter the define the upload way, internally the provider selector
+    upload_type_parameter: uploadType
+```
+
+The [Advanced usage](advanced.md) section explain the naming and storage strategies.