Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/itstructure/yii2-multi-format-uploader
Module for Yii2 Framework to upload some type of files to local or S3 Amazon storage
https://github.com/itstructure/yii2-multi-format-uploader
amazon file internal-albums module s3-amazon-storage upload yii2 yii2-framework yii2-template
Last synced: 3 months ago
JSON representation
Module for Yii2 Framework to upload some type of files to local or S3 Amazon storage
- Host: GitHub
- URL: https://github.com/itstructure/yii2-multi-format-uploader
- Owner: itstructure
- License: mit
- Created: 2018-05-15T05:53:32.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-23T00:00:48.000Z (almost 2 years ago)
- Last Synced: 2024-09-30T23:44:49.455Z (3 months ago)
- Topics: amazon, file, internal-albums, module, s3-amazon-storage, upload, yii2, yii2-framework, yii2-template
- Language: PHP
- Homepage: https://pack-develop.info/en/product/yii2-multi-format-uploader
- Size: 363 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
Yii2 Multi format uploader module - MFUploader
==============
## Introduction
[](https://packagist.org/packages/itstructure/yii2-multi-format-uploader)
[](https://packagist.org/packages/itstructure/yii2-multi-format-uploader)
[](https://packagist.org/packages/itstructure/yii2-multi-format-uploader)
[](https://packagist.org/packages/itstructure/yii2-multi-format-uploader)
[](https://scrutinizer-ci.com/g/itstructure/yii2-multi-format-uploader/build-status/master)
[](https://scrutinizer-ci.com/g/itstructure/yii2-multi-format-uploader/?branch=master)
**MFUploader** -- Module for the Yii2 Framework to upload some type of files to local or S3 Amazon storage.
MFUploader module provides the following options:
- Upload files to local storage.
- Upload files to remote Amazon S3 storage.
- Support file formats: **image**, **audio**, **video**, **application**, **text**.
- Link uploaded files with external application owners (pages, articles, posts e.t.c...).
- Manage internal albums: **imageAlbum**, **audioAlbum**, **videoAlbum**, **applicationAlbum**, **textAlbum**, **otherAlbum**.
- Link uploaded files with internal albums (owners).
- Link internal albums with the external owners (pages, articles, posts e.t.c...).
To work with image binary content it uses [Yii2 imagine](https://github.com/yiisoft/yii2-imagine).
To work with Amazon it uses [AWS SDK](https://github.com/aws/aws-sdk-php).
Base project examples, which use this MFUploader module:
[yii2-template-multilanguage](https://github.com/itstructure/yii2-template-multilanguage).
[yii2-template-simple](https://github.com/itstructure/yii2-template-simple).
Addition module description you can see in my [Personal site](https://pack-develop.info/en/product/yii2-multi-format-uploader).
## Requirements
- php >= 7.1
- composer
- MySql >= 5.5
- One of the next php extensions: GD|Imagick|Gmagick
## Installation
### Base install
Via composer:
`composer require itstructure/yii2-multi-format-uploader ~3.2.7`
### If you are testing this package from local server directory
In application `composer.json` file set the repository, like in example:
```json
"repositories": [
{
"type": "path",
"url": "../yii2-multi-format-uploader",
"options": {
"symlink": true
}
}
],
```
Here,
**yii2-multi-format-uploader** - directory name, which has the same directory level like application and contains yii2 multi format uploader package.
Then run command:
`composer require itstructure/yii2-multi-format-uploader:dev-master --prefer-source`
### Apply module migrations
For that make next, **if not already done**:
- Define **mfuploader** module in application **console** config file:
```php
use Itstructure\MFUploader\Module as MFUModule;
```
```php
'modules' => [
'mfuploader' => [
'class' => MFUModule::class,
],
],
```
- In file **yii**, that is located in application root directory, set **@mfuploader** alias:
```php
$application = new yii\console\Application($config);
\Yii::setAlias('@mfuploader', $application->getModule('mfuploader')->getBasePath());
$exitCode = $application->run();
```
OR
```php
use Itstructure\MFUploader\Module as MFUModule;
```
```php
$application = new yii\console\Application($config);
\Yii::setAlias('@mfuploader', MFUModule::getBaseDir());
$exitCode = $application->run();
```
- Run command in console:
`yii migrate --migrationPath=@mfuploader/migrations`
The data base structure:
## Usage
### Main properties
The **name** of module: `mfuploader`
The **namespace** for used classes: `Itstructure\MFUploader`.
The **alias** to access in to module root directory: `@mfuploader`.
### Application config
Base application config must be like in example below:
```php
use Itstructure\MFUploader\Module as MFUModule;
use Itstructure\MFUploader\controllers\ManagerController;
use Itstructure\MFUploader\controllers\upload\{
LocalUploadController,
S3UploadController
};
use Itstructure\MFUploader\controllers\album\{
ImageAlbumController,
AudioAlbumController,
VideoAlbumController,
ApplicationAlbumController,
TextAlbumController,
OtherAlbumController
};
use Itstructure\MFUploader\components\{
LocalUploadComponent,
S3UploadComponent
};
```
```php
'modules' => [
'mfuploader' => [
'class' => MFUModule::class, // REQUIRED
'layout' => ...path to layout..., // NOT REQUIRED
'view' => ...view component config..., // NOT REQUIRED
'controllerMap' => [ // CUSTOM
'upload/local-upload' => LocalUploadController::class,
'upload/s3-upload' => S3UploadController::class,
'managers' => ManagerController::class,
'image-album' => ImageAlbumController::class,
'audio-album' => AudioAlbumController::class,
'video-album' => VideoAlbumController::class,
'application-album' => ApplicationAlbumController::class,
'text-album' => TextAlbumController::class,
'other-album' => OtherAlbumController::class,
],
'accessRoles' => ['admin', 'manager', e.t.c...], // CUSTOM
'defaultStorageType' => MFUModule::STORAGE_TYPE_S3, // CUSTOM
'components' => [ // CUSTOM
'local-upload-component' => [ // CUSTOM
'class' => LocalUploadComponent::class,
'checkExtensionByMimeType' => false,
'uploadRoot' => dirname($_SERVER['SCRIPT_FILENAME'])
],
's3-upload-component' => [ // CUSTOM
'class' => S3UploadComponent::class,
'checkExtensionByMimeType' => false,
'credentials' => require __DIR__ . '/aws-credentials.php',
'region' => 'us-west-2',
's3DefaultBucket' => 'bucketname',
],
],
'publicBaseUrl' => 'http://your-site-address.com'
],
],
```
Here `publicBaseUrl` for example can be a project domain (`http://your-site-address.com`).
If we have `url` in `mediafiles` table `\uploads\images\imagealbum\0d\3890\a947f268d6f9fd02d8a0d7e147da922c.jpg`, and we use **getViewUrl()** function from a `mediafile` model for local files,
then for example a result link to image for `src` attribute of `![]()
` tag will be:
`http://your-site-address.com/uploads/images/imagealbum/0d/3890/a947f268d6f9fd02d8a0d7e147da922c.jpg`
**Note:** It is not necessary to configure two components: `local-upload-component` and `s3-upload-component`.
You must configure minimum one component, according with the `defaultStorageType`.
### File field for the view template
**File field** must be rendered by `FileSetter` widget.
It is necessary to send an ID or URL of uploaded mediafile to you application controller and set in
model.
An after that to link mediafile ID with owner.
Example (for image files):
```php
use Itstructure\MFUploader\widgets\FileSetter;
use Itstructure\MFUploader\Module as MFUModule;
use Itstructure\MFUploader\interfaces\UploadModelInterface;
```
```html
Container to display selected image.
```
```php
echo FileSetter::widget([
'model' => $model,
'attribute' => UploadModelInterface::FILE_TYPE_IMAGE,
'neededFileType' => UploadModelInterface::FILE_TYPE_IMAGE,
'buttonName' => MFUModule::t('main', 'Set image'),
'options' => [
'id' => Html::getInputId($model, UploadModelInterface::FILE_TYPE_IMAGE)
],
'mediafileContainer' => '#mediafile-container',
'titleContainer' => '#title-container',
'descriptionContainer' => '#description-container',
'owner' => 'post', // can be page, article, catalog e.t.c...
'ownerId' => {current owner id, post id, page id e.t.c.},
'ownerAttribute' => UploadModelInterface::FILE_TYPE_IMAGE,
'subDir' => 'post' // can be page, article, catalog e.t.c...
]);
```
### Configure upload components
#### Base attributes in BaseUploadComponent
**Note:** BaseUploadComponent - the base class, which LocalUploadComponent and S3UploadComponent extend.
To understand the principles of configure the base attributes, see public attributes in `components\BaseUploadComponent` class.
But it may be difficult to configure `thumbsConfig` and `thumbFilenameTemplate`.
Attribute `thumbsConfig` takes the values according with the next chain:
1. From the default config file `config/thumbs-config.php` in module **init()** function.
2. Can be rewrited by custom during module `thumbsConfig` attribute.
3. Previous config result inserted in to the `LocalUploadComponent` and `S3UploadComponent` module components.
4. Configuration `thumbsConfig` in module components can be rewrited by custom during component `thumbsConfig` attribute.
#### Attributes in LocalUploadComponent
That is very simple. See public attributes in `components\LocalUploadComponent` class.
#### Attributes in S3UploadComponent
See public attributes in `components\S3UploadComponent` class.
But there are important attributes:
- `credentials`. Attribute to access in to Amazon web services account.
Can be: array, callable, and other. See https://docs.aws.amazon.com/aws-sdk-php/v3/guide/guide/credentials.html.
- `s3DefaultBucket` - bucket, which you use to upload files as default.
- `s3Buckets` - buckets to upload files depending on the owner. Not required.
config example:
```php
's3Buckets' => [
'post' => 'bucketWithPosts',
'page' => 'bucketWithPages',
'imageAlbum' => 'bucketWithImages',
'audioAlbum' => 'bucketWithAudio',
]
```
For more information of S3 configuration, see the next links:
- https://docs.aws.amazon.com/aws-sdk-php/v3/guide/index.html
- https://docs.aws.amazon.com/aws-sdk-php/v3/api
- https://github.com/aws/aws-sdk-php
### Link entities with owners
To link entities (mediafiles and albums) with owners (pages, articles, posts e.t.c...) there is the abstract class `behaviors\Behavior`.
You must use child classes: `behaviors\BehaviorMediafile` and `behaviors\BehaviorAlbum`.
Explanation by example.
You have a `catalog` model which extends an ActiveRecord yii2 class.
Use a `behaviors\BehaviorMediafile` and `behaviors\BehaviorAlbum` in **behaviors** of your `catalog` model to link mediafiles and albums with catalog after: **insert active record**, **update active record**, **delete active record**:
```php
use Itstructure\MFUploader\behaviors\{BehaviorMediafile, BehaviorAlbum};
use Itstructure\MFUploader\interfaces\UploadModelInterface;
use Itstructure\MFUploader\models\album\Album;
```
```php
public $thumbnail;
public $imageAlbum = [];
public function behaviors()
{
return ArrayHelper::merge(parent::behaviors(), [
'mediafile' => [
'class' => BehaviorMediafile::class,
'name' => static::tableName(),
'attributes' => [
UploadModelInterface::FILE_TYPE_THUMB,
],
],
'albums' => [
'class' => BehaviorAlbum::class,
'name' => static::tableName(),
'attributes' => [
Album::ALBUM_TYPE_IMAGE,
],
],
]);
}
```
**Note:** This block should be used in conjunction with the `FileSetter` widget inside the view form template!
Here the following happens:
- If you use a "thumbnail" name of `attribute` param in FileSetter widget, the uploaded mediafile (thumbnail) will be linked with `catalog` after insert new catalog data to the data base.
- If you use an "imageAlbum" (by Album::ALBUM_TYPE_IMAGE) name of the `name` attribute of dropdown or checkbox html field, the last created image album will be linked with `catalog` after insert new catalog data to the data base.
That works according with the next data base example structure:
`Table "mediafiles"` - record with id=20 now inserted.
| id | ... | created_at | updated_at |
|-----|-----|---------------------|---------------------|
| ... | ... | ... | ... |
| 20 | ... | 2018-05-06 21:35:04 | 2018-05-06 21:35:10 |
`Table "catalog"` - record with id=10 inserted after create mediafile (id=20).
| id | ... | created_at | updated_at |
|-----|-----|---------------------|---------------------|
| ... | ... | ... | ... |
| 10 | ... | 2018-05-06 21:35:20 | 2018-05-06 21:35:25 |
`Table "owners_mediafiles"`
| mediafileId | ownerId | owner | ownerAttribute |
|-------------|---------|-----------|------------------|
| ... | ... | ... | ... |
| 20 | 10 | catalog | thumbnail |
`Table "albums"`
| id | type | ... | created_at | updated_at |
|-----|-------------|-----|---------------------|---------------------|
| ... | ... | ... | ... | ... |
| 5 | imageAlbum | ... | 2018-05-06 21:30:00 | 2018-05-06 21:30:05 |
`Table "owners_albums"`
| albumId | ownerId | owner | ownerAttribute |
|---------|---------|-----------|------------------|
| ... | ... | ... | ... |
| 5 | 10 | catalog | imageAlbum |
**Note:** If you set in `FileSetter` widget the attributes: `owner`, `ownerId`, `ownerAttribute` - linking entity with owner will be done automatically during ajax request in **uploadmanager**.
### Integrated album controllers
There are already integrated album controllers in the namespace: `Itstructure\MFUploader\controllers\album`.
Controllers provide the work with the next types of albums: **imageAlbum**, **audioAlbum**, **videoAlbum**, **applicationAlbum**, **textAlbum**, **otherAlbum**.
For that controllers there are already the models and view templates.
To work with that, you must set just the routes in application configuration.
## License
Copyright © 2018-2023 Andrey Girnik [email protected].
Licensed under the [MIT license](http://opensource.org/licenses/MIT). See LICENSE.txt for details.