lib/Catalyst/Request/Upload.pm

   1 package Catalyst::Request::Upload;
   2
   3 use strict;
   4 use base 'Class::Accessor::Fast';
   5
   6 use Catalyst::Exception;
   7 use File::Copy ();
   8 use IO::File   ();
   9
  10 __PACKAGE__->mk_accessors(qw/filename headers size tempname type/);
  11
  12 sub new { shift->SUPER::new( ref( $_[0] ) ? $_[0] : {@_} ) }
  13
  14 =head1 NAME
  15
  16 Catalyst::Request::Upload - handles file upload requests
  17
  18 =head1 SYNOPSIS
  19
  20     $upload->copy_to;
  21     $upload->fh;
  22     $upload->filename;
  23     $upload->headers;
  24     $upload->link_to;
  25     $upload->size;
  26     $upload->slurp;
  27     $upload->tempname;
  28     $upload->type;
  29
  30 To specify where Catalyst should put the temporary files, set the 'uploadtmp'
  31 option in the Catalyst config. If unset, Catalyst will use the system temp dir.
  32
  33     __PACKAGE__->config( uploadtmp => '/path/to/tmpdir' );
  34
  35 It is provided a way to have configurable temporary directory.
  36 If there is no config uploadtmp, system temprary directory will used.
  37
  38     __PACKAGE__->config( uploadtmp => '/path/to/tmpdir' );
  39
  40 See also L<Catalyst>.
  41
  42 =head1 DESCRIPTION
  43
  44 This class provides accessors and methods to handle client upload requests.
  45
  46 =head1 METHODS
  47
  48 =head2 $upload->new
  49
  50 Simple constructor.
  51
  52 =head2 $upload->copy_to
  53
  54 Copies the temporary file using L<File::Copy>. Returns true for success,
  55 false for failure.
  56
  57      $upload->copy_to('/path/to/target');
  58
  59 =cut
  60
  61 sub copy_to {
  62     my $self = shift;
  63     return File::Copy::copy( $self->tempname, @_ );
  64 }
  65
  66 =head2 $upload->fh
  67
  68 Opens a temporary file (see tempname below) and returns an L<IO::File> handle.
  69
  70 =cut
  71
  72 sub fh {
  73     my $self = shift;
  74
  75     my $fh = IO::File->new( $self->tempname, IO::File::O_RDONLY );
  76
  77     unless ( defined $fh ) {
  78
  79         my $filename = $self->tempname;
  80
  81         Catalyst::Exception->throw(
  82             message => qq/Can't open '$filename': '$!'/ );
  83     }
  84
  85     return $fh;
  86 }
  87
  88 =head2 $upload->filename
  89
  90 Returns the client-supplied filename.
  91
  92 =head2 $upload->headers
  93
  94 Returns an L<HTTP::Headers> object for the request.
  95
  96 =head2 $upload->link_to
  97
  98 Creates a hard link to the temporary file. Returns true for success,
  99 false for failure.
 100
 101     $upload->link_to('/path/to/target');
 102
 103 =cut
 104
 105 sub link_to {
 106     my ( $self, $target ) = @_;
 107     return CORE::link( $self->tempname, $target );
 108 }
 109
 110 =head2 $upload->size
 111
 112 Returns the size of the uploaded file in bytes.
 113
 114 =head2 $upload->slurp
 115
 116 Returns a scalar containing the contents of the temporary file.
 117
 118 =cut
 119
 120 sub slurp {
 121     my ( $self, $layer ) = @_;
 122
 123     unless ($layer) {
 124         $layer = ':raw';
 125     }
 126
 127     my $content = undef;
 128     my $handle  = $self->fh;
 129
 130     binmode( $handle, $layer );
 131
 132     while ( $handle->sysread( my $buffer, 8192 ) ) {
 133         $content .= $buffer;
 134     }
 135
 136     return $content;
 137 }
 138
 139 =head2 $upload->tempname
 140
 141 Returns the path to the temporary file.
 142
 143 =head2 $upload->type
 144
 145 Returns the client-supplied Content-Type.
 146
 147 =head1 AUTHORS
 148
 149 Sebastian Riedel, C<sri@cpan.org>
 150
 151 Christian Hansen, C<ch@ngmedia.com>
 152
 153 =head1 COPYRIGHT
 154
 155 This program is free software, you can redistribute it and/or modify
 156 it under the same terms as Perl itself.
 157
 158 =cut
 159
 160 1;