Skip to content

Commit 5e05493

Browse files
author
May Meow
committed
Update readme
1 parent d0b5261 commit 5e05493

File tree

1 file changed

+99
-44
lines changed

1 file changed

+99
-44
lines changed

‎README.md‎

Lines changed: 99 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# 🆙 FileUpload plugin for CakePHP
22

3+
Cakephp plugin to upload files to storage and download them. Currently are supported:
4+
5+
- Local storage
6+
- S3 Compatible storage
7+
8+
And supported actions are upload and download.
9+
310
## Installation
411

512
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:
1219
composer require maymeow/file-upload
1320
```
1421

15-
## 🛡 From my server
16-
17-
Add to `composer.json` following repository
18-
19-
```json
20-
{"type":"composer","url":"https://git.cloud.hsoww.net/api/v4/group/121/-/packages/composer/packages.json"}
21-
```
22-
23-
then run
24-
25-
```
26-
composer require maymeow/file-upload
27-
```
28-
2922
## Usage
3023

3124
To load plugin addd to `Application.php`
@@ -41,10 +34,17 @@ public function initialize(): void
4134
{
4235
parent::initialize();
4336
$this->loadComponent('FileUpload.Upload');
37+
$this->loadComponent('FileUpload.Dowmload'); // in case you wan to download files
4438
}
4539
```
4640

47-
Or you can change them
41+
## Using local storage
42+
43+
Commands above are loaded with default configuration:
44+
- Using Local filesystem: type is set to `local`
45+
- 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
46+
- Field name for uploading files is `uploaded_file`
47+
- Allowed are all file types
4848

4949
```php
5050
public function initialize(): void
@@ -60,40 +60,95 @@ public function initialize(): void
6060

6161
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`.
6262

63-
Usage in function
63+
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.
64+
65+
## Using S3 storage
66+
67+
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
68+
69+
```php
70+
public function initialize(): void
71+
{
72+
parent::initialize();
73+
$this->loadComponent('FileUpload.Upload', [
74+
'fieldName' => 'your_form_file_field',
75+
'storagePath' => 'bucket_name',
76+
'storage_type' => 's3'
77+
]);
78+
}
79+
```
80+
81+
:exclamation: Dont forget to change configuration for `DownloadComponent` too if you planing using it.
82+
83+
Next add configuration for s3 server to your config file `app_local.php` for example as follows:
6484

6585
```php
66-
public function add()
86+
'S3' => [
87+
'version' => 'latest',
88+
'region' => 'us-east-1',
89+
'endpoint' => 'http://cake_minio:9000',
90+
'use_path_style_endpoint' => true,
91+
'credentials' => [
92+
'key' => 'minioadmin',
93+
'secret' => 'minioadmin',
94+
],
95+
]
96+
```
97+
98+
Config above is for using minio with my [CakePHP starte kit](https://github.com/MayMeow/cakephp-starter-kit). Change it for your needs.
99+
100+
101+
## Uploading files
102+
103+
104+
```php
105+
/**
106+
* @throws \HttpException
107+
* @return \Cake\Http\Response|null|void
108+
*/
109+
public function upload()
67110
{
68-
$file = $this->Files->newEmptyEntity();
111+
$uploadForm = new UploadForm();
69112

70113
if ($this->request->is('post')) {
71-
72-
// you can use try catch to show Flash instead of error page
73-
try {
74-
// Get Uploaded file details
75-
$fileObject = $this->Upload->getFile($this->request);
76-
77-
$file = $this->Files->patchEntity($file, $this->request->getData());
78-
79-
// Update Model and write it
80-
$file->name = $fileObject->getClientFilename();
81-
$file->size = $fileObject->getSize();
82-
$file->path = $fileObject->getClientFilename();
83-
$file->updated = Date::now();
84-
85-
if ($this->Files->save($file)) {
86-
$this->Flash->success(__('The file has been saved.'));
87-
88-
return $this->redirect(['action' => 'index']);
89-
}
90-
$this->Flash->error(__('The file could not be saved. Please, try again.'));
91-
92-
} catch (HttpException $e) {
93-
$this->Flash->error($e->getMessage());
94-
}
114+
$uploadedFile = $this->Upload->getFile($this->request);
115+
116+
// Create new Entity and store info about uploaded file
117+
$file = $this->Files->newEmptyEntity();
118+
119+
$file->name = $uploadedFile->getFileName();
120+
$file->path = $uploadedFile->getPath();
121+
122+
$this->Files->save($file);
123+
124+
return $this->redirect($this->referer());
95125
}
96-
$this->set(compact('file'));
126+
127+
$this->set(compact('uploadForm'));
128+
}
129+
```
130+
131+
## Downloading files
132+
133+
134+
```php
135+
/**
136+
* @param string $fileName
137+
* @return \Cake\Http\Response|void
138+
*/
139+
public function download($fileName)
140+
{
141+
$downloadedFile = $this->Download->getFile($fileName);
142+
143+
$response = $this->response;
144+
$response = $response->withStringBody($downloadedFile->getFileContent());
145+
$response = $response->withType($downloadedFile->getFileType());
146+
147+
if ($this->request->getParam('?.download') == true) {
148+
$response = $response->withDownload($fileName);
149+
}
150+
151+
return $response;
97152
}
98153
```
99154

@@ -102,9 +157,9 @@ public function add()
102157
* [x] Configurable field name
103158
* [x] Configurable path to storage
104159
* [x] Allowed file types
160+
* [x] Add S3 Support
105161
* [ ] Multiple file upload
106162
* [ ] File Size
107-
* [ ] Factory with most common file types
108163

109164
💡 If you have more ideas then you can post issue on porect's GitHub page.
110165

0 commit comments

Comments
 (0)