Merge pull request #6 from MayMeow/add-s3-support

Adding support for S3 storage

Author: 栄茉

.devcontainer/devcontainer.json

@@ -0,0 +1,42 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
+// https://github.com/microsoft/vscode-dev-containers/tree/v0.202.5/containers/docker-existing-docker-compose
+// If you want to run as a non-root user in the container, see .devcontainer/docker-compose.yml.
+{
+	"name": "Existing Docker Compose (Extend)",
+
+	// Update the 'dockerComposeFile' list if you have more compose files or use different names.
+	// The .devcontainer/docker-compose.yml file contains any overrides you need/want to make.
+	"dockerComposeFile": [
+		"../docker-compose-dev.yml",
+		"docker-compose.yml"
+	],
+
+	// The 'service' property is the name of the service for the container that VS Code should
+	// use. Update this value and .devcontainer/docker-compose.yml to the real service name.
+	"service": "app",
+
+	// The optional 'workspaceFolder' property is the path VS Code should open by default when
+	// connected. This is typically a file mount in .devcontainer/docker-compose.yml
+	"workspaceFolder": "/workspace",
+
+	// Set *default* container specific settings.json values on container create.
+	"settings": {},
+
+	// Add the IDs of extensions you want installed when the container is created.
+	"extensions": []
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Uncomment the next line if you want start specific services in your Docker Compose config.
+	// "runServices": [],
+
+	// Uncomment the next line if you want to keep your containers running after VS Code shuts down.
+	// "shutdownAction": "none",
+
+	// Uncomment the next line to run commands after the container is created - for example installing curl.
+	// "postCreateCommand": "apt-get update && apt-get install -y curl",
+
+	// Uncomment to connect as a non-root user if you've added one. See https://aka.ms/vscode-remote/containers/non-root.
+	// "remoteUser": "vscode"
+}

.devcontainer/docker-compose.yml

@@ -0,0 +1,40 @@
+version: '3'
+services:
+  # Update this to the name of the service you want to work with in your docker-compose.yml file
+  app:
+    # If you want add a non-root user to your Dockerfile, you can use the "remoteUser"
+    # property in devcontainer.json to cause VS Code its sub-processes (terminals, tasks, 
+    # debugging) to execute as the user. Uncomment the next line if you want the entire 
+    # container to run as this user instead. Note that, on Linux, you may need to 
+    # ensure the UID and GID of the container user you create matches your local user. 
+    # See https://aka.ms/vscode-remote/containers/non-root for details.
+    #
+    # user: vscode
+
+    # Uncomment if you want to override the service's Dockerfile to one in the .devcontainer 
+    # folder. Note that the path of the Dockerfile and context is relative to the *primary* 
+    # docker-compose.yml file (the first in the devcontainer.json "dockerComposeFile"
+    # array). The sample below assumes your primary file is in the root of your project.
+    #
+    # build:
+    #   context: .
+    #   dockerfile: .devcontainer/Dockerfile
+
+    init: true
+    
+    volumes:
+      # Update this to wherever you want VS Code to mount the folder of your project
+      - .:/workspace:cached
+
+      # Uncomment the next line to use Docker from inside the container. See https://aka.ms/vscode-remote/samples/docker-from-docker-compose for details.
+      # - /var/run/docker.sock:/var/run/docker.sock 
+
+    # Uncomment the next four lines if you will use a ptrace-based debugger like C++, Go, and Rust.
+    # cap_add:
+    #   - SYS_PTRACE
+    # security_opt:
+    #   - seccomp:unconfined
+
+    # Overrides default command so things don't shut down after the process ends.
+    command: /bin/bash -c "while sleep 1000; do :; done"
+ 

CHANGELOG.md

@@ -0,0 +1,14 @@
+# v 1.1.0
+
+Added support for S3 Compatible storage, Upload and download are now handling StorageManagers.
+
+* ADD Support for S3 Compatible storage
+* ADD new Component for Download files from storage
+* ADD new `storage_type` key into configuration for components
+* ADD AWS SDK to requirements
+* ADD `FileUpload\Exceptions\FileContentException`
+* ADD `LocalStorageManager` and `S3StorageManager` which handling upload and download files from storage
+* ADD New configuration for `S3` client (for more informations check README)
+* ADD `StorageConfigInterface`, `StorageManagerInterface` and `StoredFileInterface`
+* UPDATE Return type for `getFile()` was changed to`\FileUpload\File\StoredFileInterface` from `\Psr\Http\Message\UploadedFileInterface` Which returning more informations about file
+* UPDATE `UploadComponent::getFile()` from now can throw `HttpException` in case there is `Not supported storage type` in configuration

README.md

@@ -1,5 +1,12 @@
 # 🆙 FileUpload plugin for CakePHP
 
+Cakephp plugin to upload files to storage and download them. Currently are supported:
+
+- Local storage
+- S3 Compatible storage
+
+And supported actions are upload and download.
+
 ## Installation
 
 You can install this plugin into your CakePHP application using [composer](https://getcomposer.org).
@@ -12,20 +19,6 @@ The recommended way to install composer packages is:
 composer require maymeow/file-upload
 ```
 
-## 🛡 From my server
-
-Add to `composer.json` following repository
-
-```json
-{"type":"composer","url":"https://git.cloud.hsoww.net/api/v4/group/121/-/packages/composer/packages.json"}
-```
-
-then run
-
-```
-composer require maymeow/file-upload
-```
-
 ## Usage
 
 To load plugin addd to `Application.php`
@@ -41,10 +34,17 @@ public function initialize(): void
 {
     parent::initialize();
     $this->loadComponent('FileUpload.Upload');
+    $this->loadComponent('FileUpload.Dowmload'); // in case you wan to download files
 }
 ```
 
-Or you can change them
+## Using local storage
+
+Commands above are loaded with default configuration:
+- Using Local filesystem: type is set to `local`
+- Data are stored in `sotrage` folder in root of your application - This folder is not public and cannot be served directly from webserver. You need to use `DownloadComponent` to get files
+- Field name for uploading files is `uploaded_file`
+- Allowed are all file types
 
 ```php
 public function initialize(): void
@@ -60,40 +60,95 @@ public function initialize(): void
 
 For `allowedFileTypes` use `'allowedFileTypes' => '*'` for all file types or `'allowedFileTypes' => ['type1', 'type2']` for your expected file types. If file have not allowed type Component will throw `Cake\Http\Exception\HttpException`.
 
-Usage in function
+Using local storage (default option) you can use default config but do not forge to change allowed file types and form field nam from which you uploading file to server.
+
+## Using S3 storage
+
+For S3 storage configuration is pretty same as configuration above, but you have to change type to `s3` instead of `local` which is default as follows
+
+```php
+public function initialize(): void
+{
+    parent::initialize();
+    $this->loadComponent('FileUpload.Upload', [
+        'fieldName' => 'your_form_file_field',
+        'storagePath' => 'bucket_name',
+        'storage_type' => 's3'
+    ]);
+}
+```
+
+:exclamation: Dont forget to change configuration for `DownloadComponent` too if you planing using it.
+
+Next add configuration for s3 server to your config file `app_local.php` for example as follows:
 
 ```php
-public function add()
+'S3' => [
+    'version' => 'latest',
+    'region'  => 'us-east-1',
+    'endpoint' => 'http://cake_minio:9000',
+    'use_path_style_endpoint' => true,
+    'credentials' => [
+        'key'    => 'minioadmin',
+        'secret' => 'minioadmin',
+    ],
+]
+```
+
+Config above is for using minio with my [CakePHP starte kit](https://github.com/MayMeow/cakephp-starter-kit). Change it for your needs.
+
+
+## Uploading files
+
+
+```php
+/**
+ * @throws \HttpException
+ * @return \Cake\Http\Response|null|void
+ */
+public function upload()
 {
-    $file = $this->Files->newEmptyEntity();
+    $uploadForm = new UploadForm();
 
     if ($this->request->is('post')) {
-        
-        // you can use try catch to show Flash instead of error page
-        try {
-            // Get Uploaded file details
-            $fileObject = $this->Upload->getFile($this->request);   
-
-            $file = $this->Files->patchEntity($file, $this->request->getData());
-
-            // Update Model and write it
-            $file->name = $fileObject->getClientFilename();
-            $file->size = $fileObject->getSize();
-            $file->path = $fileObject->getClientFilename();
-            $file->updated = Date::now();
-
-            if ($this->Files->save($file)) {
-                $this->Flash->success(__('The file has been saved.'));
-
-                return $this->redirect(['action' => 'index']);
-            }
-            $this->Flash->error(__('The file could not be saved. Please, try again.'));
-
-        } catch (HttpException $e) {
-            $this->Flash->error($e->getMessage());
-        }
+        $uploadedFile = $this->Upload->getFile($this->request);
+
+        // Create new Entity and store info about uploaded file
+        $file = $this->Files->newEmptyEntity();
+
+        $file->name = $uploadedFile->getFileName();
+        $file->path = $uploadedFile->getPath();
+
+        $this->Files->save($file);
+
+        return $this->redirect($this->referer());
     }
-    $this->set(compact('file'));
+
+    $this->set(compact('uploadForm'));
+}
+```
+
+## Downloading files
+
+
+```php
+/**
+ * @param string $fileName
+ * @return \Cake\Http\Response|void
+ */
+public function download($fileName)
+{
+    $downloadedFile = $this->Download->getFile($fileName);
+
+    $response = $this->response;
+    $response = $response->withStringBody($downloadedFile->getFileContent());
+    $response = $response->withType($downloadedFile->getFileType());
+
+    if ($this->request->getParam('?.download') == true) {
+        $response = $response->withDownload($fileName);
+    }
+
+    return $response;
 }
 ```
 
@@ -102,9 +157,9 @@ public function add()
 * [x] Configurable field name
 * [x] Configurable path to storage
 * [x] Allowed file types
+* [x] Add S3 Support
 * [ ] Multiple file upload
 * [ ] File Size
-* [ ] Factory with most common file types
 
 💡 If you have more ideas then you can post issue on porect's GitHub page.
 

VERSION

@@ -0,0 +1 @@
+1.0.2

composer.json

@@ -5,6 +5,7 @@
     "license": "MIT",
     "require": {
         "php": ">=7.2",
+        "aws/aws-sdk-php": "^3.199",
         "cakephp/cakephp": "~4.1.0"
     },
     "require-dev": {

docker/devcontainer/Dockerfile

@@ -1,5 +1,7 @@
 FROM ghcr.io/maymeow/php-ci-cd/php-ci-cd:7.4.16-cs-1
 
+# RUN apt update && apt install -y git
+
 # arguments in docker-compose file
 ARG user=vscode
 ARG uid=1000

src/Controller/Component/DownloadComponent.php

@@ -0,0 +1,46 @@
+<?php
+declare(strict_types=1);
+
+namespace FileUpload\Controller\Component;
+
+use Cake\Controller\Component;
+use FileUpload\File\StoredFileInterface;
+use FileUpload\Storage\LocalStorageManager;
+use FileUpload\Storage\S3StorageManager;
+use FileUpload\Storage\StorageConfigInterface;
+
+/**
+ * Download component
+ */
+class DownloadComponent extends Component implements StorageConfigInterface
+{
+    /**
+     * Default configuration.
+     *
+     * @var array
+     */
+    protected $_defaultConfig = [
+        'fieldName' => 'uploaded_file',
+        'storagePath' => ROOT . DS . 'storage' . DS ,
+        'allowedFileTypes' => '*',
+        'storage_type' => 'local',
+    ];
+
+    /**
+     * Returns stored file info and content
+     *
+     * @param string $fileName Name of file without path or slashes
+     * @return \FileUpload\File\StoredFileInterface Stored file object
+     */
+    public function getFile(string $fileName): StoredFileInterface
+    {
+        /** check if storage is s3. Local storage is default one */
+        if ($this->getConfig('storage_type') == 's3') {
+            $sm = new S3StorageManager($this);
+        } else {
+            $sm = new LocalStorageManager($this); // default one
+        }
+
+        return $sm->pull($fileName);
+    }
+}