Add Docs ModelTrait + Update ModelTrait

Author: wanforge

README.md

@@ -23,6 +23,14 @@ Amazon S3 or Amazon Simple Storage Service component for Yii2.
     - [Basic Usage](#basic-usage)
     - [Advanced Usage](#advanced-usage)
     - [Custom Commands](#custom-commands)
+  - [Using Traits](#using-traits)
+    - [Model Trait](#model-trait)
+      - [Using Trait Methods](#using-trait-methods)
+      - [Overriding Trait Methods](#overriding-trait-methods)
+        - [getS3Component](#gets3component)
+        - [attributePaths](#attributepaths)
+        - [getPresignedUrlDuration](#getpresignedurlduration)
+        - [isSuccessResponseStatus](#issuccessresponsestatus)
   - [License](#license)
 
 ## Instalation
@@ -318,6 +326,155 @@ class MyPlainCommand implements PlainCommand, HasBucket
 Any command can extend the `ExecutableCommand` class or implement the `Executable` interface that will
 allow to execute this command immediately: `$command->withSomething('some value')->execute();`.
 
+## Using Traits
+
+### Model Trait
+
+Attach the Trait to the Model/ActiveRecord with some media attribute that will be saved in S3:
+
+```php
+/**
+ * @property string|null $file
+ */
+class Model extends \yii\db\ActiveRecord
+{
+    use \diecoding\aws\s3\traits\ModelTrait;
+
+    // ...
+
+    public function rules()
+    {
+        return [
+            ['image', 'string'], // Stores the filename
+        ];
+    }
+
+    /**
+     * @inheritdoc 
+     * @see https://github.com/sugeng-sulistiyawan/yii2-aws-s3/blob/main/src/traits/ModelTrait.php#L162
+     */
+    protected function attributePaths()
+    {
+        return [
+            'image' => 'images/'
+        ];
+    }
+
+    // ...
+}
+```
+
+Override the `attributePaths()` method to change the base path where the files will be saved on AWS S3.
+
+* You can map a different path to each file attribute of your Model/ActiveRecord.
+
+#### Using Trait Methods
+
+```php
+$image = \yii\web\UploadedFile::getInstance($model, 'image');
+
+// Save image as image_thumb.png on S3 at //my_bucket/images/ path
+// $model->image will hold "image_thumb.png" after this call finish with success
+$model->saveUploadedFile($image, 'image', 'image_thumb.png');
+
+// Save image_thumb.* to S3 on //my_bucket/images/ path
+// The extension of the file will be determined by the submitted file type
+// This allows multiple file types upload (png,jpg,gif,...)
+$model->saveUploadedFile($image, 'image', 'image_thumb', true);
+
+// Get the URL to the image on S3
+$model->getFileUrl('image');
+
+// Get the presigned URL to the image on S3
+// The default duration is "+30 minutes"
+$model->getFilePresignedUrl('image');
+
+// Remove the file with named saved on the image attribute
+// Continuing the example, here "//my_bucket/images/my_image.png" will be deleted from S3
+$model->removeFile('image');
+```
+
+#### Overriding Trait Methods
+
+##### getS3Component
+
+The S3MediaTrait depends on this component to be configured. The default configuration is to use this component on index `'s3'`, but you may use another value. For this cases, override the `getS3Component()` method:
+
+```php
+public function getS3Component()
+{
+    return Yii::$app->get('my_s3_component');
+}
+```
+
+##### attributePaths
+
+The main method to override is `attributePaths()`, which defines a path in S3 for each attribute of yout model. Allowing you to save each attribute in a different S3 folder.
+
+Here an example:
+
+```php
+protected function attributePaths()
+{
+    return [
+        'logo' => 'logos/',
+        'badge' => 'images/badges/'
+    ];
+}
+
+// or use another attribute, example: id
+// ! Note: id must contain a value first if you don't want it to be empty
+
+protected function attributePaths()
+{
+    return [
+        'logo' => 'thumbnail/' . $this->id . '/logos/',
+        'badge' => 'thumbnail/' . $this->id . '/images/badges/'
+    ];
+}
+```
+
+##### getPresignedUrlDuration
+
+The default pressigned URL duration is set to "+1day", override this method and use your own expiration.
+
+```php
+protected function getPresignedUrlDuration($attribute)
+{
+    return '+2 hours';
+}
+
+// or if you want to set the attribute differently
+
+protected function getPresignedUrlDuration($attribute)
+{
+    switch ($attribute) {
+        case 'badge':
+            return '+2 hours';
+            break;
+        
+        default:
+            return '+1 days';
+            break;
+    }
+}
+
+```
+
+The value should be a valid PHP datetime operation. Read [PHP documentation](https://www.php.net/manual/en/datetime.formats.php) for details
+
+##### isSuccessResponseStatus
+
+The `isSuccessResponseStatus()` method validate the AWS response for status codes is 2**. If needed, you can override this validation:
+
+```php
+protected function isSuccessResponseStatus($response)
+{
+    // Response is always valid
+    return true;
+}
+```
+
 ## License
 
 Yii2 AWS S3 is licensed under the MIT License.

src/traits/ModelTrait.php

@@ -27,11 +27,11 @@ public function getS3Component()
      * @param UploadedFile $file Uploaded file to save
      * @param string $attribute Attribute name where the uploaded filename name will be saved
      * @param string $fileName Name which file will be saved. If empty will use the name from $file
-     * @param bool $updateExtension `true` to automatically append the extension to the file name. Default is `true`
+     * @param bool $autoExtension `true` to automatically append or replace the extension to the file name. Default is `true`
      * 
      * @return string|false Uploaded full path of filename on success or `false` in failure.
      */
-    public function saveUploadedFile(UploadedFile $file, $attribute, $fileName = '', $updateExtension = true)
+    public function saveUploadedFile(UploadedFile $file, $attribute, $fileName = '', $autoExtension = true)
     {
         if ($this->hasError && !$file instanceof UploadedFile) {
             return false;
@@ -40,8 +40,9 @@ public function saveUploadedFile(UploadedFile $file, $attribute, $fileName = '',
         if (empty($fileName)) {
             $fileName = $file->name;
         }
-        if ($updateExtension) {
-            $fileName .= '.' . $file->extension;
+        if ($autoExtension) {
+            $_file = pathinfo($fileName, PATHINFO_FILENAME);
+            $fileName = $_file . '.' . $file->extension;
         }
 
         $filePath = $this->getAttributePath($attribute) . $fileName;
@@ -127,16 +128,18 @@ public function getFilePresignedUrl($attribute)
 
         return $this->getS3Component()->getPresignedUrl(
             $this->getAttributePath($attribute) . $this->{$attribute},
-            $this->getPresignedUrlDuration()
+            $this->getPresignedUrlDuration($attribute)
         );
     }
 
     /**
      * Retrieves the URL signature expiration.
      * 
+     * @param string $attribute Attribute name which holds the duration
+     * 
      * @return mixed URL expiration
      */
-    protected function getPresignedUrlDuration()
+    protected function getPresignedUrlDuration($attribute)
     {
         return '+30 minutes';
     }