[TASK] Upgrade league/flysystem from v1 to v3#1186
Merged
linawolf merged 1 commit intoTYPO3-Documentation:mainfrom Mar 1, 2026
Merged
[TASK] Upgrade league/flysystem from v1 to v3#1186linawolf merged 1 commit intoTYPO3-Documentation:mainfrom
linawolf merged 1 commit intoTYPO3-Documentation:mainfrom
Conversation
CybotTM
force-pushed
the
feature/flysystem-3
branch
from
8c46e6f to
05a32ed
Compare
Upgrade league/flysystem from v1 (1.x) to v3 (3.x): - Replace league/flysystem ^1.1.10 with ^3.29 - Add league/flysystem-local ^3.0 dependency - Replace Flysystem v1 API (put/putStream/has/read/readStream) with v3 equivalents (write/writeStream/fileExists/read/readStream) - Update CopyResources to use FilesystemException with try/catch/finally for proper error handling and stream cleanup - Update composer.lock (flysystem 3.32.0, flysystem-local 3.31.0, flyfinder 2.0.0) Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
CybotTM
force-pushed
the
feature/flysystem-3
branch
from
05a32ed to
b54885e
Compare
Contributor
Author
|
added another fix and rebased/resolved conflict. |
linawolf
approved these changes
Mar 1, 2026
Member
|
Thanks for taking care of this! I had planned to do the upgrade and then life happened... |
This was referenced Apr 23, 2026
CybotTM
added a commit
to netresearch/typo3-ci-workflows
that referenced
this pull request
Apr 23, 2026
## Summary Bumps the pinned `render-guides` image to **0.37.1** and corrects a stale/mislabelled pin. | | Before | After | |---|---|---| | Comment | `# typo3-documentation/render-guides 0.37.0` | `# typo3-documentation/render-guides 0.37.1` | | Digest | `sha256:431ac264…` (built **2026-01-18**) | `sha256:2281eeae9bf0b8f490d9be6c8d6a3b64ccb7e178f8dd14a390fc92997524f0c5` (built 2026-03-27) | | `league/flysystem` | 1.1.10 (EOL) | 3.32.0 | ## The stale-pin story The previous pin's comment said **0.37.0** but the digest was built on **2026-01-18** — a full two months before the `0.37.0` git tag existed (2026-03-20). Whoever added the pin captured `:latest` or `:main` at the time, not a resolved `:0.37.0` image. Even more: **no `:0.37.0` Docker image exists on ghcr.io**. Published tags on the registry jump from `0.36.0` straight to `0.37.1`. The reason: the 0.37.0 release's Docker-publish workflow was missing write permission. [TYPO3-Documentation/render-guides#1211](TYPO3-Documentation/render-guides#1211) ("Update docker.yaml - add permissions") fixed it in 0.37.1. ## Why this matters The old pinned digest still ships `league/flysystem` v1, whose `Local` adapter throws `NotSupportedException` on any symbolic link encountered during `listContents()` — aborting the entire render, with no way to pre-exclude via `--exclude-path`. The upstream Flysystem v1 → v3 upgrade is [TYPO3-Documentation/render-guides#1186](TYPO3-Documentation/render-guides#1186) (merged 2026-03-01). The source fix is present from `0.37.0` onward; the first **image** carrying it is `0.37.1`. ## Concrete failure this fixes - Repo: `netresearch/t3x-nr-llm` - Failing run: https://github.com/netresearch/t3x-nr-llm/actions/runs/24824959021/job/72658428311 - PR that triggered it: netresearch/t3x-nr-llm#136 ## Verification ```bash $ docker pull ghcr.io/typo3-documentation/render-guides:0.37.1 $ docker inspect ghcr.io/typo3-documentation/render-guides:0.37.1 \ --format '{{index .RepoDigests 0}}' ghcr.io/typo3-documentation/render-guides@sha256:2281eeae9bf0b8f490d9be6c8d6a3b64ccb7e178f8dd14a390fc92997524f0c5 $ docker run --rm --entrypoint sh \ ghcr.io/typo3-documentation/render-guides:0.37.1 \ -c "grep -A1 'league/flysystem\"' /opt/guides/composer.lock | head -2" "name": "league/flysystem", "version": "3.32.0", ``` ## Test plan - [ ] Self-CI passes on this workflow repo - [ ] Downstream docs workflow (e.g. `nr-llm`) renders `Documentation/` successfully with symlinks present
CybotTM
added a commit
to netresearch/t3x-nr-llm
that referenced
this pull request
Apr 23, 2026
Upstream root cause is fixed: render-guides 0.37.1 ships league/flysystem 3.32.0, which handles symbolic links natively. The shared CI workflow (netresearch/typo3-ci-workflows@main) now pins that image, so the docs build no longer crashes on symlinks in Documentation/. Chain: - TYPO3-Documentation/render-guides#1186 — flysystem v1 -> v3 (merged 2026-03-01) - TYPO3-Documentation/render-guides 0.37.1 — first image carrying it - netresearch/typo3-ci-workflows#63 — bumped pinned digest - netresearch/typo3-ci-workflows#64 — added Renovate customManager so this kind of env-var digest pin cannot rot silently again Effectively reverts 54dbb51 now that the blocker is gone, giving Claude Code users scoped auto-loading of Documentation/AGENTS.md when editing RST files under that directory. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Upgrade league/flysystem from abandoned v1 (EOL since 2022) to v3. The upstream
phpdocumentor/guidesalready supports flysystem v3 via itsFileSysteminterface shim.Dependency changes
league/flysystem:^1.1.10→^3.29(resolved: 3.32.0)league/flysystem-local: new transitive dependency (3.31.0)phpdocumentor/flyfinder: 1.1.0 → 2.0.0 (flysystem v3 compatible)Code changes
CopyResources.phpAdapter\Local→LocalFilesystemAdapter,FilesystemExceptiontry/catch/finally for bothreadStream()andputStream()with proper stream cleanupTwigExtension.phpLeague\Flysystem\Exception→League\Flysystem\FilesystemExceptionIncludeDirective.php@throws FileNotFoundExceptiondocblocks (class removed in v3)SiteSetSettingsDirective.php@throws FileNotFoundExceptiondocblockError handling
In v3,
readStream()throwsUnableToReadFileandwriteStream()throwsUnableToWriteFileinstead of returning false. Atry/catch(FilesystemException)block wraps both read and write operations with afinallyclause to ensurefclose()on the stream. Individual file failures are logged and skipped — a single unreadable/unwritable file will not abort the entire resource copy loop.Compatibility
The phpdocumentor
FileSysteminterface shim (phpdocumentor/filesystem) provides backward compatibility. TheFilesystemInterfaceunion type inIncludeDirectiveis preserved since the shim provides a polyfill for the v1 interface.Test plan