mheads/yii-filestorage-active-record

1.0.0-beta1 2026-06-04 14:09 UTC

Requires

• php: 8.3 - 8.5
• mheads/yii-filestorage-db: 1.0.0-beta1
• yiisoft/active-record: ^1.0.2
• yiisoft/event-dispatcher: ^1.1

Requires (Dev)

• ext-pdo: *
• friendsofphp/php-cs-fixer: ^3.94
• httpsoft/http-message: ^1.1
• phpunit/phpunit: ^12.5
• vimeo/psalm: ^6.16
• yiisoft/cache: ^3.0
• yiisoft/db-migration: ^2.0
• yiisoft/db-mssql: ^2.0
• yiisoft/db-mysql: ^2.0
• yiisoft/db-oracle: ^2.0
• yiisoft/db-pgsql: ^2.0
• yiisoft/db-sqlite: ^2.0
• yiisoft/dummy-provider: ^1.1
• yiisoft/test-support: ^3.2

BSD-3-Clause

• MachineHeads
• Sergey Alekseenko

README

ActiveRecord adapter for mheads/yii-filestorage.

The package provides:

• ActiveRecordRepository - a RepositoryInterface implementation that stores file metadata through yiisoft/active-record.
• ArFile - an ActiveRecord file entity for the mh_filestorage_file table.
• #[FileUpload] - an ActiveRecord event handler that uploads pending files on save and cleans old files on replace/delete.
• PendingUploadedFileOwnerInterface and PendingUploadedFileOwnerTrait - a small model-side queue for uploaded files.

Physical file storage is still handled by the core package stores, for example PublicFileSystemStore and PrivateFileSystemStore. The file metadata table schema and DbRepository come from mheads/yii-filestorage-db, which is installed as a dependency.

Installation

composer require mheads/yii-filestorage-active-record

Also install the database driver used by your project:

composer require yiisoft/db-mysql

Before using this ActiveRecord adapter, complete the mheads/yii-filestorage-db DB adapter setup, including the DB driver and file metadata table. For the demo product table used in examples, see example migrations.

Quick Start

use Mheads\Yii\Filestorage\ActiveRecord\ActiveRecordRepository;
use Mheads\Yii\Filestorage\ActiveRecord\ArFile;
use Mheads\Yii\Filestorage\Storage;
use Mheads\Yii\Filestorage\StorageProvider;
use Yiisoft\Db\Connection\ConnectionProvider;

ConnectionProvider::set($db);

$storage = new Storage(
    repository: new ActiveRecordRepository(ArFile::class),
    stores: [$publicStore],
    defaultStoreName: 'upload',
    defaultGroupName: 'products',
);
StorageProvider::set($storage);

$product = new Product();
$product->setPicture($uploadedFile);
$product->save();

$publicStore is a core package store, for example PublicFileSystemStore. Product should use #[FileUpload] and PendingUploadedFileOwnerTrait; see the lifecycle guide below.

ConnectionProvider::set() is required for ArFile, ActiveRecordRepository, and AR relations. StorageProvider::set() is required for #[FileUpload] and direct file methods such as getUrl().

See the full flow in AR file upload lifecycle and 02-active-record-file-upload.php.

Documentation

• Guide
• Examples
• Internals

License

BSD-3-Clause