add documentation and only load example endpoints when debug is set t…

…o true
CakeDC · Apr 8, 2024 · 2153c0f · 2153c0f
1 parent 7917862
commit 2153c0f
Show file tree

Hide file tree

Showing 6 changed files with 200 additions and 107 deletions.
diff --git a/Docs/Documentation/CakePHP-Docker.md b/Docs/Documentation/CakePHP-Docker.md
@@ -0,0 +1,52 @@
+## CakePHP
+
+CakePHP installation and configuration example using Docker
+
+```
+$> composer create-project --prefer-dist cakephp/app:~5 uppy_app
+$> cd uppy_app
+$> cp config/app_local.example.php config/app_local.php
+```
+
+## Docker
+
+create docker-compose.yml file as
+```
+version: '3'
+services:
+  psql13:
+    image: postgres:13
+    container_name: uppy-app-postgres13
+    volumes:
+      - ./tmp/data/inertia-postgres13__db:/var/lib/postgresql:delegated
+    environment:
+      - POSTGRES_USER=my_app
+      - POSTGRES_PASSWORD=secret
+      - POSTGRES_DB=my_app
+      - PGUSER=my_app
+      - PGDATABASE=my_app
+      - PGPASSWORD=secret
+    ports:
+      - '7432:5432'
+
+  cakephp:
+    image: webdevops/php-nginx:8.1
+    container_name: uppy-app-cakephp
+    working_dir: /application
+    volumes:
+      - ./:/application:cached
+      - ~/.ssh:/home/application/.ssh:ro
+    environment:
+      - WEB_DOCUMENT_ROOT=/application/webroot
+      - DATABASE_URL=postgres://my_app:secret@uppy-app-postgres13:5432/my_app
+    ports:
+      - "9099:80"
+```
+
+launch container
+
+```
+$> docker-compose up -d
+```
+
+go to http://localhost:9099/
diff --git a/Docs/Documentation/Configure.md b/Docs/Documentation/Configure.md
@@ -0,0 +1,93 @@
+## Configure
+
+To configure the plugin first copy the base configuration to your project
+
+```
+$> cp vendor/cakedc/cakephp-uppy/config/uppy.php config/uppy.php
+```
+
+Then run migration to create table *uppy_files* where save data for files uploaded
+
+```
+$> bin/cake migrations migrate -p CakeDC/Uppy
+```
+
+Note: you can change the name of this table in the configuration file *config/uppy.php*
+
+## Configuration file *config/uppy.php*
+
+By default, when debug is set to true the plugin will add a number of routes to your application `/uppy/files` in order to
+upload and view the uploaded files. You should protect these endpoints in case your application requires
+authentication to upload or manage files. Failing to do so would allow an authenticated user to *upload* files
+to your application.
+
+### Default uppy config file:
+
+```php
+<?php
+
+return [
+    'Uppy' => [
+        'Props' => [
+            'usersModel' => 'Users',
+            'deleteFileS3' => true,
+            'tableFiles' => 'uppy_files',
+        ],
+        'AcceptedContentTypes' => [
+            'application/pdf',
+            'image/png',
+        ],
+        'AcceptedExtensions' => [
+            'pdf',
+            'png',
+        ],
+        /*
+        * S3 configuration to manage files
+        */
+        'S3' => [
+            'contants' => [
+                'lifeTimeGetObject' => '+20 minutes',
+                'lifeTimePutObject' => '+5 minutes',
+            ],
+            'config' => [
+                'version' => 'latest',
+                'region' => filter_var(env('S3_REGION', null)),
+                'endpoint' => filter_var(env('S3_END_POINT', null)),
+                'credentials' => [
+                    'key' => filter_var(env('S3_KEY', null)),
+                    'secret' => filter_var(env('S3_SECRET', null)),
+                ],
+            ],
+            'bucket' => filter_var(env('S3_BUCKET')),
+        ],
+    ],
+];
+```
+
+- usersModel = is the alias name used in you app
+- deleteFileS3 = if the record of the file in the database is deleted and it's marked true, the deletion is launched in the S3 deposit
+- tableFiles = name of table used to store file data, default is `uppy_files`
+- AcceptedContentTypes = list of content-type stored in S3 and saved in database
+- AcceptedExtensions = list of file extensions stored in S3 and saved in database
+- lifeTimeGetObject = life time generated link to access file in S3
+- lifeTimePutObject = life time generated link to post file in S3
+- region = configured region S3
+- endpoint = endpoint server to PUT/POST/GET S3 files
+- key = S3 account key
+- secret = S3 account secret
+- bucket = bucket name
+
+Enpoints
+-------
+
+- /uppy/files/sign = sign with credentials and return signed url to upload file in S3 directly in front
+- /uppy/files/save = save register just uploaded in database with correct S3 path
+- /uppy/files/delete = delete register in database, if Uppy.Props.deleteFileS3 is true remove from S3
+- /uppy/files/view = sign with credentials and return signed url to access file in S3 directly in front
+
+Sample
+-------
+
+- /uppy/files = list of files in database and link to view/delete in S3
+- /uppy/files/add = example uppy upload file to configured S3 and save data relationed in database
+- /uppy/files/drag = example uppy drag and upload multiple file, using Dashboard to configured S3 and save data relationed in database
diff --git a/Docs/Documentation/Installation.md b/Docs/Documentation/Installation.md
@@ -0,0 +1,21 @@
+## Installation
+
+Install plugin via command line:
+
+```
+$> composer require cakedc/cakephp-uppy
+```
+
+## Configuration
+
+Once installed enable it in *src/Application.php*, adding at the bottom of bootstrap function:
+
+```
+$this->addPlugin('CakeDC/Uppy');
+```
+
+or type in command line
+
+```
+$> bin/cake plugin load CakeDC/Uppy
+```
diff --git a/Docs/Home.md b/Docs/Home.md
@@ -0,0 +1,14 @@
+Home
+====
+The **Uppy** Plugin integrate https://github.com/transloadit/uppy to upload files directly to a configured S3 usign a signature, and in the callback response save data related to files uploaded in database.
+
+The plugin is thought as a base to extend and use your app specific controllers and views from.
+
+That it works out of the box doesn't mean it is thought to be used exactly like it is but to provide you a kick start.
+
+Documentation
+-------------
+
+* [CakePHP Docker](Documentation/CakePHP-Docker.md) (optional)
+* [Install](Documentation/Installation.md)
+* [Configure as Use](Documentation/Configure.md)
diff --git a/README.md b/README.md
@@ -1,116 +1,26 @@
 CakeDC Uppy Plugin
 ======================
 
-You can install this plugin into your CakePHP application using [composer](https://getcomposer.org).
+The **Uppy** plugin covers the following features:
+
+* Upload directly files to configured S3 from frontside using a signature
+* Save on configured table path to uploaded files on S3, mime_type, date, metadata and relation to user and specified related model in database indicated
 
 Requirements
 ------------
 
 * CakePHP 5.0+
 * PHP 8.1+
 
+Documentation
+-------------
 
-Setup
------
-
-The recommended way to install composer packages is:
-
-`composer require cakedc/cakephp-uppy`
-
-Then, ensure the plugin is added to your application, in `config/plugins.php` add
-
-```php
-'CakeDC/Uppy'
-```
-
-Important: By default, the plugin will add a number of routes to your application `/uppy/files` in order to
-upload and view the uploaded files. You should protect these endpoints in case your application requires
-authentication to upload or manage files. Failing to do so would allow an authenticated user to *upload* files
-to your application.
-
-This plugin uses `uppy_files` as a table to store filedata as filename, filesize, path in S3, ...
-
-Run the Plugin migrations to create a table to hold the uploaded files details
-
-`bin/cake migrations migrate -p CakeDC/Uppy`
-
-Then copy the file `vendor/cakedc/cakephp-uppy/config/uppy.php` into `config/uppy.php`. Tweak this file to
-provide the required configuration for your S3 compatible connection.
-
-```php
-<?php
-
-return [
-    'Uppy' => [
-        'Props' => [
-            'usersModel' => 'Users',
-            'deleteFileS3' => true,
-            'tableFiles' => 'uppy_files',
-        ],
-        'AcceptedContentTypes' => [
-            'application/pdf',
-            'image/png',
-        ],
-        'AcceptedExtensions' => [
-            'pdf',
-            'png',
-        ],
-        /*
-        * S3 configuration to manage files
-        */
-        'S3' => [
-            'contants' => [
-                'lifeTimeGetObject' => '+20 minutes',
-                'lifeTimePutObject' => '+5 minutes',
-            ],
-            'config' => [
-                'version' => 'latest',
-                'region' => filter_var(env('S3_REGION', null)),
-                'endpoint' => filter_var(env('S3_END_POINT', null)),
-                'credentials' => [
-                    'key' => filter_var(env('S3_KEY', null)),
-                    'secret' => filter_var(env('S3_SECRET', null)),
-                ],
-            ],
-            'bucket' => filter_var(env('S3_BUCKET')),
-        ],
-    ],
-];
-```
-
-- usersModel = is the alias name used in you app
-- deleteFileS3 = if the record of the file in the database is deleted and it's marked true, the deletion is launched in the S3 deposit
-- tableFiles = name of table used to store file data, default is `uppy_files`
-- AcceptedContentTypes = list of content-type stored in S3 and saved in database
-- AcceptedExtensions = list of file extensions stored in S3 and saved in database
-- lifeTimeGetObject = life time generated link to access file in S3
-- lifeTimePutObject = life time generated link to post file in S3
-- region = configured region S3
-- endpoint = endpoint server to PUT/POST/GET S3 files
-- key = S3 account key
-- secret = S3 account secret
-- bucket = bucket name
-
-Enpoints
--------
-
-- /uppy/files/sign = sign with credentials and return signed url to upload file in S3 directly in front
-- /uppy/files/save = save register just uploaded in database with correct S3 path
-- /uppy/files/delete = delete register in database, if Uppy.Props.deleteFileS3 is true remove from S3
-- /uppy/files/view = sign with credentials and return signed url to access file in S3 directly in front
-
-Sample
--------
-
-- /uppy/files = list of files in database and link to view/delete in S3
-- /uppy/files/add = example uppy upload file to configured S3 and save data relationed in database
-- /uppy/files/drag = example uppy drag and upload multiple file, using Dashboard to configured S3 and save data relationed in database
-
+For documentation, as well as tutorials, see the [Docs](Docs/Home.md) directory of this repository.
 
 Support
 -------
 
-For bugs and feature requests, please use the [issues](https://github.com/cakedc/categories/issues) section of this repository.
+For bugs and feature requests, please use the [issues](https://github.com/CakeDC/cakephp-inertia/issues) section of this repository.
 
 Commercial support is also available, [contact us](https://www.cakedc.com/contact) for more information.
 
@@ -122,7 +32,7 @@ This repository follows the [CakeDC Plugin Standard](https://www.cakedc.com/plug
 License
 -------
 
-Copyright 2017-2023 Cake Development Corporation (CakeDC). All rights reserved.
+Copyright 2024 Cake Development Corporation (CakeDC). All rights reserved.
 
 Licensed under the [MIT](http://www.opensource.org/licenses/mit-license.php) License. Redistributions of the source code included in this repository must retain the copyright notice found in each file.
 

diff --git a/config/routes.php b/config/routes.php
@@ -12,14 +12,17 @@
  */
 use Cake\Routing\Route\DashedRoute;
 use Cake\Routing\RouteBuilder;
+use Cake\Core\Configure;
 
 return static function (RouteBuilder $builder): void {
-    $builder->plugin(
-        'CakeDC/Uppy',
-        ['path' => '/uppy'],
-        function (RouteBuilder $routes): void {
-            $routes->setRouteClass(DashedRoute::class);
-            $routes->fallbacks();
-        }
-    );
+    if (Configure::read('debug')) {
+        $builder->plugin(
+            'CakeDC/Uppy',
+            ['path' => '/uppy'],
+            function (RouteBuilder $routes): void {
+                $routes->setRouteClass(DashedRoute::class);
+                $routes->fallbacks();
+            }
+        );
+    }
 };