Merge tag '1.1.0' into 1.2.0

1.1.0

docs/Documentation/Getting-a-File-Path-and-URL.md

@@ -0,0 +1,48 @@
+# Getting a file path and URL
+
+The path and filename of a stored file in the storage backend that was used to store the file is generated by a [path builder](Path-Builders.md). The event listener that stored your file has used a path builder to generate the path based on the entity data. This means that if you have the entity and instantiate a path builder you can build the path to it in any place.
+
+The plugin already provides you with several convenience short cuts to do that.
+
+Be aware that whenever you use a path builder somewhere, you **must** use the same path builder and options as when the entity was created. They're usually the same as configured in your event listener.
+
+## Getting it from an entity
+
+While you can do this technically it is **not** the *recommended* way of doing it depending on your overall implementation.
+
+TBD
+
+## Getting it using the storage helper
+
+The storage helper is basically just a proxy to a path builder. The helper takes two configuration options:
+
+ * **pathBuilder**: Name of the path builder to use.
+ * **pathBuilderOptions**: The options passed to the path builders constructor.
+
+Make sure that the options you pass and the path builder are the same you've used when you uploaded the file! Otherwise you end up with a different path!
+
+```php
+// Load the helper
+$this->loadHelper('Burzum/FileStorage.Storage', [
+	'pathBuilder' => 'Base',
+	//The builder options must match the options and builder class that were used to store the file.
+	'pathBuilderOptions' => [
+		'modelFolder' => true,
+	]
+]);
+
+// Use it in your views
+$url = $this->Storage->url($yourEntity);
+
+// Change the path builder at run time
+// Be carefully, this will change the path builder instance in the helper!
+$this->Storage->pathBuilder('SomePathBuilder', ['options' => 'here']);
+```
+
+## Getting image versions using the image helper
+
+TBD
+
+## Getting it via events
+
+TBD

docs/Documentation/Path-Builders.md

@@ -1,27 +1,84 @@
-Path Builders
-=============
+# Path Builders
 
 Path builders are classes that are used to build the storage paths for a file based on the information coming from the `file_storage` table.
 
 A path builder *should but doesn't have to* build a unique path per entity based on all the data available in the entity.
 
 They implement at least these methods:
 
- * filename
- * path
- * fullPath
- * url
- 
+ * **filename**: filename
+ * **path**: relative path
+ * **fullPath**: absolute path
+ * **url**: URL to the file
+
 Each of them will take a `FileStorage` entity as first argument. Based on that entity it will generate a path depending on the logic implemented in the path builder.
 
-The reason for this is to separate or share, just as needed, the path building logic between different storage systems. For example S3 differs in it's first part of the path, it's using a bucket while locally you usually have something like a base path instead of the bucket. 
+The reason for this is to separate or share, just as needed, the path building logic between different storage systems. For example S3 differs in it's first part of the path, it's using a bucket while locally you usually have something like a base path instead of the bucket.
 
 If you want to change the way your files are saved extend the `BasePathBuilder` class.
 
-BasePathBuilder
----------------
+## Using path builders
+
+The path builders constructors take a single argument, an array. Every path builder *should* extend `BasePathBuilder` and provide at least some of the config options of it as well.
+
+```php
+$pathBuilder = new BasePathBuilder([
+	'prefix' => 'some-prefix-for-the-path'
+]);
+$pathToEntity = $pathBuilder->path($entity);
+```
+
+## The PathBuilderTrait
+
+The trait allows you to add two methods to any class:
+
+ * `PathBuilderTrait::createPathBuilder()` will return a new instance of a path builder.
+ * `PathBuilderTrait::pathBuilder()` will get/set a path builder from the `PathBuilder::$_pathBuilder` property.
+
+If you want to configure a default path builder just add it's name to your config if your object is using the `InstanceConfigTrait` for example:
+
+
+```php
+protected $_defaultConfig = [
+	'pathBuilder' => 'Base',
+	'pathBuilderOptions' => [
+		'modelFolder' => true
+	]
+];
+
+public function __construct(View $view, array $config = []) {
+	parent::__construct($view, $config);
+
+	$this->pathBuilder(
+		$this->config('pathBuilder'),
+		$this->config('pathBuilderOptions')
+	);
+}
+```
+
+Or set your own configuration options up:
+
+```php
+public function __construct(array $properties = [], array $options = []) {
+	$options += [
+		'pathBuilder' => null,
+		'pathBuilderOptions' => []
+	];
+	parent::__construct($properties, $options);
+	if (is_string($options['pathBuilder'])) {
+		$this->pathBuilder(
+			$options['pathBuilder'],
+			$options['pathBuilderOptions']
+		);
+	}
+}
+```
+
+## Path builders included in the plugin
+
+### BasePathBuilder
 
-This is the path builder all other BP's should inherit from. But if you like to write your very own BP you're free to implement it from the ground up but you'll have to use the PathBuilderInterface.
+This is the path builder all other BP's *should* inherit from. But if you like to write your very own BP you're free to implement it from the ground up but you'll have to use the PathBuilderInterface.
 
 The BasePathBuilder comes with a set of configuration options:
 
@@ -37,4 +94,4 @@ The BasePathBuilder comes with a set of configuration options:
 	'uuidFolder' => true,
 	'randomPath' => 'sha1'
 ]
-```
+```

docs/Documentation/Specific-Adapter-Configurations.md

@@ -13,7 +13,7 @@ Local Filesystem
 By default the StorageManager already comes with a pre-configured adapter instance for the local file system adapter.
 
 The first array element of the `adapterOptions` config key is `TMP` because the tmp folder and the logs folder should be the only writeable place in a *proper* configured application. The reason for that is simply to make it work out of the box without issues. **You definitely want to change that path for your application.**
- 
+
 ```php
 StorageManager::config('Local', [
 	'adapterOptions' => [TMP, true],
@@ -124,3 +124,23 @@ StorageManager::config('OpenCloudTest', array(
 	'class' => '\Gaufrette\Filesystem')
 );
 ```
+
+Azure
+-----
+
+Attention: This adapter config was provided by a third party. If you encounter any trouble with it please report it and the best submit a working example.
+
+```php
+$connectionString = "DefaultEndpointsProtocol=https;AccountName=;AccountKey=";
+$blobRestProxy = new Gaufrette\Adapter\AzureBlobStorage\BlobProxyFactory($connectionString);
+$blobRestProxy->create();
+
+StorageManager::config('AzureBlobStorage', [
+    'adapterOptions' => [
+        $blobRestProxy,
+        'gatewayfiles'
+    ],
+    'adapterClass' => '\Gaufrette\Adapter\AzureBlobStorage',
+    'class' => '\Gaufrette\Filesystem'
+]);
+```

docs/Documentation/The-Image-Helper.md

@@ -16,13 +16,19 @@ class AppView extends View {
 In your views you can now access all your image versions, which you have declared before in your config through the helper.
 
 ```php
-echo $this->Image->display($product['Image'], 'small');
+echo $this->Image->display($product['image'], 'small');
+```
+
+If you want the original image just call the display() method without a version.
+
+```php
+echo $this->Image->display($product['image']);
 ```
 
 If you want to get only the URL to an image you can call ```imageUrl()```.
 
 ```php
-$imageUrl = $this->Image->imageUrl($product['Image'], 'small');
+$imageUrl = $this->Image->imageUrl($product['image'], 'small');
 echo $this->Html->image($imageUrl);
 ```
 

docs/Home.md

@@ -13,12 +13,18 @@ Documentation
 * [Requirements](Documentation/Requirements.md)
 * [Installation](Documentation/Installation.md)
 * [How it works](Documentation/How-it-works.md)
-* [The Storage Manager](Documentation/The-Storage-Manager.md)
 * [How to Use it](Documentation/How-To-Use.md)
-* [Specific Adapter Configurations](Documentation/Specific-Adapter-Configurations.md)
+* [The Storage Manager](Documentation/The-Storage-Manager.md)
 * [Included Event Listeners](Documentation/Included-Event-Listeners.md)
 * [Legacy Event Listeners](Documentation/Legacy-Event-Listeners.md)
 * [Path Builders](Documentation/Path-Builders.md)
+* [Getting a file path and URL](Documentation/Getting-a-File-Path-and-URL.md)
+* [Adapter Configurations](Documentation/Specific-Adapter-Configurations.md)
+  * [Local Filesystem](Documentation/Specific-Adapter-Configurations.md#local-filesystem)
+  * [Amazon S3](Documentation/Specific-Adapter-Configurations.md#amazons3---awss3-adapter)
+  * [Amazon S3 (Legacy)](Documentation/Specific-Adapter-Configurations.md#amazons3---amazons3-adapter-legacy)
+  * [OpenCloud (Rackspace)](Documentation/Specific-Adapter-Configurations.md#opencloud-rackspace)
+  * [Azure](Documentation/Specific-Adapter-Configurations.md#azure)
 * Image processing
   * [Image Storage and Versioning](Documentation/Image-Storage-And-Versioning.md)
   * [The Image Version Shell](Documentation/The-Image-Version-Shell.md)

src/Event/ImageProcessingListener.php

@@ -210,18 +210,24 @@ public function afterDelete(Event $Event) {
 			try {
 				$Storage = StorageManager::adapter($record['adapter']);
 				if (!$Storage->has($string)) {
+					$Event->stopPropagation();
+					$Event->result = false;
 					return false;
 				}
 				$Storage->delete($string);
 			} catch (\Exception $e) {
 				$this->log($e->getMessage());
+				$Event->stopPropagation();
+				$Event->result = false;
 				return false;
 			}
 			$operations = Configure::read('FileStorage.imageSizes.' . $record['model']);
 			if (!empty($operations)) {
 				$Event->data['operations'] = $operations;
 				$this->_removeVersions($Event);
 			}
+			$Event->stopPropagation();
+			$Event->result = true;
 			return true;
 		}
 	}

src/Event/LocalFileStorageListener.php

@@ -61,8 +61,13 @@ public function afterDelete(Event $event) {
 			$path = $storageConfig['adapterOptions'][0] . $event->data['record']['path'];
 			if (is_dir($path)) {
 				$Folder = new Folder($path);
-				return $Folder->delete();
+				$Folder->delete();
+				$event->stopPropagation();
+				$event->result = true;
+				return true;
 			}
+			$event->stopPropagation();
+			$event->result = false;
 			return false;
 		}
 	}

src/Event/S3StorageListener.php

@@ -53,8 +53,12 @@ public function afterDelete(Event $Event) {
 				$Storage->delete($path['combined']);
 			} catch (\Exception $e) {
 				$this->log($e->getMessage());
+				$Event->stopPropagation();
+				$Event->result = false;
 				return false;
 			}
+			$Event->stopPropagation();
+			$Event->result = true;
 			return true;
 		}
 	}

src/Model/Entity/FileStorage.php

@@ -1,6 +1,7 @@
 <?php
 namespace Burzum\FileStorage\Model\Entity;
 
+use Burzum\FileStorage\Storage\PathBuilder\PathBuilderTrait;
 use Cake\Event\EventDispatcherTrait;
 use Cake\ORM\Entity;
 
@@ -14,6 +15,45 @@
 class FileStorage extends Entity {
 
 	use EventDispatcherTrait;
+	use PathBuilderTrait;
+
+	/**
+	 * Path Builder Class.
+	 *
+	 * This is named $_pathBuilderClass because $_pathBuilder is already used by
+	 * the trait to store the path builder instance.
+	 *
+	 * @param array
+	 */
+	protected $_pathBuilderClass = null;
+
+	/**
+	 * Path Builder options
+	 *
+	 * @param array
+	 */
+	protected $_pathBuilderOptions = [];
+
+	/**
+	 * Constructor
+	 *
+	 * @param array $properties hash of properties to set in this entity
+	 * @param array $options list of options to use when creating this entity
+	 */
+	public function __construct(array $properties = [], array $options = []) {
+		$options += [
+			'pathBuilder' => $this->_pathBuilderClass,
+			'pathBuilderOptions' => $this->_pathBuilderOptions
+		];
+		parent::__construct($properties, $options);
+
+		if (!empty($options['pathBuilder'])) {
+			$this->pathBuilder(
+				$options['pathBuilder'],
+				$options['pathBuilderOptions']
+			);
+		}
+	}
 
 	/**
 	 * Fields that can be mass assigned using newEntity() or patchEntity().