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 // TODO: Once UploadBase starts using this, switch to use these constants rather than UploadBase::SESSION*
28 // const SESSION_VERSION = 2;
29 // const SESSION_KEYNAME = 'wsUploadData';
32 * Represents the session which contains temporarily stored files.
33 * Designed to be compatible with the session stashing code in UploadBase (should replace it eventually)
35 * @param $repo FileRepo: optional -- repo in which to store files. Will choose LocalRepo if not supplied.
37 public function __construct( $repo = null ) {
39 if ( is_null( $repo ) ) {
40 $repo = RepoGroup
::singleton()->getLocalRepo();
45 if ( ! isset( $_SESSION ) ) {
46 throw new UploadStashNotAvailableException( 'no session variable' );
49 if ( !isset( $_SESSION[UploadBase
::SESSION_KEYNAME
] ) ) {
50 $_SESSION[UploadBase
::SESSION_KEYNAME
] = array();
56 * Get a file and its metadata from the stash.
57 * May throw exception if session data cannot be parsed due to schema change, or key not found.
59 * @param $key Integer: key
60 * @throws UploadStashFileNotFoundException
61 * @throws UploadStashBadVersionException
62 * @return UploadStashFile
64 public function getFile( $key ) {
65 if ( ! preg_match( self
::KEY_FORMAT_REGEX
, $key ) ) {
66 throw new UploadStashBadPathException( "key '$key' is not in a proper format" );
69 if ( !isset( $this->files
[$key] ) ) {
70 if ( !isset( $_SESSION[UploadBase
::SESSION_KEYNAME
][$key] ) ) {
71 throw new UploadStashFileNotFoundException( "key '$key' not found in stash" );
74 $data = $_SESSION[UploadBase
::SESSION_KEYNAME
][$key];
75 // guards against PHP class changing while session data doesn't
76 if ($data['version'] !== UploadBase
::SESSION_VERSION
) {
77 throw new UploadStashBadVersionException( $data['version'] . " does not match current version " . UploadBase
::SESSION_VERSION
);
80 // separate the stashData into the path, and then the rest of the data
81 $path = $data['mTempPath'];
82 unset( $data['mTempPath'] );
84 $file = new UploadStashFile( $this, $this->repo
, $path, $key, $data );
86 $this->files
[$key] = $file;
89 return $this->files
[$key];
93 * Stash a file in a temp directory and record that we did this in the session, along with other metadata.
94 * We store data in a flat key-val namespace because that's how UploadBase did it. This also means we have to
95 * ensure that the key-val pairs in $data do not overwrite other required fields.
97 * @param $path String: path to file you want stashed
98 * @param $data Array: optional, other data you want associated with the file. Do not use 'mTempPath', 'mFileProps', 'mFileSize', or 'version' as keys here
99 * @param $key String: optional, unique key for this file in this session. Used for directory hashing when storing, otherwise not important
100 * @throws UploadStashBadPathException
101 * @throws UploadStashFileException
102 * @return UploadStashFile: file, or null on failure
104 public function stashFile( $path, $data = array(), $key = null ) {
105 if ( ! file_exists( $path ) ) {
106 wfDebug( "UploadStash: tried to stash file at '$path', but it doesn't exist\n" );
107 throw new UploadStashBadPathException( "path doesn't exist" );
109 $fileProps = File
::getPropsFromPath( $path );
111 // If no key was supplied, use content hash. Also has the nice property of collapsing multiple identical files
112 // uploaded this session, which could happen if uploads had failed.
113 if ( is_null( $key ) ) {
114 $key = $fileProps['sha1'];
117 if ( ! preg_match( self
::KEY_FORMAT_REGEX
, $key ) ) {
118 throw new UploadStashBadPathException( "key '$key' is not in a proper format" );
121 // if not already in a temporary area, put it there
122 $status = $this->repo
->storeTemp( basename( $path ), $path );
123 if( ! $status->isOK() ) {
124 // It is a convention in MediaWiki to only return one error per API exception, even if multiple errors
125 // are available. We use reset() to pick the "first" thing that was wrong, preferring errors to warnings.
126 // 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
127 // redesigning API errors significantly.
128 // $status->value just contains the virtual URL (if anything) which is probably useless to the caller
129 $error = reset( $status->getErrorsArray() );
130 if ( ! count( $error ) ) {
131 $error = reset( $status->getWarningsArray() );
132 if ( ! count( $error ) ) {
133 $error = array( 'unknown', 'no error recorded' );
136 throw new UploadStashFileException( "error storing file in '$path': " . implode( '; ', $error ) );
138 $stashPath = $status->value
;
140 // required info we always store. Must trump any other application info in $data
141 // 'mTempPath', 'mFileSize', and 'mFileProps' are arbitrary names
142 // chosen for compatibility with UploadBase's way of doing this.
143 $requiredData = array(
144 'mTempPath' => $stashPath,
145 'mFileSize' => $fileProps['size'],
146 'mFileProps' => $fileProps,
147 'version' => UploadBase
::SESSION_VERSION
150 // now, merge required info and extra data into the session. (The extra data changes from application to application.
151 // UploadWizard wants different things than say FirefoggChunkedUpload.)
152 $_SESSION[UploadBase
::SESSION_KEYNAME
][$key] = array_merge( $data, $requiredData );
154 return $this->getFile( $key );
159 class UploadStashFile
extends UnregisteredLocalFile
{
160 private $sessionStash;
162 private $sessionData;
166 * A LocalFile wrapper around a file that has been temporarily stashed, so we can do things like create thumbnails for it
167 * Arguably UnregisteredLocalFile should be handling its own file repo but that class is a bit retarded currently
169 * @param $stash UploadStash: useful for obtaining config, stashing transformed files
170 * @param $repo FileRepo: repository where we should find the path
171 * @param $path String: path to file
172 * @param $key String: key to store the path and any stashed data under
173 * @param $data String: any other data we want stored with this file
174 * @throws UploadStashBadPathException
175 * @throws UploadStashFileNotFoundException
177 public function __construct( $stash, $repo, $path, $key, $data ) {
178 $this->sessionStash
= $stash;
179 $this->sessionKey
= $key;
180 $this->sessionData
= $data;
182 // resolve mwrepo:// urls
183 if ( $repo->isVirtualUrl( $path ) ) {
184 $path = $repo->resolveVirtualUrl( $path );
187 // check if path appears to be sane, no parent traversals, and is in this repo's temp zone.
188 $repoTempPath = $repo->getZonePath( 'temp' );
189 if ( ( ! $repo->validateFilename( $path ) ) ||
190 ( strpos( $path, $repoTempPath ) !== 0 ) ) {
191 wfDebug( "UploadStash: tried to construct an UploadStashFile from a file that should already exist at '$path', but path is not valid\n" );
192 throw new UploadStashBadPathException( 'path is not valid' );
195 // check if path exists! and is a plain file.
196 if ( ! $repo->fileExists( $path, FileRepo
::FILES_ONLY
) ) {
197 wfDebug( "UploadStash: tried to construct an UploadStashFile from a file that should already exist at '$path', but path is not found\n" );
198 throw new UploadStashFileNotFoundException( 'cannot find path, or not a plain file' );
201 parent
::__construct( false, $repo, $path, false );
203 // we will be initializing from some tmpnam files that don't have extensions.
204 // most of MediaWiki assumes all uploaded files have good extensions. So, we fix this.
205 $this->name
= basename( $this->path
);
206 $this->setExtension();
211 * A method needed by the file transforming and scaling routines in File.php
212 * We do not necessarily care about doing the description at this point
213 * However, we also can't return the empty string, as the rest of MediaWiki demands this (and calls to imagemagick
214 * convert require it to be there)
216 * @return String: dummy value
218 public function getDescriptionUrl() {
219 return $this->getUrl();
223 * Find or guess extension -- ensuring that our extension matches our mime type.
224 * Since these files are constructed from php tempnames they may not start off
226 * This does not override getExtension() because things like getMimeType() already call getExtension(),
227 * and that results in infinite recursion. So, we preemptively *set* the extension so getExtension() can find it.
228 * For obvious reasons this should be called as early as possible, as part of initialization
230 public function setExtension() {
231 // Does this have an extension?
232 $n = strrpos( $this->path
, '.' );
234 if ( $n !== false ) {
235 $extension = $n ?
substr( $this->path
, $n +
1 ) : '';
237 // If not, assume that it should be related to the mime type of the original file.
239 // This entire thing is backwards -- we *should* just create an extension based on
240 // the mime type of the transformed file, *after* transformation. But File.php demands
241 // to know the name of the transformed file before creating it.
242 $mimeType = $this->getMimeType();
243 $extensions = explode( ' ', MimeMagic
::singleton()->getExtensionsForType( $mimeType ) );
244 if ( count( $extensions ) ) {
245 $extension = $extensions[0];
249 if ( is_null( $extension ) ) {
250 throw new UploadStashFileException( "extension is null" );
253 $this->extension
= parent
::normalizeExtension( $extension );
257 * Get the path for the thumbnail (actually any transformation of this file)
258 * The actual argument is the result of thumbName although we seem to have
259 * buggy code elsewhere that expects a boolean 'suffix'
261 * @param $thumbName String: name of thumbnail (e.g. "120px-123456.jpg" ), or false to just get the path
262 * @return String: path thumbnail should take on filesystem, or containing directory if thumbname is false
264 public function getThumbPath( $thumbName = false ) {
265 $path = dirname( $this->path
);
266 if ( $thumbName !== false ) {
267 $path .= "/$thumbName";
273 * Return the file/url base name of a thumbnail with the specified parameters
275 * @param $params Array: handler-specific parameters
276 * @return String: base name for URL, like '120px-12345.jpg', or null if there is no handler
278 function thumbName( $params ) {
279 if ( !$this->getHandler() ) {
282 $extension = $this->getExtension();
283 list( $thumbExt, $thumbMime ) = $this->handler
->getThumbType( $extension, $this->getMimeType(), $params );
284 $thumbName = $this->getHandler()->makeParamString( $params ) . '-' . $this->getUrlName();
285 if ( $thumbExt != $extension ) {
286 $thumbName .= ".$thumbExt";
292 * Helper function -- given a 'subpage', return the local URL e.g. /wiki/Special:UploadStash/subpage
293 * @param {String} $subPage
294 * @return {String} local URL for this subpage in the Special:UploadStash space.
296 private function getSpecialUrl( $subPage ) {
297 return SpecialPage
::getTitleFor( 'UploadStash', $subPage )->getLocalURL();
302 * Get a URL to access the thumbnail
303 * This is required because the model of how files work requires that
304 * the thumbnail urls be predictable. However, in our model the URL is not based on the filename
305 * (that's hidden in the session)
307 * @param $thumbName String: basename of thumbnail file -- however, we don't want to use the file exactly
308 * @return String: URL to access thumbnail, or URL with partial path
310 public function getThumbUrl( $thumbName = false ) {
311 return self
::getSpecialUrl( $thumbName );
315 * The basename for the URL, which we want to not be related to the filename.
316 * Will also be used as the lookup key for a thumbnail file.
318 * @return String: base url name, like '120px-123456.jpg'
320 public function getUrlName() {
321 if ( ! $this->urlName
) {
322 $this->urlName
= $this->sessionKey
. '.' . $this->getExtension();
324 return $this->urlName
;
328 * Return the URL of the file, if for some reason we wanted to download it
329 * We tend not to do this for the original file, but we do want thumb icons
331 * @return String: url
333 public function getUrl() {
334 if ( !isset( $this->url
) ) {
335 $this->url
= self
::getSpecialUrl( $this->getUrlName() );
341 * Parent classes use this method, for no obvious reason, to return the path (relative to wiki root, I assume).
342 * But with this class, the URL is unrelated to the path.
344 * @return String: url
346 public function getFullUrl() {
347 return $this->getUrl();
352 * Getter for session key (the session-unique id by which this file's location & metadata is stored in the session)
354 * @return String: session key
356 public function getSessionKey() {
357 return $this->sessionKey
;
361 * Typically, transform() returns a ThumbnailImage, which you can think of as being the exact
362 * equivalent of an HTML thumbnail on Wikipedia. So its URL is the full-size file, not the thumbnail's URL.
364 * Here we override transform() to stash the thumbnail file, and then
365 * provide a way to get at the stashed thumbnail file to extract properties such as its URL
367 * @param $params Array: parameters suitable for File::transform()
368 * @param $flags Integer: bitmask, flags suitable for File::transform()
369 * @return ThumbnailImage: with additional File thumbnailFile property
371 public function transform( $params, $flags = 0 ) {
373 // force it to get a thumbnail right away
374 $flags |
= self
::RENDER_NOW
;
376 // returns a ThumbnailImage object containing the url and path. Note. NOT A FILE OBJECT.
377 $thumb = parent
::transform( $params, $flags );
378 wfDebug( "UploadStash: generating thumbnail\n" );
379 wfDebug( print_r( $thumb, 1 ) );
380 $key = $this->thumbName($params);
382 // remove extension, so it's stored in the session under '120px-123456'
383 // this makes it uniform with the other session key for the original, '123456'
384 $n = strrpos( $key, '.' );
385 if ( $n !== false ) {
386 $key = substr( $key, 0, $n );
389 // stash the thumbnail File, and provide our caller with a way to get at its properties
390 $stashedThumbFile = $this->sessionStash
->stashFile( $thumb->getPath(), array(), $key );
391 $thumb->thumbnailFile
= $stashedThumbFile;
398 * Remove the associated temporary file
399 * @return Status: success
401 public function remove() {
402 return $this->repo
->freeTemp( $this->path
);
407 class UploadStashNotAvailableException
extends MWException
{};
408 class UploadStashFileNotFoundException
extends MWException
{};
409 class UploadStashBadPathException
extends MWException
{};
410 class UploadStashBadVersionException
extends MWException
{};
411 class UploadStashFileException
extends MWException
{};