help.pl - bugfix module usage (HTML::Template::Pro)
[koha.git] / C4 / UploadedFile.pm
1 package C4::UploadedFile;
2
3 # Copyright (C) 2007 LibLime
4 # Galen Charlton <galen.charlton@liblime.com>
5 #
6 # This file is part of Koha.
7 #
8 # Koha is free software; you can redistribute it and/or modify it under the
9 # terms of the GNU General Public License as published by the Free Software
10 # Foundation; either version 2 of the License, or (at your option) any later
11 # version.
12 #
13 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
14 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
15 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
16 #
17 # You should have received a copy of the GNU General Public License along with
18 # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
19 # Suite 330, Boston, MA  02111-1307 USA
20
21 use strict;
22 use C4::Context;
23 use C4::Auth qw/get_session/;
24 use IO::File;
25
26 use vars qw($VERSION);
27
28 BEGIN {
29         # set the version for version checking
30         $VERSION = 3.00;
31 }
32
33 =head1 NAME
34
35 C4::UploadedFile - manage files uploaded by the user
36 for later processing.
37
38 =head1 SYNOPSIS
39
40 =over 4
41
42 # create and store data
43 my $uploaded_file = C4::UploadedFile->new($sessionID);
44 my $fileID = $uploaded_file->id();
45 $uploaded_file->name('c:\temp\file.mrc');
46 $uploaded_file->max_size(1024);
47 while ($have_more_data) {
48     $uploaded_file->stash($data, $bytes_read);
49 }
50 $uploaded_file->done();
51
52 # check status of current file upload
53 my $progress = C4::UploadedFile->upload_progress($sessionID);
54
55 # get file handle for reading uploaded file
56 my $uploaded_file = C4::UploadedFile->fetch($fileID);
57 my $fh = $uploaded_file->fh();
58
59 =back
60
61 Stores files uploaded by the user from their web browser.  The
62 uploaded files are temporary and at present are not guaranteed
63 to survive beyond the life of the user's session.
64
65 This module allows for tracking the progress of the file
66 currently being uploaded.
67
68 TODO: implement secure persistant storage of uploaded files.
69
70 =cut
71
72 =head1 METHODS
73
74 =cut
75
76 =head2 new
77
78 =over 4
79
80 my $uploaded_file = C4::UploadedFile->new($sessionID);
81
82 =back
83
84 Creates a new object to represent the uploaded file.  Requires
85 the current session ID.
86
87 =cut
88
89 sub new {
90     my $class = shift;
91     my $sessionID = shift;
92
93     my $self = {};
94
95     $self->{'sessionID'} = $sessionID;
96     $self->{'fileID'} = Digest::MD5::md5_hex(Digest::MD5::md5_hex(time().{}.rand().{}.$$));
97     # FIXME - make staging area configurable
98     my $TEMPROOT = "/tmp";
99     my $OUTPUTDIR = "$TEMPROOT/$sessionID";
100     mkdir $OUTPUTDIR;
101     my $tmp_file_name = "$OUTPUTDIR/$self->{'fileID'}";
102     my $fh = new IO::File $tmp_file_name, "w";
103     unless (defined $fh) {
104         return undef;
105     }
106     $fh->binmode(); # Windows compatibility
107     $self->{'fh'} = $fh;
108     $self->{'tmp_file_name'} = $tmp_file_name;
109     $self->{'max_size'} = 0;
110     $self->{'progress'} = 0;
111     $self->{'name'} = '';
112
113     bless $self, $class;
114     $self->_serialize();
115
116     my $session = get_session($sessionID);
117     $session->param('current_upload', $self->{'fileID'});
118     $session->flush();
119
120     return $self;
121
122 }
123
124 sub _serialize {
125     my $self = shift;
126
127     my $prefix = "upload_" . $self->{'fileID'};
128     my $session = get_session($self->{'sessionID'});
129
130     # temporarily take file handle out of structure
131     my $fh = $self->{'fh'};
132     delete $self->{'fh'};
133     $session->param($prefix, $self);
134     $session->flush();
135     $self->{'fh'} =$fh;
136 }
137
138 =head2 id
139
140 =over 4
141
142 my $fileID = $uploaded_file->id();
143
144 =back
145
146 =cut
147
148 sub id {
149     my $self = shift;
150     return $self->{'fileID'};
151 }
152
153 =head2 name
154
155 =over 4
156
157 my $name = $uploaded_file->name();
158 $uploaded_file->name($name);
159
160 =back
161
162 Accessor method for the name by which the file is to be known.
163
164 =cut
165
166 sub name {
167     my $self = shift;
168     if (@_) {
169         $self->{'name'} = shift;
170         $self->_serialize();
171     } else {
172         return $self->{'name'};
173     }
174 }
175
176 =head2 max_size
177
178 =over 4
179
180 my $max_size = $uploaded_file->max_size();
181 $uploaded_file->max_size($max_size);
182
183 =back
184
185 Accessor method for the maximum size of the uploaded file.
186
187 =cut
188
189 sub max_size {
190     my $self = shift;
191     @_ ? $self->{'max_size'} = shift : $self->{'max_size'};
192 }
193
194 =head2 stash
195
196 =over 4
197
198 $uploaded_file->stash($dataref, $bytes_read);
199
200 =back
201
202 Write C<$dataref> to the temporary file.  C<$bytes_read> represents
203 the number of bytes (out of C<$max_size>) transmitted so far.
204
205 =cut
206
207 sub stash {
208     my $self = shift;
209     my $dataref = shift;
210     my $bytes_read = shift;
211
212     my $fh = $self->{'fh'};
213     print $fh $$dataref;
214
215     my $percentage = int(($bytes_read / $self->{'max_size'}) * 100);
216     if ($percentage > $self->{'progress'}) {
217         $self->{'progress'} = $percentage;
218         $self->_serialize();
219     }
220 }
221
222 =head2 done
223
224 =over 4
225
226 $uploaded_file->done();
227
228 =back
229
230 Indicates that all of the bytes have been uploaded.
231
232 =cut
233
234 sub done {
235     my $self = shift;
236     $self->{'progress'} = 'done';
237     $self->{'fh'}->close();
238     $self->_serialize();
239 }
240
241 =head2 upload_progress
242
243 =over 4
244
245 my $upload_progress = C4::UploadFile->upload_progress($sessionID);
246
247 =back
248
249 Returns (as an integer from 0 to 100) the percentage
250 progress of the current file upload.
251
252 =cut
253
254 sub upload_progress {
255     my ($class, $sessionID) = shift;
256
257     my $session = get_session($sessionID);
258
259     my $fileID = $session->param('current_upload');
260
261     my $reported_progress = 0;
262     if (defined $fileID and $fileID ne "") {
263         my $file = C4::UploadedFile->fetch($sessionID, $fileID);
264         my $progress = $file->{'progress'};
265         if (defined $progress) {
266             if ($progress eq "done") {
267                 $reported_progress = 100;
268             } else {
269                 $reported_progress = $progress;
270             }
271         }
272     }
273     return $reported_progress;
274 }
275
276 =head2 fetch
277
278 =over 4
279
280     my $uploaded_file = C4::UploadedFile->fetch($sessionID, $fileID);
281
282 =back
283
284 Retrieves an uploaded file object from the current session.
285
286 =cut
287
288 sub fetch {
289     my $class = shift;
290     my $sessionID = shift;
291     my $fileID = shift;
292
293     my $session = get_session($sessionID);
294     my $prefix = "upload_$fileID";
295     my $self = $session->param($prefix);
296     my $fh = new IO::File $self->{'tmp_file_name'}, "r";
297     $self->{'fh'} = $fh;
298
299     bless $self, $class;
300     return $self;
301 }
302
303 =head2 fh
304
305 =over
306
307 my $fh = $uploaded_file->fh();
308
309 =back
310
311 Returns an IO::File handle to read the uploaded file.
312
313 =cut
314
315 sub fh {
316     my $self = shift;
317     return $self->{'fh'};
318 }
319
320 1;
321 __END__
322
323 =head1 AUTHOR
324
325 Koha Development Team <info@koha.org>
326
327 Galen Charlton <galen.charlton@liblime.com>
328
329 =cut