Upgrade from 1.x
Flysystem V1 was released on the 19th of January in 2015. Since then, it has maintained full backwards compatibility. In order to guarantee that for the years to come, some changes were needed. Some functionality needed to be standardized in order to make behavior more predictable. This meant some functionality needed to be scoped down, some “accidental” features were removed.
Upgrade your dependencies
Firstly you’ll need to upgrade Flysystem itself. You can do this by requiring
^1.0. The same needs to be done for all the adapters too, in the same action.
Filesystem::getMetadata is removed
getMetadata method is removed, in favour of better metadata getters.
Plugins are removed
The plugin functionality was a flawed concept from the start. It promoted bad practices and didn’t help in terms of predictability and the design of consuming code. With the improved guarantees of what methods do, some plugins became redundant because they augmented broken behavior in V1.
Apart from that, many cases for plugins should have just been consumer code.
||Just remove the directory, they’re always created implicitly.|
||This is no longer needed since
||This is no longer needed since
||Use specific metadata getters instead.|
||Filter on the contents listing instead.|
||Transform over the contents listing instead.|
||This operation is very unpredictable and has bad performance, don’t use it.|
basename is no longer precomputed
These values are often part of a rename that can just as well incorporate functions like
- $name = $item['basename']; + $name = basename($item->path());
Rename is now move, specific for files.
When this method was introduced, the
rename operation didn’t move files to new parent
directory. This behavior was added later. Renaming the operation
move better reflects
this behaviour. It will now also enforce that it only moves files, this is the
only way to be adapter agnostic, which is the main purpose of the library.
- $filesystem->rename($path); + $filesystem->move($path);
No arbitrary abbreviations
No need for beep-boop language (computer-speak).
- $filesystem->createDir($path); + $filesystem->createDirectory($path);
Writes are now deterministic
putStream. You can simply use
- $filesystem->update($path, $contents); + $filesystem->write($path, $contents); - $filesystem->updateStream($path, $contents); + $filesystem->writeStream($path, $contents); - $filesystem->put($path, $contents); + $filesystem->write($path, $contents); - $filesystem->putStream($path, $contents); + $filesystem->writeStream($path, $contents);
Metadata getters are renamed:
With a new major version, BC breaks are allowed. After much consideration, this was the moment to rename functions that had a sub-optimal name. Since Flysystem V2 will probably be supported as long as V1 is, breaking with past mistakes is needed sometimes.
// Explains better how to interpret the response - $lastModified = $filesystem->getTimestamp($path); + $lastModified = $filesystem->lastModified($path); // More explicit it's only for files, which is adapter agnostic. - $fileExists = $filesystem->has($path); + $fileExists = $filesystem->fileExists($path); // More explicit it's only for directories, better portability. - $directoryExists = $filesystem->has($path); + $directoryExists = $filesystem->directoryExists($path); // Correct casing. - $mimetype = $filesystem->getMimetype($path); + $mimetype = $filesystem->mimeType($path); // More explicit about what type of size - $fileSize = $filesystem->getSize($path); + $fileSize = $filesystem->fileSize($path); // In line with other metadata methods. - $visibility = $filesystem->getVisibility($path); + $visibility = $filesystem->visibility($path);
Directory listings received a big overhaul. To read more about it check out the documentation for directory listings.
- All adapters have changed constructors to allow more modular extension points.
- The cached adapter was not ported to V2.