NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #3118 most downloaded on Packagist
Non-blocking access to the filesystem based on Amp and Revolt.
Latest stable
v4.0.0
Last release 6 months ago
09 May 2026
Release timing varies
gaps range from 1 weeks to 1.3 years
Most releases are documented
notes for 25 of 30 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
37 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
Users of 3.x should be able to update to 4.x without code changes unless their application did one of the following:
Users of 3.x should be able to update to 4.x without code changes unless their application did one of the following:
File implementationParallelFilesystemDriver with a custom worker count.This release adds a lock(), tryLock(), and unlock() to the File interface. These methods provide a non-blocking means of locking and unlocking a file.
File::lock(): Non-blocking method to obtain a shared or exclusive lock on the file. This method must only return once the lock has been obtained.File::tryLock(): Makes a single non-blocking attempt to obtain a shared or exclusive lock on the file. Returns true if the lock was obtained, otherwise false.File::unlock(): Unlocks the file if the lock is currently held.In 3.x, the constructor of ParallelFilesystemDriver accepted an optional WorkerPool and a number of workers to use from that pool. In 4.x, instead the constructor now requires only an optional LimitedWorkerPool (a new pool is created if one is not provided). The number of workers used for opening files is determined by the value returned from LimitedWorkerPool::getWorkerLimit(). Use a DelegateWorkerPool if you wish to use an existing pool and limit the number of workers used from the pool to open files. In general, it is not necessary to customize the parallel filesystem driver.
Full Changelog: https://github.com/amphp/file/compare/v3.2.0...v4.0.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Users of 3.x should be able to update to 4.x without code changes unless their application did one of the following:
Users of 3.x should be able to update to 4.x without code changes unless their application did one of the following:
File implementationParallelFilesystemDriver with a custom worker count.This release adds a lock(), tryLock(), and unlock() to the File interface. These methods provide a non-blocking means of locking and unlocking a file.
File::lock(): Non-blocking method to obtain a shared or exclusive lock on the file. This method must only return once the lock has been obtained.File::tryLock(): Makes a single non-blocking attempt to obtain a shared or exclusive lock on the file. Returns true if the lock was obtained, otherwise false.File::unlock(): Unlocks the file if the lock is currently held.In 3.x, the constructor of ParallelFilesystemDriver accepted an optional WorkerPool and a number of workers to use from that pool. In 4.x, instead the constructor now requires only an optional LimitedWorkerPool (a new pool is created if one is not provided). The number of workers used for opening files is determined by the value returned from LimitedWorkerPool::getWorkerLimit(). Use a DelegateWorkerPool if you wish to use an existing pool and limit the number of workers used from the pool to open files. In general, it is not necessary to customize the parallel filesystem driver.
Full Changelog: https://github.com/amphp/file/compare/v3.2.0...v4.0.0-beta.1
The $workerLimit parameter to the constructor of ParallelFilesystemDriver is now deprecated. Pass an instance of LimitedWorkerPool instead.
$workerLimit parameter to the constructor of ParallelFilesystemDriver is now deprecated. Pass an instance of LimitedWorkerPool instead.Full Changelog: https://github.com/amphp/file/compare/v3.1.1...v3.2.0
$workerLimit parameter to the constructor of ParallelFilesystemDriver is now deprecated. Pass an instance of LimitedWorkerPool instead.Full Changelog: v3.1.1...v3.2.0
Dropped support for ext-uv < 0.3.0.
Full Changelog: https://github.com/amphp/file/compare/v3.1.0...v3.1.1
Full Changelog: v3.1.0...v3.1.1
Made implicit nullable types explicit to avoid deprecation notice in PHP 8.4
FileCache class by @Nadyita in https://github.com/amphp/file/pull/83KeyedFileMutex by @bwoebi in https://github.com/amphp/file/pull/62Full Changelog: https://github.com/amphp/file/compare/v3.0.2...v3.1.0
FileCache class by @Nadyita in #83KeyedFileMutex by @bwoebi in #62Full Changelog: v3.0.2...v3.1.0
Fixed detecting if a file is writing from the file mode when r+ (or similar) is used as the mode.
r+ (or similar) is used as the mode. (#77)ParallelFilesystemDriver. (#81)Full Changelog: https://github.com/amphp/file/compare/v3.0.1...v3.0.2
r+ (or similar) is used as the mode. (#77)ParallelFilesystemDriver. (#81)Full Changelog: v3.0.1...v3.0.2
Fix touch() on non-existent files in ext-uv and ext-eio by @kelunik
touch() on non-existent files in ext-uv and ext-eio by @kelunik (#73)write() truncation with ext-uv and ext-eio by @danog in (#76)Full Changelog: https://github.com/amphp/file/compare/v3.0.0...v3.0.1
touch() on non-existent files in ext-uv and ext-eio by @kelunik (#73)write() truncation with ext-uv and ext-eio by @danog in (#76)Full Changelog: v3.0.0...v3.0.1
Stable release compatible with AMPHP v3 and fibers! 🎉
Stable release compatible with AMPHP v3 and fibers! 🎉
As with other libraries compatible with AMPHP v3, most cases of parameters or returns of Promise<ResolutionType> have been replaced with ResolutionType.
BlockingDriver to BlockingFilesystemDriverEioDriver to EioFilesystemDriverParallelDriver to ParallelFilesystemDriverStatusCachingDriver to StatusCachingFilesystemDriverUvDriver to UvFilesystemDriverAmp\File\Sync\AsyncFileMutex to Amp\File\FileMutex?Cancellation as first parameter of File::read()File::isSeekable()File::SEEK_SET, File::SEEK_CUR, and File::SEEK_ENDAmp\File\Whence for seeking insteadv2.0 of amphp/byte-stream by updating File implementations to also implement Traversable.PendingOperationError being thrown after several seek-then-write operations in UvFile and EioFile.Fixed compatibility with v2.0 of amphp/byte-stream by updating File implementations to also implement Traversable.
v2.0 of amphp/byte-stream by updating File implementations to also implement Traversable.Fixed PendingOperationError being thrown after several seek-then-write operations in UvFile and EioFile.
PendingOperationError being thrown after several seek-then-write operations in UvFile and EioFile.Added compatibility with Revolt v1.x
ext-eioext-uvBlockingFilesystemDriver::writeFix createDirectoryRecursively with trailing slash with ext-uv / ext-eio
createDirectoryRecursively with trailing slash with ext-uv / ext-eio (https://github.com/amphp/file/issues/70, https://github.com/amphp/file/pull/71)Update for Closable interface adding an onClose. All File objects now include an onClose method which can be used to attache a closure which will be i
Closable interface adding an onClose. All File objects now include an onClose method which can be used to attache a closure which will be invoked when the file is closed.Support AMPHP v3 and fibers, removing the need for promises for return values
File::write() return type from Promise<int> to voidDriver to FilesystemDriverAmp\File\Sync\AsyncMutex to Amp\File\FileMutexFix createDirectoryRecursively with trailing slash in async drivers
createDirectoryRecursively with trailing slash in async drivers (https://github.com/amphp/file/issues/70, https://github.com/amphp/file/pull/71)Return written length in blocking and parallel drivers (https://github.com/amphp/file/pull/64) This makes BlockingFile and ParallelFile consistent wit
BlockingFile and ParallelFile consistent with the other drivers and the documented return type. However, it's recommended to avoid relying on this return value, as these method will return void in the next major version.- Fix compatibility with ext-eio
Fixed deprecation warning on PHP 8.1
Improved driver consistency and reduced its API
AsyncFileMutex (#43)isSymlink$uid and $gid accept null instead of -1 to ignore now)Huge thanks to @enumag for this release!
Fixed compatibility with ext-uv@0.2.x
ext-uv@0.2.x (#46)Improved error messages when using the blocking driver or parallel driver
ext-uv@0.3.0link() function, previously was creating a symlink instead of a hard link (#37)EIO_O_FSYNC if undefined (#42)Handle has been deprecated in favor of File, which extends Handle for backward compatibility. Uses of Handle should be updated to File. Thus, the prom…
This release is, in most cases, backward compatible with v0.3.x if this library was only used for async file access.
Uses of Amp\File\Handle should be replaced with Amp\File\File, as Amp\File\Handle will be removed in a future major release.
Please review the changes below to determine if further changes are needed for your code.
Handle has been deprecated in favor of File, which extends Handle for backward compatibility. Uses of Handle should be updated to File. Thus, the promise returned from Driver::open() should resolve with an instance of File.BlockingHandle, EioHandle, ParallelHandle, and UvHandle have been renamed respectively to BlockingFile, EioFile, ParallelFile, and UvFile.FilesystemException, are now declared final.Amp\File\driver() has been renamed to Amp\File\createDefaultDriver().File adds a truncate() method to resize the file to a given length.Fixed an error calculating file length when writing to files with the UV extension if the file was opened in append mode.
Accidental tag on master when v0.3.x branch should have been tagged. Ignore this release.
Accidental tag on master when v0.3.x branch should have been tagged. Ignore this release.
Fixed stat result when using UvDriver
stat result when using UvDriver (#29)readlink implementation when using EioDriver or UvDriver (#30)scandir when reading an empty directory when using UvDriver (#23)scandir are now alphabetically sorted when using EioDriver (now matches results from other drivers).isSupported() method to EioDriver and UvDriver, returning a bool determining if the driver can be used.Updated to `amphp/parallel` `v1.0`.
Updated to amphp/parallel v1.0.
Fixed default permissions for mkdir(). These previously were 0644, which doesn't really make sense, because it doesn't allow listing. New default is 0
mkdir(). These previously were 0644, which doesn't really make sense, because it doesn't allow listing. New default is 0777 like PHP's default, which will usually result in 0755 with the umask.Added optional parameters $time and $atime to Amp\File\touch() and Driver::touch() (#22) This is only a breaking change if you implement the Driver in…
ParallelDriver if ext-eio and ext-uv are not installed.ParallelDriver'e' flag is automatically used when opening files (#20)$time and $atime to Amp\File\touch() and Driver::touch() (#22)<br>This is only a breaking change if you implement the Driver interface yourself.Use BlockingDriver for SAPIs other than cli and phpdbg.
BlockingDriver for SAPIs other than cli and phpdbg.Workers created by the amphp/parallel package will not use ParallelDriver to avoid launching another worker from within a worker. BlockingDriver is us
amphp/parallel package will not use ParallelDriver to avoid launching another worker from within a worker. BlockingDriver is used if eio or uv is not available.StatCache is now used in ParallelDriver in the same way as EioDriver and UvDriver.The ParallelHandle::seek() function now doesn't set the handle to busy, similarly to the other handle implementations.
ParallelHandle::seek() function now doesn't set the handle to busy, similarly to the other handle implementations.Windows now uses BlockingDriver by default if EIO or UV is not available. Previously ParallelDriver was used, but amphp/parallel and amphp/process do
BlockingDriver by default if EIO or UV is not available. Previously ParallelDriver was used, but amphp/parallel and amphp/process do not play nice on Windows (at least for now).Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.