webware / webware-filewriter
Atomic file writer and directory-tree writer for the Webware ecosystem
Package info
github.com/webinertia/webware-filewriter
Language:PowerShell
pkg:composer/webware/webware-filewriter
Requires
- php: ~8.4.1 || ~8.5.0
- php-standard-library/file: ^6.4.2
- php-standard-library/filesystem: ^6.4.2
Requires (Dev)
- infection/infection: ^0.35.0
- phpbench/phpbench: ^1.7
- phpunit/phpunit: ^13.4.4
- roave/backward-compatibility-check: ^8.21.0
- roave/security-advisories: dev-master
- webware/webware-tools: ^1.0.0-rc.8
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 02:01:26 UTC
README
Writes files atomically, and optionally writes a tree of them.
A file is never written in place. The content is written to an exclusive temporary file beside the destination, given the destination's mode, owner and group, and then renamed onto it. A reader therefore sees either the previous document or the new one, and an interrupted write never leaves a truncated file behind.
Installation
composer require webware/webware-filewriter
Usage
Writing a single file
use Webware\FileWriter\FileWriter; FileWriter::write('/srv/app/config/autoload/local.php', $content);
write() requires the containing directory to exist. A wrong path fails rather than having a
directory invented for it, which is the right default for a single file whose location is meant to be
exact.
Writing a tree
FileWriter::writeTree('/srv/build/site/guide/intro/index.html', $html);
writeTree() creates the directories leading to the file first, then writes it the same way. Use it
when generating output, where every target below the first level is missing by construction.
foreach ($pages as $relativePath => $html) { FileWriter::writeTree("{$output}/{$relativePath}", $html); }
Naming the mode
Both methods take an optional mode. It matters when the output is served rather than read by the deployer, because the derived mode is a function of the environment:
- a new file gets
0o666narrowed by umask - an existing file keeps the mode it already has, forever
So a published page that replaces a file created 0o600 stays unreadable by the web server on every
future write, and a build host with a 0o077 umask silently makes every asset private.
FileWriter::write( filename: '/srv/site/index.html', content : $html, mode : 0o644, ); FileWriter::writeTree( filename : '/srv/build/site/guide/intro/index.html', content : $html, mode : 0o644, directoryMode: 0o755, );
An explicit mode wins over both the destination's current bits and the process umask, and is applied
to the temporary file before the rename, so the destination never exists with any other mode. The
directory mode is applied after mkdir() because that call is always masked by umask. Both are
accepted but have no effect on Windows, which does not model POSIX permissions.
Omitting them keeps the derived behaviour described above.
Symbolic links
A symlinked destination is resolved, and the write lands on the target, so the link survives. This
matters for release-directory deployments, where config/app.php is a link into shared/:
replacing the link would appear to succeed while every release kept reading the previous content.
A link whose target does not exist is reported instead of replaced, because there is nothing to follow and guessing where the file belongs is worse than saying so.
Behaviour worth knowing
| Situation | Behaviour |
|---|---|
| Existing destination | mode, owner and group carried over to the new file |
| New destination | mode 0666 narrowed by the process umask |
Explicit $mode |
applied verbatim, over both the destination's bits and umask |
Explicit $directoryMode |
applied after mkdir(), since that call is masked by umask |
| Windows | no mode or ownership adoption; chmod there only toggles the read-only attribute, and a read-only file cannot be renamed over |
| Unprivileged PHP process | mode preserved, ownership keeps the PHP user, since chown needs privilege |
| Destination is a directory | fails with Exception\RuntimeException |
| Empty file name | fails with Exception\InvalidArgumentException |
| Temporary file on failure | removed before the exception is thrown |
Owner and group adoption is best effort: a refused change does not fail the write. A host that runs PHP as a different user than the file's owner therefore needs its ownership corrected outside the application.
Documentation
- Introduction: the write sequence, symbolic links, and every error case.
- Modes and ownership: derived versus explicit modes, umask, directory modes, and what happens on Windows.
- Writing a tree: the generator case, its cost, and what it does not guarantee.
Quality gates
Both MSI gates are set to 98, matching the sibling packages, and must not be lowered silently:
"min_msi": "98", "min_covered_msi": "98"
Four Mago gates run in CI and must be clean: format --check, lint, analyze, guard.
Development
The toolchain runs in a container, so the host needs no PHP install:
docker compose up -d docker compose exec tooling composer install docker compose exec tooling composer test docker compose exec tooling composer test-integration docker compose exec tooling mago lint docker compose down