rasuvaeff/yii3-filestorage-attachments

Tenant-scoped polymorphic file attachments for rasuvaeff/yii3-filestorage

v0.1.0 2026-08-14 17:30 UTC

Requires

• php: 8.3 - 8.5
• rasuvaeff/yii3-filestorage: ^0.1.1
• rasuvaeff/yii3-filestorage-db: ^0.1
• yiisoft/db: ^2.0
• yiisoft/db-migration: ^2.1

Requires (Dev)

• ergebnis/composer-normalize: ^2.51
• friendsofphp/php-cs-fixer: ^3.95
• infection/infection: ^0.33
• maglnet/composer-require-checker: ^4.17
• rasuvaeff/property-testing-testo: ^0.1
• rasuvaeff/rector-named-literals: ^1.0
• rector/rector: ^2.4
• roave/backward-compatibility-check: ^8.0
• testo/bridge-infection: ^0.1.6
• testo/testo: ^0.10.25
• vimeo/psalm: ^6.16
• yiisoft/cache: ^3.2
• yiisoft/db-sqlite: ^2.0
• yiisoft/di: ^1.4
• yiisoft/injector: ^1.2

BSD-3-Clause

• Victor Razuvaev

• polymorphic
• attachments
• yii3
• file-storage

Published on Packagist.org on 2026-08-14 17:30 UTC

README

rasuvaeff/yii3-filestorage-attachments provides a small database-backed owner-to-file link service for Yii3 Filestorage. It covers the common polymorphic attachment case without requiring Active Record.

Install

composer require rasuvaeff/yii3-filestorage-attachments

The package requires rasuvaeff/yii3-filestorage-db. Run its file-table migration first, then register this package's migration namespace:

MigrationService::class => [
    'setSourceNamespaces()' => [[
        'Rasuvaeff\\Yii3FilestorageDb\\Migration',
        'Rasuvaeff\\Yii3FilestorageAttachments\\Migration',
    ]],
],

The config plugin supplies AttachmentTableName and Attachments. It does not bind FileScopeProviderInterface; applications with tenants bind that contract once, and the same provider is used by yii3-filestorage-db.

Usage

$attachments->attach(
    file: $file,
    ownerType: 'order',
    ownerId: (string) $orderId,
    role: 'invoice',
);

$invoices = $attachments->forOwner(
    ownerType: 'order',
    ownerId: (string) $orderId,
    role: 'invoice',
);

$attachments->detach(
    file: $file,
    ownerType: 'order',
    ownerId: (string) $orderId,
    role: 'invoice',
);

attach() is idempotent and returns false when the exact link already exists. forOwner() returns list<Attachment> in insertion order; omit role to list every role. detachOwner() removes every role and file link for an owner and must be called by the application or an Active Record lifecycle when that owner is deleted.

The table has a real foreign key to filestorage_file, so deleting a file row automatically removes its links. There is deliberately no generic foreign key to owner tables.

SQLite prerequisite: SQLite enforces ON DELETE CASCADE only when every connection enables PRAGMA foreign_keys = ON. The package does not configure connections injected into it — do this in your application's connection setup. MySQL/MariaDB and PostgreSQL enforce the cascade by default.

Table names and scope

Set rasuvaeff/yii3-filestorage-attachments.attachmentTable and tablePrefix in application params when the defaults conflict. The migration and runtime service resolve the same typed AttachmentTableName.

With no scope provider, links use an internal empty scope key. With a bound FileScopeProviderInterface, every operation is restricted to its current scope and a file must be visible in that scope before it can be attached.

Verification

make build
make test-integration
make rector

The integration suite applies the real yii3-filestorage-db and attachments migrations on SQLite and exercises the documented migration path.