Safe Writer Laravel Package

Getting Started

Install via Composer: composer require webimpress/safe-writer. This package provides a single main class, Webimpress\SafeWriter\Writer, which safely writes content to files by first writing to a temporary file and then atomic-rename (via rename()), eliminating partial writes and race conditions. Start by using the static method Writer::writeFile($filePath, $content). For common use cases like config caching or log file rotation, this is plug-and-play — no configuration needed beyond ensuring the target directory is writable.

Implementation Patterns

• Configuration generation: Safely overwrite PHP config arrays (e.g., config.php) in production without risking partial reads during deployment or concurrent deploys.
• Atomic file updates: Replace entire files (e.g., sitemap.xml, cache files, static site assets) atomically — useful in CI pipelines or worker processes.
• Error handling via exceptions: Wrap writeFile() in try-catch to gracefully handle permission or I/O failures; the method throws Webimpress\SafeWriter\Exception\IOException on failure.
• Custom temp path: Use Writer::writeFile($path, $content, $tempDir) when the temp file must reside on the same filesystem as the target (e.g., across NFS or docker volumes).
• Integration with frameworks: Drop into Laravel’s Storage disk extension or custom Laravel commands (e.g., php artisan cache:generate) to avoid partial cache writes.

Gotchas and Tips

• Same filesystem requirement: rename() only works atomically if temp and target paths share the same filesystem mount — if not, race conditions may reappear. Use the optional $tempDir argument to enforce this.
• No file locking: The package does not implement advisory locking — it’s for atomic replacement, not concurrent modification. Pair with OS-level locking (flock()) if multiple processes write to the same file simultaneously.
• File permissions: On Unix systems, the new file inherits umask-based permissions — not the original file’s. Use chmod($filePath, $mode) after writing if strict permission control is needed.
• No directory creation: Fails if the target directory doesn’t exist. Pre-validate or create the path before calling writeFile().
• Silent truncation on symlink: Avoid writing to symlinks directly — rename() will overwrite the link target, not the link itself — but verify with is_link() if relevant to your use case.
• Consider alternatives for large files: For files >100MB, memory usage may be high since $content must be held in full — consider streaming via tempnam() + stream_copy_to_stream() instead.