You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: documentation/components/bridges/symfony-filesystem-bundle.md
+120-6Lines changed: 120 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,6 +32,7 @@ This bundle integrates Flow PHP's Filesystem library with Symfony applications.
32
32
-**Pluggable filesystem factories** — register custom backends with the `#[AsFilesystemFactory]` attribute or a DI tag
33
33
-**Built-in factories** — `file`, `memory`, `stdout`, `aws_s3`, and `azure_blob` ship out of the box
34
34
-**Console commands** — `flow:filesystem:*` (alias `flow:fs:*`) for `ls`, `cat`, `cp`, `mv`, `rm`, `stat`, `touch` against any configured filesystem
35
+
-**Symfony Cache pools** — register PSR-6 cache pools backed by any mounted filesystem (local disk, S3, Azure Blob …) when [flow-php/symfony-filesystem-cache-bridge](/documentation/components/bridges/symfony-filesystem-cache-bridge.md) is installed
35
36
-**Telemetry integration** — wrap every filesystem in `TraceableFilesystem` via OpenTelemetry
36
37
-**Multi-fstab support***(advanced)* — configure several independent `FilesystemTable` services when you really need them
37
38
@@ -119,7 +120,7 @@ flow_filesystem:
119
120
client_service_id: app.s3_client
120
121
```
121
122
122
-
The fstab is wired as a private `.flow_filesystem.fstab.<name>` service and aliased to
123
+
The fstab is wired as a private `.flow.filesystem.fstab.<name>` service and aliased to
123
124
`Flow\Filesystem\FilesystemTable`for autowiring.
124
125
125
126
### Default Fstab
@@ -393,6 +394,119 @@ Remote object stores (S3, Azure Blob, …) do not have a real concept of directo
393
394
keyspaces with `/` as a convention. Rather than emulate `mkdir` inconsistently across backends, the bundle
394
395
omits the command entirely. Directories appear when files appear inside them.
395
396
397
+
## Symfony Cache Integration
398
+
399
+
The bundle integrates with [flow-php/symfony-filesystem-cache-bridge](/documentation/components/bridges/symfony-filesystem-cache-bridge.md) to provide PSR-6 / Symfony Cache pools backed by any filesystem already mounted in a fstab — local disk, S3, Azure Blob, anything the bundle's factories can build. The adapter implements `PruneableInterface`, so `cache:pool:prune` works out of the box.
400
+
401
+
Each pool resolves its filesystem **through a fstab mount**, not by referencing a service id directly. Filesystems must already be declared under `flow_filesystem.fstabs.<fstab>.filesystems.<protocol>` before a cache pool can target them. This keeps fstab the single place where filesystems live and avoids the cache and the rest of the app drifting into separate filesystem definitions.
2. Define one or more pools under `flow_filesystem.cache.pools`. Each pool names a fstab mount (the YAML key under `filesystems:`) and a base path inside it:
412
+
413
+
```yaml
414
+
# config/packages/flow_filesystem.yaml
415
+
flow_filesystem:
416
+
fstabs:
417
+
default:
418
+
filesystems:
419
+
file:
420
+
type: file
421
+
422
+
cache:
423
+
pools:
424
+
app:
425
+
filesystem: file # mount protocol from the default fstab
`fstab` is optional and defaults to the bundle's resolved default fstab — same rule the `flow:filesystem:*` CLI commands follow. Set it explicitly when you want a pool to use a non-default fstab:
437
+
438
+
```yaml
439
+
flow_filesystem:
440
+
default_fstab: primary
441
+
fstabs:
442
+
primary:
443
+
filesystems:
444
+
file:
445
+
type: file
446
+
archive:
447
+
filesystems:
448
+
aws-s3:
449
+
type: aws_s3
450
+
bucket: '%env(ARCHIVE_BUCKET)%'
451
+
452
+
cache:
453
+
pools:
454
+
cold_storage:
455
+
fstab: archive
456
+
filesystem: aws-s3
457
+
path: '/cache/cold'
458
+
default_lifetime: 86400
459
+
```
460
+
461
+
Each pool registers as `flow.filesystem.cache.pool.<name>` (public).
462
+
463
+
3. Wire the pools into Symfony's cache framework via `cache.adapter.psr6`:
464
+
465
+
```yaml
466
+
# config/packages/framework.yaml
467
+
framework:
468
+
cache:
469
+
pools:
470
+
cache.app_fs:
471
+
adapter: cache.adapter.psr6
472
+
provider: flow.filesystem.cache.pool.app
473
+
474
+
cache.sessions_fs:
475
+
adapter: cache.adapter.psr6
476
+
provider: flow.filesystem.cache.pool.sessions
477
+
```
478
+
479
+
The `cache.adapter.psr6` wrapper is required because Symfony's `CachePoolPass` overwrites the first constructor argument of any service used directly as `adapter:`, which conflicts with this bridge's strict `Filesystem` typing on argument 0.
| `fstab` | default fstab | Fstab name. Defaults to the bundle's resolved default fstab when omitted. |
486
+
| `filesystem` | *required* | Mount protocol within the chosen fstab (the YAML key under `filesystems:`). |
487
+
| `path` | *required* | Base directory inside the chosen filesystem where cache files are stored. |
488
+
| `namespace` | `''` | Cache pool namespace; chars in `[-+.A-Za-z0-9]` only. |
489
+
| `default_lifetime` | `0` | Default TTL in seconds; `0` means no expiry. |
490
+
| `marshaller_service_id` | `null` | Service ID of a custom `MarshallerInterface`. |
491
+
492
+
Validation runs at container compile time:
493
+
494
+
- A pool referencing a missing fstab fails with `flow_filesystem.cache.pools.<name>: fstab "<x>" is not declared. Available fstabs: [...]`.
495
+
- A pool referencing a mount protocol that is not registered in the chosen fstab fails with `flow_filesystem.cache.pools.<name>: filesystem "<x>" is not mounted in fstab "<y>". Available mounts: [...]`.
496
+
- `flow_filesystem.cache.pools`is configured but `flow-php/symfony-filesystem-cache-bridge` is not installed → fails fast with a message pointing at the missing package.
497
+
498
+
### Pruning
499
+
500
+
Schedule the standard Symfony command on a cron to remove expired files:
501
+
502
+
```bash
503
+
php bin/console cache:pool:prune
504
+
```
505
+
506
+
Without pruning, expired files accumulate under each pool's directory. They are filtered out on read but only deleted when either the same key is fetched again or `cache:pool:prune` runs.
507
+
508
+
For full documentation, see the [Symfony Filesystem Cache Bridge](/documentation/components/bridges/symfony-filesystem-cache-bridge.md).
509
+
396
510
## Multi-Fstab Support
397
511
398
512
> **Advanced.** Most applications should stick to a single fstab with multiple filesystems mounted under
@@ -425,7 +539,7 @@ flow_filesystem:
425
539
bucket: '%env(ARCHIVE_BUCKET)%'
426
540
```
427
541
428
-
Each fstab gets its own `.flow_filesystem.fstab.<name>` service. The default fstab is automatically aliased
542
+
Each fstab gets its own `.flow.filesystem.fstab.<name>` service. The default fstab is automatically aliased
429
543
to `Flow\Filesystem\FilesystemTable`, allowing direct type-hint injection without specifying a fstab name.
430
544
Each named fstab is also aliased as `Flow\Filesystem\FilesystemTable $<camelCasedName>Fstab` for
431
545
named-argument autowiring:
@@ -507,7 +621,7 @@ final class MyFilesystemFactory implements FilesystemFactory
507
621
```
508
622
509
623
As long as your service is autoconfigured (the default in `services.yaml` for everything under your `App\`
510
-
namespace), the bundle automatically attaches the `flow_filesystem.factory` tag with the right `type`
624
+
namespace), the bundle automatically attaches the `flow.filesystem.factory` tag with the right `type`
0 commit comments