1 package Catalyst::Response;
5 use Moose::Util::TypeConstraints;
6 use namespace::autoclean;
8 with 'MooseX::Emulate::Class::Accessor::Fast';
13 writer => '_set_response_cb',
14 clearer => '_clear_response_cb',
15 predicate => '_has_response_cb',
18 subtype 'Catalyst::Engine::Types::Writer',
19 as duck_type([qw(write close)]);
23 isa => 'Catalyst::Engine::Types::Writer', #Pointless since we control how this is built
24 #writer => '_set_writer', Now that its lazy I think this is safe to remove
25 clearer => '_clear_writer',
26 predicate => '_has_writer',
28 builder => '_build_writer',
34 ## These two lines are probably crap now...
35 $self->_context->finalize_headers unless
36 $self->finalized_headers;
39 $self->headers->scan(sub { push @headers, @_ });
41 my $writer = $self->_response_cb->([ $self->status, \@headers ]);
42 $self->_clear_response_cb;
49 predicate=>'_has_write_fh',
51 builder=>'_build_write_fh',
54 sub _build_write_fh { shift ->_writer }
58 return if $self->_has_write_fh;
59 if($self->_has_writer) {
64 has cookies => (is => 'rw', default => sub { {} });
65 has body => (is => 'rw', default => undef);
66 sub has_body { defined($_[0]->body) }
68 has location => (is => 'rw');
69 has status => (is => 'rw', default => 200);
70 has finalized_headers => (is => 'rw', default => 0);
73 isa => 'HTTP::Headers',
74 handles => [qw(content_encoding content_length content_type header)],
75 default => sub { HTTP::Headers->new() },
82 clearer => '_clear_context',
85 before [qw(status headers content_encoding content_length content_type header)] => sub {
88 $self->_context->log->warn(
89 "Useless setting a header value after finalize_headers called." .
90 " Not what you want." )
91 if ( $self->finalized_headers && @_ );
94 sub output { shift->body(@_) }
96 sub code { shift->status(@_) }
99 my ( $self, $buffer ) = @_;
101 # Finalize headers if someone manually writes output
102 $self->_context->finalize_headers unless $self->finalized_headers;
104 $buffer = q[] unless defined $buffer;
106 my $len = length($buffer);
107 $self->_writer->write($buffer);
112 sub finalize_headers {
117 sub from_psgi_response {
118 my ($self, $psgi_res) = @_;
119 if(ref $psgi_res eq 'ARRAY') {
120 my ($status, $headers, $body) = @$psgi_res;
121 $self->status($status);
122 $self->headers(HTTP::Headers->new(@$headers));
124 } elsif(ref $psgi_res eq 'CODE') {
126 my $response = shift;
127 my ($status, $headers, $maybe_body) = @$response;
128 $self->status($status);
129 $self->headers(HTTP::Headers->new(@$headers));
130 if(defined $maybe_body) {
131 $self->body($maybe_body);
133 return $self->write_fh;
137 die "You can't set a Catalyst response from that, expect a valid PSGI response";
143 Catalyst::Response - stores output responding to the current client request
150 $res->content_encoding;
151 $res->content_length;
163 This is the Catalyst Response class, which provides methods for responding to
164 the current client request. The appropriate L<Catalyst::Engine> for your environment
165 will turn the Catalyst::Response into a HTTP Response and return it to the client.
169 =head2 $res->body( $text | $fh | $iohandle_object )
171 $c->response->body('Catalyst rocks!');
173 Sets or returns the output (text or binary data). If you are returning a large body,
174 you might want to use a L<IO::Handle> type of object (Something that implements the read method
175 in the same fashion), or a filehandle GLOB. Catalyst
176 will write it piece by piece into the response.
178 When using a L<IO::Handle> type of object and no content length has been
179 already set in the response headers Catalyst will make a reasonable attempt
180 to determine the size of the Handle. Depending on the implementation of your
181 handle object, setting the content length may fail. If it is at all possible
182 for you to determine the content length of your handle object,
183 it is recommended that you set the content length in the response headers
184 yourself, which will be respected and sent by Catalyst in the response.
186 =head2 $res->has_body
188 Predicate which returns true when a body has been set.
192 Alias for $res->status.
194 =head2 $res->content_encoding
196 Shortcut for $res->headers->content_encoding.
198 =head2 $res->content_length
200 Shortcut for $res->headers->content_length.
202 =head2 $res->content_type
204 Shortcut for $res->headers->content_type.
206 This value is typically set by your view or plugin. For example,
207 L<Catalyst::Plugin::Static::Simple> will guess the mime type based on the file
208 it found, while L<Catalyst::View::TT> defaults to C<text/html>.
212 Returns a reference to a hash containing cookies to be set. The keys of the
213 hash are the cookies' names, and their corresponding values are hash
214 references used to construct a L<CGI::Simple::Cookie> object.
216 $c->response->cookies->{foo} = { value => '123' };
218 The keys of the hash reference on the right correspond to the L<CGI::Simple::Cookie>
219 parameters of the same name, except they are used without a leading dash.
220 Possible parameters are:
240 Shortcut for $res->headers->header.
244 Returns an L<HTTP::Headers> object, which can be used to set headers.
246 $c->response->headers->header( 'X-Catalyst' => $Catalyst::VERSION );
250 Alias for $res->body.
252 =head2 $res->redirect( $url, $status )
254 Causes the response to redirect to the specified URL. The default status is
257 $c->response->redirect( 'http://slashdot.org' );
258 $c->response->redirect( 'http://slashdot.org', 307 );
260 This is a convenience method that sets the Location header to the
261 redirect destination, and then sets the response status. You will
262 want to C< return > or C<< $c->detach() >> to interrupt the normal
263 processing flow if you want the redirect to occur straight away.
265 B<Note:> do not give a relative URL as $url, i.e: one that is not fully
266 qualified (= C<http://...>, etc.) or that starts with a slash
267 (= C</path/here>). While it may work, it is not guaranteed to do the right
268 thing and is not a standard behaviour. You may opt to use uri_for() or
269 uri_for_action() instead.
277 my $location = shift;
278 my $status = shift || 302;
280 $self->location($location);
281 $self->status($status);
284 return $self->location;
287 =head2 $res->location
289 Sets or returns the HTTP 'Location'.
293 Sets or returns the HTTP status.
295 $c->response->status(404);
297 $res->code is an alias for this, to match HTTP::Response->code.
299 =head2 $res->write( $data )
301 Writes $data to the output stream.
303 =head2 $res->write_fh
305 Returns a PSGI $writer object that has two methods, write and close. You can
306 close over this object for asynchronous and nonblocking applications. For
307 example (assuming you are using a supporting server, like L<Twiggy>
309 package AsyncExample::Controller::Root;
313 BEGIN { extends 'Catalyst::Controller' }
319 $write_fh->write("Finishing: $message\n");
324 sub anyevent :Local :Args(0) {
326 my $cb = $self->prepare_cb($c->res->write_fh);
329 $watcher = AnyEvent->timer(
332 $cb->(scalar localtime);
333 undef $watcher; # cancel circular-ref
337 =head2 $res->print( @data )
339 Prints @data to the output stream, separated by $,. This lets you pass
340 the response object to functions that want to write to an L<IO::Handle>.
342 =head2 $self->finalize_headers($c)
344 Writes headers to response if not already written
346 =head2 from_psgi_response
348 Given a PSGI response (either three element ARRAY reference OR coderef expecting
349 a $responder) set the response from it.
351 Properly supports streaming and delayed response and / or async IO if running
352 under an expected event loop.
356 package MyApp::Web::Controller::Test;
358 use base 'Catalyst::Controller';
359 use Plack::App::Directory;
362 my $app = Plack::App::Directory->new({ root => "/path/to/htdocs" })
365 sub myaction :Local Args {
367 $c->res->from_psgi_response($app->($c->req->env));
370 Please note this does not attempt to map or nest your PSGI application under
371 the Controller and Action namespace or path.
375 Ensures that the response is flushed and closed at the end of the
388 defined $self->write($data) or return;
391 defined $self->write($,) or return;
392 defined $self->write($_) or return;
394 defined $self->write($\) or return;
401 Catalyst Contributors, see Catalyst.pm
405 This library is free software. You can redistribute it and/or modify
406 it under the same terms as Perl itself.
410 __PACKAGE__->meta->make_immutable;