Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -170,19 +170,19 @@ check-twig-extra:
validate-translations: ensure-up
$(COMPOSE) exec -T $(SERVICE_PHP) php .scripts/validate-translations.php

# REQ-TEST-005: the Integration suite on SQLite, then the lifecycle tests (tests/Integration/Lifecycle: purge, references, moves) on the MySQL 8.4
# service of the root compose (`db` profile, data in tmpfs), like the "Lifecycle on …" CI jobs.
# REQ-TEST-005: the Integration suite on SQLite, then the database files (lifecycle, concurrency, private / dedicated manager) on
# the MySQL 8.4 service of the root compose (`db` profile, data in tmpfs), like the "Lifecycle on …" CI jobs.
STORAGE_KIT_TEST_DATABASE_URL ?= mysql://root:ci-throwaway@db:3306/storagekit?serverVersion=8.4&charset=utf8mb4

db-up:
$(COMPOSE) --profile db up -d --wait db

test-with-db: ensure-up db-up
$(COMPOSE) exec -T $(SERVICE_PHP) vendor/bin/phpunit --testsuite Integration
$(COMPOSE) exec -T -e STORAGE_KIT_TEST_DATABASE_URL='$(STORAGE_KIT_TEST_DATABASE_URL)' $(SERVICE_PHP) vendor/bin/phpunit --no-coverage tests/Integration/Lifecycle
# 1.8: the same in host mode (the suites default to doctrine.private_entity_manager: true).
$(COMPOSE) exec -T -e STORAGE_KIT_TEST_HOST_EM=1 $(SERVICE_PHP) vendor/bin/phpunit --testsuite Integration
$(COMPOSE) exec -T -e STORAGE_KIT_TEST_HOST_EM=1 -e STORAGE_KIT_TEST_DATABASE_URL='$(STORAGE_KIT_TEST_DATABASE_URL)' $(SERVICE_PHP) vendor/bin/phpunit --no-coverage tests/Integration/Lifecycle
# The database files of the CI "Lifecycle on …" jobs (2.0: the private manager only; the 1.8 host-mode runs are gone).
@for path in tests/Integration/Lifecycle tests/Integration/Functional/ArchitectureBarTest.php tests/Integration/Concurrency tests/Integration/Functional/ConcurrentWritesTest.php tests/Integration/Persistence/PrivateEntityManagerKernelTest.php tests/Integration/Persistence/DedicatedEntityManagerKernelTest.php; do \
$(COMPOSE) exec -T -e STORAGE_KIT_TEST_DATABASE_URL='$(STORAGE_KIT_TEST_DATABASE_URL)' $(SERVICE_PHP) vendor/bin/phpunit --no-coverage $$path || exit 1; \
done

test-coverage-with-db: ensure-up db-up
$(COMPOSE) exec -T -e STORAGE_KIT_TEST_DATABASE_URL='$(STORAGE_KIT_TEST_DATABASE_URL)' $(SERVICE_PHP) vendor/bin/phpunit tests/Integration/Lifecycle --coverage-text
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,8 @@ final class IssueContext implements FileContextInterface // autoconfigured
- PHP **8.2+** (`>=8.2 <8.6`, `ext-gd`; Symfony 8.x requires PHP 8.4+)
- Symfony **7.4**, **8.0** or **8.1** (FrameworkBundle with CSRF, Form, Validator, RateLimiter, HttpClient, Lock,
TwigBundle; SecurityBundle for the admin pages)
- Doctrine ORM **3.3+**; `nowo-tech/doctrine-encrypt-bundle` **^2.10** (registered); `nowo-tech/instance-settings-bundle`
- Doctrine ORM **3.3+**; `nowo-tech/doctrine-encrypt-bundle` **^2.10** (registered); `nowo-tech/transaction-doctrine`
**^1.9.1** (the bundle's private entity manager); `nowo-tech/instance-settings-bundle`
**^1.3.1** for the default settings-backed instance bucket (a `suggest` since 2.0: require it yourself);
`nowo-tech/ui-kit-bundle` **^2.23**; `nowo-tech/form-kit-bundle` **^2.17**;
`nowo-tech/outbound-url-guard-bundle` **^1.3**; `async-aws/s3` **^2.8 || ^3.0**; `league/flysystem` **^3.29**;
Expand Down
34 changes: 25 additions & 9 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,24 +6,25 @@ All notable changes to this project are documented here. The format follows
## Table of contents

- [[Unreleased]](#unreleased)
- [Fixed](#fixed)
- [[2.0.0] - 2026-11-21](#200---2026-11-21)
- [Removed](#removed)
- [Changed](#changed)
- [Security](#security)
- [[1.8.1] - 2026-11-20](#181---2026-11-20)
- [Fixed](#fixed)
- [Fixed](#fixed-1)
- [[1.8.0] - 2026-11-20](#180---2026-11-20)
- [Added](#added)
- [Deprecated](#deprecated)
- [Changed](#changed-1)
- [[1.7.1] - 2026-11-19](#171---2026-11-19)
- [Fixed](#fixed-1)
- [Fixed](#fixed-2)
- [[1.7.0] - 2026-11-19](#170---2026-11-19)
- [Added](#added-1)
- [Fixed](#fixed-2)
- [Fixed](#fixed-3)
- [Changed](#changed-2)
- [[1.6.1] - 2026-11-15](#161---2026-11-15)
- [Fixed](#fixed-3)
- [Fixed](#fixed-4)
- [Tests](#tests)
- [[1.6.0] - 2026-11-15](#160---2026-11-15)
- [Added](#added-2)
Expand All @@ -36,10 +37,10 @@ All notable changes to this project are documented here. The format follows
- [Tests](#tests-2)
- [[1.5.2] - 2026-11-13](#152---2026-11-13)
- [Security](#security-2)
- [Fixed](#fixed-4)
- [Fixed](#fixed-5)
- [Tests](#tests-3)
- [[1.5.1] - 2026-11-12](#151---2026-11-12)
- [Fixed](#fixed-5)
- [Fixed](#fixed-6)
- [Tests](#tests-4)
- [[1.5.0] - 2026-11-12](#150---2026-11-12)
- [Added](#added-4)
Expand All @@ -48,10 +49,10 @@ All notable changes to this project are documented here. The format follows
- [[1.4.0] - 2026-11-11](#140---2026-11-11)
- [Added](#added-5)
- [Security](#security-3)
- [Fixed](#fixed-6)
- [Fixed](#fixed-7)
- [Changed](#changed-6)
- [[1.3.0] - 2026-11-11](#130---2026-11-11)
- [Fixed](#fixed-7)
- [Fixed](#fixed-8)
- [Added](#added-6)
- [Changed](#changed-7)
- [Deprecated](#deprecated-2)
Expand All @@ -62,13 +63,28 @@ All notable changes to this project are documented here. The format follows
- [[1.1.0] - 2026-11-03](#110---2026-11-03)
- [Added](#added-8)
- [Changed](#changed-9)
- [Fixed](#fixed-8)
- [Fixed](#fixed-9)
- [[1.0.0] - 2026-11-03](#100---2026-11-03)
- [Added](#added-9)
- [Security](#security-5)

## [Unreleased]

### Fixed

- `Sync\StorageMove::saveTarget()` without its fourth argument (`$configure`) saved nothing for a saved target the
bundle loads again through its own manager (2.0): a target your manager loaded, or one the bundle loaded before a
unit-of-work boundary dropped the private manager (FrankenPHP worker mode included). The connection you set on it
was replaced by the stored row, yet the call returned `true` and audited `move_target_saved`. The connection set on
the target you pass (provider, enabled, endpoints, region, bucket, prefix, access key, path style and a new secret)
is now applied to the bundle's instance inside the same write unit under the owner lock; without a new secret the
stored one is kept. The Move page always passes `$configure` and was not affected (audit YH-1).
- Docs after 2.0 (audit YH-2): USAGE and CONFIGURATION no longer describe the removed `ImageUploader::upload()` or the
1.x flushes of your default manager by the admin pages and commands; README lists `nowo-tech/transaction-doctrine`;
the `FileDeliveryPortsPass` docblock no longer calls the `FileDelivery` id deprecated or mentions `respond()`;
UPGRADING links and duplicated 1.8.0 / 1.8.1 headings fixed; `make test-with-db` runs the CI database files instead
of the removed host-mode runs.

## [2.0.0] - 2026-11-21

2.0.0: the major that removes what 1.x deprecated (REQ-BC-001) and closes REQ-ARCH-001 rules 6 and 8. An application
Expand Down
9 changes: 5 additions & 4 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,17 +257,18 @@ Buckets per scope (organisation, tenant, workspace…).
| Key | Default | Validation / effect |
| --- | --- | --- |
| `table_prefix` | `''` | `[A-Za-z0-9_]*`. Prefixes the tables and index names: `app_` gives `app_storage_kit_file`. |
| `entity_manager` | `null` | `\w+` or `null` (1.5). Null: the bundle writes through a private manager on the connection, mapping and event manager of your default manager (2.0; your manager itself is never used). A name: the bundle entities are mapped on that manager **only** (removed from the others, `auto_mapping` and a default metadata driver — DoctrineBundle 3.4 `auto_discover_entities`, fixed in Unreleased — included), every bundle read and write uses it, the bundle recovers it when closed and clears it at the end of every request, Messenger message and console command; the build fails when the manager is not declared under `doctrine.orm.entity_managers` or does not map the entities. The DDD option, on the same connection as your default manager (see below). |
| `entity_manager` | `null` | `\w+` or `null` (1.5). Null: the bundle writes through a private manager on the connection, mapping and event manager of your default manager (2.0; your manager itself is never used). A name: the bundle entities are mapped on that manager **only** (removed from the others, `auto_mapping` and a default metadata driver — DoctrineBundle 3.4 `auto_discover_entities`, fixed in 1.5.2 — included), every bundle read and write uses it, the bundle recovers it when closed and clears it at the end of every request, Messenger message and console command; the build fails when the manager is not declared under `doctrine.orm.entity_managers` or does not map the entities. The DDD option, on the same connection as your default manager (see below). |
| `private_entity_manager` | `null` | Deprecated since 2.0 (REQ-ARCH-001 rule 6; removed in 3.0). The bundle always reads and writes through a private entity manager created on the connection, mapping and event manager of your default manager: same tables, nothing else to declare, no bundle flush ever writes your pending changes; dropped at every request / message / command boundary and replaced when closed. Unset: that private manager (or, with a dedicated `entity_manager`, that manager directly). `true`: a no-op with a build-time deprecation; with a dedicated `entity_manager`, the private manager on it (as in 1.8). `false`: the build fails ([UPGRADING "To 2.0.0"](UPGRADING.md#to-200)); with a dedicated `entity_manager` it is ignored with a deprecation. |

Tables: `storage_kit_profile`, `storage_kit_file`, `storage_kit_file_reference`, `storage_kit_sync` (see
[ARCHITECTURE](ARCHITECTURE.md#entities-and-tables)).

### Standard Symfony host

Keep `entity_manager: null`: the entities are attribute-mapped on your default manager. Uploads, references, the GDPR
erasure and the settings listener never flush it (DBAL statements); the admin pages and console commands do flush it
(profile save and test, moves, purge).
Keep `entity_manager: null`: the entities are attribute-mapped on your default manager's mapping and written through
the bundle's private manager on its connection (2.0). Uploads, references, the GDPR erasure and the settings listener
never flush a manager (DBAL statements); the admin pages and console commands (profile save and test, moves, purge)
flush only the private manager, never yours (1.x flushed your default manager there).

### DDD / hexagonal host (and new installs)

Expand Down
2 changes: 1 addition & 1 deletion docs/FRANKENPHP-WORKER-AUDIT.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
| Re-audit | 1.5.0 (2026-11-12): **kernel reset false supported.** Dedicated entity manager (`doctrine.entity_manager`) recovered when closed and cleared at the start and at the end of every unit — main request, Messenger message, outermost console command — so even a unit whose end never ran leaves nothing behind (`OwnEntityManagerSubscriber`, console depth counter for nested commands); memos also cleared at the end of the outermost console command; download VO secrets in a `WeakMap` keyed by the per-request VO. Worker test `tests/Integration/Ddd/DddPortsKernelTest.php::testAKeptAliveWorkerAnswersEachUserWithTheirOwnFilesAndFlatMemory`: one kernel, `http_kernel` handle / terminate, no services resetter, **N = 1,200** downloads (600 iterations × 2 files) alternating **alice / bob** (each answer only what that user may read, bytes checked), a Messenger `WorkerMessageHandledEvent` and a `console.terminate` every 100 iterations, bundle manager empty (`UnitOfWork::size() === 0`) after every request, memory growth **< 2 MB** after a 100-iteration warm-up |
| Re-audit | 1.5.1 (2026-11-12, audit NM / NL2-v): the console depth counter of `OwnEntityManagerSubscriber` and `RequestBoundaryListener` could stay above zero after a throwing or propagation-stopping console listener, after which the dedicated manager was never cleared at request boundaries again. Units of work are now tracked at `PHP_INT_MAX` by `UnitOfWorkFrames` (one frame per console run keyed by command and input, saving and restoring the message / request state; failing runs without terminate dropped at the next unit; main requests counted). Test: `tests/Integration/Persistence/ConsoleBoundaryCounterKernelTest.php` |
| Re-audit | 1.8.0 (2026-11-20): `doctrine.private_entity_manager: true` (transaction-doctrine `PrivateEntityManager`) is dropped at the start and end of every outermost request / message / command and at `kernel.reset`, and replaced when closed; the host-flush probe's reported classes are reset at the same boundaries (`StorageHostFlushReporter`). Worker test `tests/Integration/Persistence/PrivateEntityManagerKernelTest.php::testAKeptAliveKernelDropsThePrivateManagerAtEveryRequestBoundary`: one kernel, `handle` / `terminate`, no services resetter, 150 requests, no private manager after any `kernel.terminate`, memory growth < 2 MB after a 50-request warm-up |
| Re-audit | 2.0.0 (Unreleased, REQ-ARCH-001 rule 6): the private manager is the only mode (unless a dedicated `doctrine.entity_manager` is named); the host mode and `StorageHostFlushReporter` are removed, so no service keeps host-flush state. The same worker test runs with the default configuration (no `private_entity_manager` key) |
| Re-audit | 2.0.0 (2026-11-21, REQ-ARCH-001 rule 6): the private manager is the only mode (unless a dedicated `doctrine.entity_manager` is named); the host mode and `StorageHostFlushReporter` are removed, so no service keeps host-flush state. The same worker test runs with the default configuration (no `private_entity_manager` key) |

## Table of contents

Expand Down
30 changes: 9 additions & 21 deletions docs/UPGRADING.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,8 @@
- [Private manager only](#private-manager-only)
- [1.x support](#1x-support)
- [To 1.8.1](#to-181)
- [To 1.8.1](#to-181-1)
- [Missing foreign keys on MySQL / MariaDB (1.5.2 to 1.8.0)](#missing-foreign-keys-on-mysql--mariadb-152-to-180)
- [To 1.8.0](#to-180)
- [To 1.8.0](#to-180-1)
- [The private entity manager notice](#the-private-entity-manager-notice)
- [Reading the host-flush probe](#reading-the-host-flush-probe)
- [Opting in: what changes](#opting-in-what-changes)
Expand Down Expand Up @@ -43,7 +41,7 @@

## Done in 2.0

The breaking changes 1.x announced (REQ-BC-001), applied in 2.0 ([Unreleased](#unreleased)):
The breaking changes 1.x announced (REQ-BC-001), applied in 2.0 ([To 2.0.0](#to-200)):

1. **`nowo-tech/instance-settings-bundle` moved from `require` to `suggest`** (announced in 1.3.0; REQ-ARCH-001
rule 8).
Expand All @@ -55,6 +53,12 @@ The breaking changes 1.x announced (REQ-BC-001), applied in 2.0 ([Unreleased](#u

## Unreleased

From **2.0.0**: `composer update nowo-tech/storage-kit-bundle`. No configuration or code change.

If your code calls `StorageMove::saveTarget($target, $actor, $fields)` without the fourth argument on a target your
own manager loaded (or one kept across requests in a worker), 2.0.0 saved the stored row unchanged and still returned
`true`: save that target again after the update. The Move page was not affected.

## To 2.0.0

From **1.8.1**:
Expand Down Expand Up @@ -225,14 +229,6 @@ From **1.8.0**:
composer update nowo-tech/storage-kit-bundle
```

## To 1.8.1

From **1.8.0**:

```bash
composer update nowo-tech/storage-kit-bundle
```

### Missing foreign keys on MySQL / MariaDB (1.5.2 to 1.8.0)

Only MySQL / MariaDB databases whose bundle tables were created or migrated with doctrine/orm 3.7.0 to 3.8.0 and
Expand Down Expand Up @@ -274,15 +270,7 @@ ALTER TABLE storage_kit_file_reference ADD CONSTRAINT FK_AAE94DBE93CB796C FOREIG

## To 1.8.0

From **1.7.1**:

```bash
composer update nowo-tech/storage-kit-bundle
```

## To 1.8.0

From **1.7.x**:
From **1.7.x** (1.8.0 requires `nowo-tech/transaction-doctrine` ^1.9.1, so update it with the bundle):

```bash
composer update nowo-tech/storage-kit-bundle nowo-tech/transaction-doctrine
Expand Down Expand Up @@ -512,7 +500,7 @@ From 1.4.0 to 1.6.1 two first uploads at the same time (or the first selection o
section racing an upload) could create two active instance rows that read the `storage` section; config profiles
could get two rows the same way. 1.7 creates these rows once, under a lock, but does not repair existing duplicates.
On MySQL / MariaDB 1.7.0 could still create one when the first use ran inside a transaction you opened (fixed in
1.7.1, [Unreleased](#unreleased)). Check once after upgrading (`<prefix>` is `doctrine.table_prefix`, empty by default):
1.7.1, [To 1.7.1](#to-171)). Check once after upgrading (`<prefix>` is `doctrine.table_prefix`, empty by default):

```sql
-- More than one row: the instance has duplicate active rows
Expand Down
10 changes: 6 additions & 4 deletions docs/USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,8 @@

Nothing to configure beyond the [installation](INSTALLATION.md): require and register `NowoInstanceSettingsBundle`
(`nowo-tech/instance-settings-bundle` ^1.3.1, a `suggest` since 2.0) and the instance bucket is the
`storage` settings section; the bundle entities are attribute-mapped on your default entity manager; your texts are
`storage` settings section; the bundle entities are attribute-mapped on your default manager's mapping and written
through the bundle's private manager on its connection (2.0); your texts are
Doctrine entities whose `FileReferenceSourceInterface` makes the references automatic; downloads, rendering and GDPR
hooks are services you inject (`StoredImageResolver`, `StoredFilesPersonalData::exportUser()` / `eraseUser()`).

Expand Down Expand Up @@ -219,8 +220,8 @@ Use `forget('comment', [$id])` when a text is deleted.
Inject `Upload\ImageUploaderInterface` and call `uploadImage($user, $contextType, $contextId, $bytes, $name)`: it
returns a `StoredFileView` DTO (`uuid`, `scope`, context, name, type, sizes, variants, `uploadedBy`, `createdAt`);
reference the file by its `uuid`. The row is written with a DBAL insert built from the entity metadata: **no entity
manager is flushed**, so an upload never commits what your own unit of work left pending (standard applications get
the same guarantee through the deprecated `upload()`, which still returns the `StoredFile` entity).
manager is flushed**, so an upload never commits what your own unit of work left pending (2.0 removed the 1.3
`upload()` that returned the `StoredFile` entity; load the row by `uuid` if you need it).

- *Outside a transaction* the row is committed at once and the `file_uploaded` audit event follows.
- *Inside your transaction* (the host controls the unit of work) the row joins it in a savepoint (a failed insert rolls
Expand Down Expand Up @@ -453,7 +454,8 @@ WebP are re-encoded (EXIF / GPS / XMP dropped, JPEGs turned upright); GIF and an
| 503 | `storage` | the bucket failed (objects already written are removed) |

`message` is the translated `upload.error.<reason>`. Answers are `private, no-store`, `nosniff`. A refused upload
stores nothing. The PHP API behind it is `Upload\ImageUploader::upload($user, $type, $id, $bytes, $name)`.
stores nothing. The PHP API behind it is `Upload\ImageUploaderInterface::uploadImage($user, $type, $id, $bytes, $name)`
(a `StoredFileView`; [Uploading from your code](#uploading-from-your-code-13)).

A new file is an orphan until a text that points at it is saved ([References](#references-and-the-purge)).

Expand Down
Loading
Loading