{"id":15169478,"url":"https://github.com/yii2tech/file-storage","last_synced_at":"2025-10-01T02:31:13.292Z","repository":{"id":1064498,"uuid":"38484900","full_name":"yii2tech/file-storage","owner":"yii2tech","description":"This package has been abandoned. See: https://www.patreon.com/posts/59332556","archived":true,"fork":false,"pushed_at":"2021-04-01T16:37:56.000Z","size":96,"stargazers_count":119,"open_issues_count":0,"forks_count":30,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-09-22T22:01:55.969Z","etag":null,"topics":["amazon","bucket","file","files","filesystem","gridfs","mongodb","sftp","storage","yii","yii2","yii2-extension"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yii2tech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["klimov-paul"],"patreon":"klimov_paul"}},"created_at":"2015-07-03T09:34:53.000Z","updated_at":"2024-05-09T14:48:59.000Z","dependencies_parsed_at":"2022-08-06T10:15:11.419Z","dependency_job_id":null,"html_url":"https://github.com/yii2tech/file-storage","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yii2tech%2Ffile-storage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yii2tech%2Ffile-storage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yii2tech%2Ffile-storage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yii2tech%2Ffile-storage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yii2tech","download_url":"https://codeload.github.com/yii2tech/file-storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219875269,"owners_count":16554660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon","bucket","file","files","filesystem","gridfs","mongodb","sftp","storage","yii","yii2","yii2-extension"],"created_at":"2024-09-27T07:01:49.687Z","updated_at":"2025-10-01T02:31:12.809Z","avatar_url":"https://github.com/yii2tech.png","language":"PHP","funding_links":["https://github.com/sponsors/klimov-paul","https://patreon.com/klimov_paul"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/yii2tech\" target=\"_blank\"\u003e\n        \u003cimg src=\"https://avatars2.githubusercontent.com/u/12951949\" height=\"100px\"\u003e\n    \u003c/a\u003e\n    \u003ch1 align=\"center\"\u003eFile Storage Extension for Yii 2\u003c/h1\u003e\n    \u003cbr\u003e\n\u003c/p\u003e\n\nThis extension provides file storage abstraction layer for Yii2.\n\nFor license information check the [LICENSE](LICENSE.md)-file.\n\n[![Latest Stable Version](https://poser.pugx.org/yii2tech/file-storage/v/stable.png)](https://packagist.org/packages/yii2tech/file-storage)\n[![Total Downloads](https://poser.pugx.org/yii2tech/file-storage/downloads.png)](https://packagist.org/packages/yii2tech/file-storage)\n[![Build Status](https://travis-ci.org/yii2tech/file-storage.svg?branch=master)](https://travis-ci.org/yii2tech/file-storage)\n\n\nInstallation\n------------\n\nThe preferred way to install this extension is through [composer](http://getcomposer.org/download/).\n\nEither run\n\n```\nphp composer.phar require --prefer-dist yii2tech/file-storage\n```\n\nor add\n\n```json\n\"yii2tech/file-storage\": \"*\"\n```\n\nto the require section of your composer.json.\n\nIf you wish to use Amazon S3 storage, you should also install [aws/aws-sdk-php](https://github.com/aws/aws-sdk-php) version 2.\nEither run\n\n```\nphp composer.phar require --prefer-dist aws/aws-sdk-php:~2.0\n```\n\nor add\n\n```json\n\"aws/aws-sdk-php\": \"~2.0\"\n```\n\nto the require section of your composer.json.\n\nIf you wish to use MongoDB storage, you should also install [yiisoft/yii2-mongodb](https://github.com/yiisoft/yii2-mongodb) version 2.1.\nEither run\n\n```\nphp composer.phar require --prefer-dist yiisoft/yii2-mongodb:~2.1.0\n```\n\nor add\n\n```json\n\"yiisoft/yii2-mongodb\": \"2.1.0\"\n```\n\nto the require section of your composer.json.\n\n\nUsage\n-----\n\nThis extension provides file storage abstraction layer for Yii2.\nThis abstraction introduces 2 main terms: 'storage' and 'bucket'.\n'Storage' - is a unit, which is able to store files using some particular approach.\n'Bucket' - is a logical part of the storage, which has own specific attributes and serves some logical mean.\nEach time you need to read/write a file you should do it via particular bucket, which is always belongs to the\nfile storage.\n\nExample application configuration:\n\n```php\nreturn [\n    'components' =\u003e [\n        'fileStorage' =\u003e [\n            'class' =\u003e 'yii2tech\\filestorage\\local\\Storage',\n            'basePath' =\u003e '@webroot/files',\n            'baseUrl' =\u003e '@web/files',\n            'dirPermission' =\u003e 0775,\n            'filePermission' =\u003e 0755,\n            'buckets' =\u003e [\n                'tempFiles' =\u003e [\n                    'baseSubPath' =\u003e 'temp',\n                    'fileSubDirTemplate' =\u003e '{^name}/{^^name}',\n                ],\n                'imageFiles' =\u003e [\n                    'baseSubPath' =\u003e 'image',\n                    'fileSubDirTemplate' =\u003e '{ext}/{^name}/{^^name}',\n                ],\n            ]\n        ],\n        // ...\n    ],\n    // ...\n];\n```\n\nExample usage:\n\n```php\n$bucket = Yii::$app-\u003efileStorage-\u003egetBucket('tempFiles');\n\n$bucket-\u003esaveFileContent('foo.txt', 'Foo content'); // create file with content\n$bucket-\u003edeleteFile('foo.txt'); // deletes file from bucket\n$bucket-\u003ecopyFileIn('/path/to/source/file.txt', 'file.txt'); // copy file into the bucket\n$bucket-\u003ecopyFileOut('file.txt', '/path/to/destination/file.txt'); // copy file from the bucket\nvar_dump($bucket-\u003efileExists('file.txt')); // outputs `true`\necho $bucket-\u003egetFileUrl('file.txt'); // outputs: 'http://domain.com/files/f/i/file.txt'\n```\n\nFollowing file storages are available with this extension:\n - [[\\yii2tech\\filestorage\\local\\Storage]] - stores files on the OS local file system.\n - [[\\yii2tech\\filestorage\\sftp\\Storage]] - stores files using SSH2 SFTP.\n - [[\\yii2tech\\filestorage\\amazon\\Storage]] - stores files using Amazon simple storage service (S3).\n - [[\\yii2tech\\filestorage\\mongodb\\Storage]] - stores files using MongoDB GridFS.\n - [[\\yii2tech\\filestorage\\hub\\Storage]] - allows combination of different file storages.\n\nPlease refer to the particular storage class for more details.\n\n**Heads up!** Some of the storages may require additional libraries or PHP extensions, which are not\nrequired with this package by default, to be installed. Please check particular storage class documentation\nfor the details.\n\n\n## Abstraction usage \u003cspan id=\"abstraction-usage\"\u003e\u003c/span\u003e\n\nEach provided storage implements same interface for the files processing. Thus each storage can substitute another one,\nunless program code follows this interface. This allows you to switch between different storages without being need to\nadjust program source code. For example, at production server you may need to use SFTP for files storing and your application\nconfig looks like following:\n\n```php\nreturn [\n    'components' =\u003e [\n        'fileStorage' =\u003e [\n            'class' =\u003e 'yii2tech\\filestorage\\sftp\\Storage',\n            'ssh' =\u003e [\n                'host' =\u003e 'file.server.com',\n                'username' =\u003e 'user',\n                'password' =\u003e 'some-password',\n            ],\n            'basePath' =\u003e '/var/www/html/files',\n            'baseUrl' =\u003e 'http://file.server.com/files',\n            'buckets' =\u003e [\n                'temp',\n                'item',\n            ]\n        ],\n        // ...\n    ],\n    // ...\n];\n```\n\nHowever, at development environment you may use simple local file storage instead:\n\n```php\nreturn [\n    'components' =\u003e [\n        'fileStorage' =\u003e [\n            'class' =\u003e 'yii2tech\\filestorage\\local\\Storage',\n            'basePath' =\u003e '@webroot/files',\n            'baseUrl' =\u003e '@web/files',\n            'buckets' =\u003e [\n                'temp',\n                'item',\n            ]\n        ],\n        // ...\n    ],\n    // ...\n];\n```\n\nYou can also combine several different storages using [[\\yii2tech\\filestorage\\hub\\Storage]], if necessary:\n\n```php\nreturn [\n    'components' =\u003e [\n        'fileStorage' =\u003e [\n            'class' =\u003e 'yii2tech\\filestorage\\hub\\Storage',\n            'storages' =\u003e [\n                [\n                    'class' =\u003e 'yii2tech\\filestorage\\sftp\\Storage',\n                    'ssh' =\u003e [\n                        'host' =\u003e 'file.server.com',\n                        'username' =\u003e 'user',\n                        'password' =\u003e 'some-password',\n                    ],\n                    'basePath' =\u003e '/var/www/html/files',\n                    'baseUrl' =\u003e 'http://file.server.com/files',\n                    'buckets' =\u003e [\n                        'item',\n                    ]\n                ],\n                [\n                    'class' =\u003e 'yii2tech\\filestorage\\local\\Storage',\n                    'basePath' =\u003e '@webroot/files',\n                    'baseUrl' =\u003e '@web/files',\n                    'buckets' =\u003e [\n                        'temp',\n                    ]\n                ]\n            ],\n        ],\n        // ...\n    ],\n    // ...\n];\n```\n\n\n## Accessing files by URL \u003cspan id=\"accessing-files-by-url\"\u003e\u003c/span\u003e\n\nAlmost all file storage implementation, implemented in this extension, provide mechanism for accessing stored files\nvia web URL. Actual mechanism implementation may vary depending on particular storage. For example: [[\\yii2tech\\filestorage\\local\\Storage]]\nallows setup of the URL leading to its root folder, creating URL for particular file appending its name to base URL,\nwhile [[\\yii2tech\\filestorage\\amazon\\Storage]] uses S3 built-in object URL composition.\n\nIn order to get URL leading to the stored file, you should use [[\\yii2tech\\filestorage\\BucketInterface::getFileUrl()]] method:\n\n```php\n$bucket = Yii::$app-\u003efileStorage-\u003egetBucket('tempFiles');\n\n$fileUrl = $bucket-\u003egetFileUrl('image.jpg');\n```\n\nIn case particular storage does not provide native URL file access, or it is not available or not desirable by some reason,\nyou can setup composition of the file URL via Yii URL route mechanism. You need to setup `baseUrl` to be an array, containing\nroute, which leads to the Yii controller action, which will return the file content. For example:\n\n```php\nreturn [\n    'components' =\u003e [\n        'fileStorage' =\u003e [\n            'class' =\u003e 'yii2tech\\filestorage\\local\\Storage',\n            'baseUrl' =\u003e ['/file/download'],\n            // ...\n        ],\n        // ...\n    ],\n    // ...\n];\n```\n\nWith this configuration `getFileUrl()` method will use current application URL manager to create URL. Doing so it\nwill add bucket name as `bucket` parameter and file name as `filename` parameter. For example:\n\n```php\nuse yii\\helpers\\Url;\n\n$bucket = Yii::$app-\u003efileStorage-\u003egetBucket('images');\n\n$fileUrl = $bucket-\u003egetFileUrl('logo.png');\n$manualUrl = Url::to(['/file/download', 'bucket' =\u003e 'images', 'filename' =\u003e 'logo.png']);\nvar_dump($fileUrl === $manualUrl); // outputs `true`\n```\n\nYou may setup [[\\yii2tech\\filestorage\\DownloadAction]] to handle file content web access. For example:\n\n```php\nclass FileController extends \\yii\\web\\Controller\n{\n    public function actions()\n    {\n        return [\n            'download' =\u003e [\n                'class' =\u003e 'yii2tech\\filestorage\\DownloadAction',\n            ],\n        ];\n    }\n}\n```\n\n\u003e Tip: usage of the controller action for the file web access usually slower then native mechanism provided by\n  file storage, however, you may put some extra logic into it, like allowing file access for logged in users only.\n\n\n## Processing of the large files \u003cspan id=\"processing-of-the-large-files\"\u003e\u003c/span\u003e\n\nSaving or reading large files, like \u003e 100 MB, using such methods like [[\\yii2tech\\filestorage\\BucketInterface::saveFileContent()]] or\n[[\\yii2tech\\filestorage\\BucketInterface::getFileContent()]], may easily exceed PHP memory limit, breaking the script.\nYou should use [[\\yii2tech\\filestorage\\BucketInterface::openFile()]] method to create a file resource similar to the one\ncreated via [[fopen()]] PHP function. Such resource can be read or written by blocks, keeping memory usage low.\nFor example:\n\n```php\n$bucket = Yii::$app-\u003efileStorage-\u003egetBucket('tempFiles');\n\n$resource = $bucket-\u003eopenFile('new_file.dat', 'w');\nfwrite($resource, 'content part1');\nfwrite($resource, 'content part2');\n// ...\nfclose($resource);\n\n$resource = $bucket-\u003eopenFile('existing_file.dat', 'r');\nwhile (!feof($resource)) {\n    echo fread($resource, 1024);\n}\nfclose($resource);\n```\n\n\u003e Note: You should prefer usage of simple modes like `r` and `w`, avoiding complex ones like `w+`, as they\n  may be not supported by some storages.\n\n\n## Logging \u003cspan id=\"logging\"\u003e\u003c/span\u003e\n\nEach file operation performed by file storage component is logged.\nIn order to setup a log target, which can capture all entries related to file storage, you should\nuse category `yii2tech\\filestorage\\*`. For example:\n\n```php\nreturn [\n    // ...\n    'components' =\u003e [\n        // ...\n        'log' =\u003e [\n            // ...\n            'targets' =\u003e [\n                [\n                    'class' =\u003e 'yii\\log\\FileTarget',\n                    'logFile' =\u003e '@runtime/logs/file-storage.log',\n                    'categories' =\u003e ['yii2tech\\filestorage\\*'],\n                ],\n                // ...\n            ],\n        ],\n    ],\n];\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyii2tech%2Ffile-storage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyii2tech%2Ffile-storage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyii2tech%2Ffile-storage/lists"}