Manual:FileBackend.php
| MediaWiki file: FileBackend.php | |
|---|---|
| Location: | includes/libs/filebackend/ |
| Source code: | master • 1.41.1 • 1.40.3 • 1.39.7 |
| Classes: | FileBackend |
FileBackend.php contains a class, FileBackend, to interact with file storage systems, such as the local file system, NFS, or cloud storage systems. This class defines the methods as abstract that subclasses must implement. Outside callers can assume that all backends will have these functions.
All "storage paths" are of the format "mwstore://<backend>/<container>/<path>". The "backend" portion is unique name for MediaWiki to refer to a backend, while the "container" portion is a top-level directory of the backend. The "path" portion is a relative path that uses UNIX file system (FS) notation, though any particular backend may not actually be using a local filesystem. Therefore, the relative paths are only virtual.
Backend contents are stored under wiki-specific container names by default. Global (qualified) backends are achieved by configuring the "wiki ID" to a constant. For legacy reasons, the FSFileBackend class allows manually setting the paths of containers to ones that do not respect the "wiki ID".
In key/value (object) stores, containers are the only hierarchy (the rest is emulated). FS-based backends are somewhat more restrictive due to the existence of real directory files; a regular file cannot have the same name as a directory. Other backends with virtual directories may not have this limitation. Callers should store files in such a way that no files and directories are under the same path.
In general, this class allows for callers to access storage through the same interface, without regard to the underlying storage system. However, calling code must follow certain patterns and be aware of certain things to ensure compatibility:
- Always call prepare() on the parent directory before trying to put a file there; key/value stores only need the container to exist first, but filesystems need all the parent directories to exist first (prepare() is aware of all this)
- Always call clean() on a directory when it might become empty to avoid empty directory buildup on filesystems; key/value stores never have empty directories, so doing this helps preserve consistency in both cases
- Likewise, do not rely on the existence of empty directories for anything; calling directoryExists() on a path that prepare() was previously called on will return false for key/value stores if there are no files under that path
- Never alter the resulting FSFile returned from getLocalReference(), as it could either be a copy of the source file in /tmp or the original source file itself
- Use a file layout that results in never attempting to store files over directories or directories over files; key/value stores allow this but filesystems do not
- Use ASCII file names (e.g. base32, IDs, hashes) to avoid Unicode issues in Windows
- Do not assume that move operations are atomic (difficult with key/value stores)
- Do not assume that file stat or read operations always have immediate consistency; various methods have a "latest" flag that should always be used if up-to-date information is required (this trades performance for correctness as needed)
- Do not assume that directory listings have immediate consistency
Child classes
FileBackendStore and FileBackendMultiWrite extend FileBackend. FileBackendStore is the base class for all backends using particular storage medium. FileBackendMultiWrite is a proxy backend that mirrors writes to several internal backends.
