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 See also L<Catalyst>.
  36
  37 =head1 DESCRIPTION
  38
  39 This class provides accessors and methods to handle client upload requests.
  40
  41 =head1 METHODS
  42
  43 =head2 $upload->new
  44
  45 Simple constructor.
  46
  47 =head2 $upload->copy_to
  48
  49 Copies the temporary file using L<File::Copy>. Returns true for success,
  50 false for failure.
  51
  52      $upload->copy_to('/path/to/target');
  53
  54 =cut
  55
  56 sub copy_to {
  57     my $self = shift;
  58     return File::Copy::copy( $self->tempname, @_ );
  59 }
  60
  61 =head2 $upload->fh
  62
  63 Opens a temporary file (see tempname below) and returns an L<IO::File> handle.
  64
  65 =cut
  66
  67 sub fh {
  68     my $self = shift;
  69
  70     my $fh = IO::File->new( $self->tempname, IO::File::O_RDONLY );
  71
  72     unless ( defined $fh ) {
  73
  74         my $filename = $self->tempname;
  75
  76         Catalyst::Exception->throw(
  77             message => qq/Can't open '$filename': '$!'/ );
  78     }
  79
  80     return $fh;
  81 }
  82
  83 =head2 $upload->filename
  84
  85 Returns the client-supplied filename.
  86
  87 =head2 $upload->headers
  88
  89 Returns an L<HTTP::Headers> object for the request.
  90
  91 =head2 $upload->link_to
  92
  93 Creates a hard link to the temporary file. Returns true for success,
  94 false for failure.
  95
  96     $upload->link_to('/path/to/target');
  97
  98 =cut
  99
 100 sub link_to {
 101     my ( $self, $target ) = @_;
 102     return CORE::link( $self->tempname, $target );
 103 }
 104
 105 =head2 $upload->size
 106
 107 Returns the size of the uploaded file in bytes.
 108
 109 =head2 $upload->slurp
 110
 111 Returns a scalar containing the contents of the temporary file.
 112
 113 =cut
 114
 115 sub slurp {
 116     my ( $self, $layer ) = @_;
 117
 118     unless ($layer) {
 119         $layer = ':raw';
 120     }
 121
 122     my $content = undef;
 123     my $handle  = $self->fh;
 124
 125     binmode( $handle, $layer );
 126
 127     while ( $handle->sysread( my $buffer, 8192 ) ) {
 128         $content .= $buffer;
 129     }
 130
 131     return $content;
 132 }
 133
 134 =head2 $upload->tempname
 135
 136 Returns the path to the temporary file.
 137
 138 =head2 $upload->type
 139
 140 Returns the client-supplied Content-Type.
 141
 142 =head1 AUTHORS
 143
 144 Sebastian Riedel, C<sri@cpan.org>
 145
 146 Christian Hansen, C<ch@ngmedia.com>
 147
 148 =head1 COPYRIGHT
 149
 150 This program is free software, you can redistribute it and/or modify
 151 it under the same terms as Perl itself.
 152
 153 =cut
 154
 155 1;