3 * UploadStash is intended to accomplish a few things:
4 * - enable applications to temporarily stash files without publishing them to the wiki.
5 * - Several parts of MediaWiki do this in similar ways: UploadBase, UploadWizard, and FirefoggChunkedExtension
6 * And there are several that reimplement stashing from scratch, in idiosyncratic ways. The idea is to unify them all here.
7 * Mostly all of them are the same except for storing some custom fields, which we subsume into the data array.
8 * - enable applications to find said files later, as long as the session or temp files haven't been purged.
9 * - enable the uploading user (and *ONLY* the uploading user) to access said files, and thumbnails of said files, via a URL.
10 * We accomplish this by making the session serve as a URL->file mapping, on the assumption that nobody else can access
11 * the session, even the uploading user. See SpecialUploadStash, which implements a web interface to some files stored this way.
15 // Format of the key for files -- has to be suitable as a filename itself in some cases.
16 // This should encompass a sha1 content hash in hex (new style), or an integer (old style),
17 // and also thumbnails with prepended strings like "120px-".
18 // The file extension should not be part of the key.
19 const KEY_FORMAT_REGEX
= '/^[\w-]+$/';
21 // repository that this uses to store temp files
24 // array of initialized objects obtained from session (lazily initialized upon getFile())
25 private $files = array();
27 // the base URL for files in the stash
30 // TODO: Once UploadBase starts using this, switch to use these constants rather than UploadBase::SESSION*
31 // const SESSION_VERSION = 2;
32 // const SESSION_KEYNAME = 'wsUploadData';
35 * Represents the session which contains temporarily stored files.
36 * Designed to be compatible with the session stashing code in UploadBase (should replace it eventually)
37 * @param {FileRepo} $repo: optional -- repo in which to store files. Will choose LocalRepo if not supplied.
39 public function __construct( $repo = null ) {
41 if ( is_null( $repo ) ) {
42 $repo = RepoGroup
::singleton()->getLocalRepo();
47 if ( ! isset( $_SESSION ) ) {
48 throw new UploadStashNotAvailableException( 'no session variable' );
51 if ( !isset( $_SESSION[UploadBase
::SESSION_KEYNAME
] ) ) {
52 $_SESSION[UploadBase
::SESSION_KEYNAME
] = array();
55 $this->baseUrl
= SpecialPage
::getTitleFor( 'UploadStash' )->getLocalURL();
59 * Get the base of URLs by which one can access the files
60 * @return {String} url
62 public function getBaseUrl() {
63 return $this->baseUrl
;
67 * Get a file and its metadata from the stash.
68 * May throw exception if session data cannot be parsed due to schema change, or key not found.
69 * @param {Integer} $key: key
70 * @throws UploadStashFileNotFoundException
71 * @throws UploadStashBadVersionException
72 * @return {UploadStashItem} null if no such item or item out of date, or the item
74 public function getFile( $key ) {
75 if ( ! preg_match( self
::KEY_FORMAT_REGEX
, $key ) ) {
76 throw new UploadStashBadPathException( "key '$key' is not in a proper format" );
79 if ( !isset( $this->files
[$key] ) ) {
80 if ( !isset( $_SESSION[UploadBase
::SESSION_KEYNAME
][$key] ) ) {
81 throw new UploadStashFileNotFoundException( "key '$key' not found in session" );
84 $data = $_SESSION[UploadBase
::SESSION_KEYNAME
][$key];
85 // guards against PHP class changing while session data doesn't
86 if ($data['version'] !== UploadBase
::SESSION_VERSION
) {
87 throw new UploadStashBadVersionException( $data['version'] . " does not match current version " . UploadBase
::SESSION_VERSION
);
90 // separate the stashData into the path, and then the rest of the data
91 $path = $data['mTempPath'];
92 unset( $data['mTempPath'] );
94 $file = new UploadStashFile( $this, $this->repo
, $path, $key, $data );
96 $this->files
[$key] = $file;
99 return $this->files
[$key];
103 * Stash a file in a temp directory and record that we did this in the session, along with other metadata.
104 * We store data in a flat key-val namespace because that's how UploadBase did it. This also means we have to
105 * ensure that the key-val pairs in $data do not overwrite other required fields.
107 * @param {String} $path: path to file you want stashed
108 * @param {Array} $data: optional, other data you want associated with the file. Do not use 'mTempPath', 'mFileProps', 'mFileSize', or 'version' as keys here
109 * @param {String} $key: optional, unique key for this file in this session. Used for directory hashing when storing, otherwise not important
110 * @throws UploadStashBadPathException
111 * @throws UploadStashFileException
112 * @return {null|UploadStashFile} file, or null on failure
114 public function stashFile( $path, $data = array(), $key = null ) {
115 if ( ! file_exists( $path ) ) {
116 throw new UploadStashBadPathException( "path '$path' doesn't exist" );
118 $fileProps = File
::getPropsFromPath( $path );
120 // If no key was supplied, use content hash. Also has the nice property of collapsing multiple identical files
121 // uploaded this session, which could happen if uploads had failed.
122 if ( is_null( $key ) ) {
123 $key = $fileProps['sha1'];
126 if ( ! preg_match( self
::KEY_FORMAT_REGEX
, $key ) ) {
127 throw new UploadStashBadPathException( "key '$key' is not in a proper format" );
130 // if not already in a temporary area, put it there
131 $status = $this->repo
->storeTemp( basename( $path ), $path );
132 if( ! $status->isOK() ) {
133 // It is a convention in MediaWiki to only return one error per API exception, even if multiple errors
134 // are available. We use reset() to pick the "first" thing that was wrong, preferring errors to warnings.
135 // This is a bit lame, as we may have more info in the $status and we're throwing it away, but to fix it means
136 // redesigning API errors significantly.
137 // $status->value just contains the virtual URL (if anything) which is probably useless to the caller
138 $error = reset( $status->getErrorsArray() );
139 if ( ! count( $error ) ) {
140 $error = reset( $status->getWarningsArray() );
141 if ( ! count( $error ) ) {
142 $error = array( 'unknown', 'no error recorded' );
145 throw new UploadStashFileException( "error storing file in '$path': " . implode( '; ', $error ) );
147 $stashPath = $status->value
;
149 // required info we always store. Must trump any other application info in $data
150 // 'mTempPath', 'mFileSize', and 'mFileProps' are arbitrary names
151 // chosen for compatibility with UploadBase's way of doing this.
152 $requiredData = array(
153 'mTempPath' => $stashPath,
154 'mFileSize' => $fileProps['size'],
155 'mFileProps' => $fileProps,
156 'version' => UploadBase
::SESSION_VERSION
159 // now, merge required info and extra data into the session. (The extra data changes from application to application.
160 // UploadWizard wants different things than say FirefoggChunkedUpload.)
161 $_SESSION[UploadBase
::SESSION_KEYNAME
][$key] = array_merge( $data, $requiredData );
163 return $this->getFile( $key );
168 class UploadStashFile
extends UnregisteredLocalFile
{
169 private $sessionStash;
171 private $sessionData;
175 * A LocalFile wrapper around a file that has been temporarily stashed, so we can do things like create thumbnails for it
176 * Arguably UnregisteredLocalFile should be handling its own file repo but that class is a bit retarded currently
177 * @param {UploadStash} $stash: UploadStash, useful for obtaining config, stashing transformed files
178 * @param {FileRepo} $repo: repository where we should find the path
179 * @param {String} $path: path to file
180 * @param {String} $key: key to store the path and any stashed data under
181 * @param {String} $data: any other data we want stored with this file
182 * @throws UploadStashBadPathException
183 * @throws UploadStashFileNotFoundException
185 public function __construct( $stash, $repo, $path, $key, $data ) {
186 $this->sessionStash
= $stash;
187 $this->sessionKey
= $key;
188 $this->sessionData
= $data;
190 // resolve mwrepo:// urls
191 if ( $repo->isVirtualUrl( $path ) ) {
192 $path = $repo->resolveVirtualUrl( $path );
195 // check if path appears to be sane, no parent traversals, and is in this repo's temp zone.
196 $repoTempPath = $repo->getZonePath( 'temp' );
197 if ( ( ! $repo->validateFilename( $path ) ) ||
198 ( strpos( $path, $repoTempPath ) !== 0 ) ) {
199 throw new UploadStashBadPathException( "path '$path' is not valid or is not in repo temp area: '$repoTempPath'" );
202 // check if path exists! and is a plain file.
203 if ( ! $repo->fileExists( $path, FileRepo
::FILES_ONLY
) ) {
204 throw new UploadStashFileNotFoundException( "cannot find path '$path'" );
207 parent
::__construct( false, $repo, $path, false );
209 // we will be initializing from some tmpnam files that don't have extensions.
210 // most of MediaWiki assumes all uploaded files have good extensions. So, we fix this.
211 $this->name
= basename( $this->path
);
212 $this->setExtension();
217 * A method needed by the file transforming and scaling routines in File.php
218 * We do not necessarily care about doing the description at this point
219 * However, we also can't return the empty string, as the rest of MediaWiki demands this (and calls to imagemagick
220 * convert require it to be there)
221 * @return {String} dummy value
223 public function getDescriptionUrl() {
224 return $this->getUrl();
228 * Find or guess extension -- ensuring that our extension matches our mime type.
229 * Since these files are constructed from php tempnames they may not start off
231 * This does not override getExtension() because things like getMimeType() already call getExtension(),
232 * and that results in infinite recursion. So, we preemptively *set* the extension so getExtension() can find it.
233 * For obvious reasons this should be called as early as possible, as part of initialization
235 public function setExtension() {
236 // Does this have an extension?
237 $n = strrpos( $this->path
, '.' );
239 if ( $n !== false ) {
240 $extension = $n ?
substr( $this->path
, $n +
1 ) : '';
242 // If not, assume that it should be related to the mime type of the original file.
244 // This entire thing is backwards -- we *should* just create an extension based on
245 // the mime type of the transformed file, *after* transformation. But File.php demands
246 // to know the name of the transformed file before creating it.
247 $mimeType = $this->getMimeType();
248 $extensions = explode( ' ', MimeMagic
::singleton()->getExtensionsForType( $mimeType ) );
249 if ( count( $extensions ) ) {
250 $extension = $extensions[0];
254 if ( is_null( $extension ) ) {
255 throw new UploadStashFileException( "extension '$extension' is null" );
258 $this->extension
= parent
::normalizeExtension( $extension );
262 * Get the path for the thumbnail (actually any transformation of this file)
263 * The actual argument is the result of thumbName although we seem to have
264 * buggy code elsewhere that expects a boolean 'suffix'
266 * @param {String|false} $thumbName: name of thumbnail (e.g. "120px-123456.jpg" ), or false to just get the path
267 * @return {String} path thumbnail should take on filesystem, or containing directory if thumbname is false
269 public function getThumbPath( $thumbName = false ) {
270 $path = dirname( $this->path
);
271 if ( $thumbName !== false ) {
272 $path .= "/$thumbName";
278 * Return the file/url base name of a thumbnail with the specified parameters
280 * @param {Array} $params: handler-specific parameters
281 * @return {String|null} base name for URL, like '120px-12345.jpg', or null if there is no handler
283 function thumbName( $params ) {
284 if ( !$this->getHandler() ) {
287 $extension = $this->getExtension();
288 list( $thumbExt, $thumbMime ) = $this->handler
->getThumbType( $extension, $this->getMimeType(), $params );
289 $thumbName = $this->getHandler()->makeParamString( $params ) . '-' . $this->getUrlName();
290 if ( $thumbExt != $extension ) {
291 $thumbName .= ".$thumbExt";
297 * Get a URL to access the thumbnail
298 * This is required because the model of how files work requires that
299 * the thumbnail urls be predictable. However, in our model the URL is not based on the filename
300 * (that's hidden in the session)
302 * @param {String} $thumbName: basename of thumbnail file -- however, we don't want to use the file exactly
303 * @return {String} URL to access thumbnail, or URL with partial path
305 public function getThumbUrl( $thumbName = false ) {
306 $path = $this->sessionStash
->getBaseUrl();
307 if ( $thumbName !== false ) {
308 $path .= '/' . rawurlencode( $thumbName );
314 * The basename for the URL, which we want to not be related to the filename.
315 * Will also be used as the lookup key for a thumbnail file.
316 * @return {String} base url name, like '120px-123456.jpg'
318 public function getUrlName() {
319 if ( ! $this->urlName
) {
320 $this->urlName
= $this->sessionKey
. '.' . $this->getExtension();
322 return $this->urlName
;
326 * Return the URL of the file, if for some reason we wanted to download it
327 * We tend not to do this for the original file, but we do want thumb icons
328 * @return {String} url
330 public function getUrl() {
331 if ( !isset( $this->url
) ) {
332 $this->url
= $this->sessionStash
->getBaseUrl() . '/' . $this->getUrlName();
338 * Parent classes use this method, for no obvious reason, to return the path (relative to wiki root, I assume).
339 * But with this class, the URL is unrelated to the path.
341 * @return {String} url
343 public function getFullUrl() {
344 return $this->getUrl();
349 * Getter for session key (the session-unique id by which this file's location & metadata is stored in the session)
350 * @return {String} session key
352 public function getSessionKey() {
353 return $this->sessionKey
;
357 * Typically, transform() returns a ThumbnailImage, which you can think of as being the exact
358 * equivalent of an HTML thumbnail on Wikipedia. So its URL is the full-size file, not the thumbnail's URL.
360 * Here we override transform() to stash the thumbnail file, and then
361 * provide a way to get at the stashed thumbnail file to extract properties such as its URL
363 * @param {Array} $params: parameters suitable for File::transform()
364 * @param {Bitmask} $flags: flags suitable for File::transform()
365 * @return {ThumbnailImage} with additional File thumbnailFile property
367 public function transform( $params, $flags = 0 ) {
369 // force it to get a thumbnail right away
370 $flags |
= self
::RENDER_NOW
;
372 // returns a ThumbnailImage object containing the url and path. Note. NOT A FILE OBJECT.
373 $thumb = parent
::transform( $params, $flags );
374 $key = $this->thumbName($params);
376 // remove extension, so it's stored in the session under '120px-123456'
377 // this makes it uniform with the other session key for the original, '123456'
378 $n = strrpos( $key, '.' );
379 if ( $n !== false ) {
380 $key = substr( $key, 0, $n );
383 // stash the thumbnail File, and provide our caller with a way to get at its properties
384 $stashedThumbFile = $this->sessionStash
->stashFile( $thumb->getPath(), array(), $key );
385 $thumb->thumbnailFile
= $stashedThumbFile;
392 * Remove the associated temporary file
393 * @return {Status} success
395 public function remove() {
396 return $this->repo
->freeTemp( $this->path
);
401 class UploadStashNotAvailableException
extends MWException
{};
402 class UploadStashFileNotFoundException
extends MWException
{};
403 class UploadStashBadPathException
extends MWException
{};
404 class UploadStashBadVersionException
extends MWException
{};
405 class UploadStashFileException
extends MWException
{};