=head1 Description
-Starting in 5.90080 L<Catalyst> will enable UTF8 encoding by default for
+Starting in 5.90080 L<Catalyst> will enable UTF8 encoding by default for
text like body responses. In addition we've made a ton of fixes around encoding
and utf8 scattered throughout the codebase. This document attempts to give
an overview of the assumptions and practices that L<Catalyst> uses when
and explain where we may have been exceptional to respect our commitment
to backwards compatibility.
-=head1 UTF8 in Controller Actions
+=head1 UTF8 in Controller Actions
Using UTF8 characters in your Controller classes and actions.
Again, remember that we are display the unicode character and using it to match actions
containing such multibyte characters BUT over HTTP you are getting these as URL encoded
-bytes. For example if you looked at the L<PSGI> C<$env> value for C<REQUEST_URI> you
-would see (for the above request)
+bytes. For example if you looked at the L<PSGI> C<$env> value for C<REQUEST_URI> you
+would see (for the above request)
REQUEST_URI => "/base/%E2%99%A5/%E2%99%A5/%E2%99%A5/%E2%99%A5"
Again, remember that values of your parameters are now decode into Unicode strings. so
for example you'd expect the result of length to reflect the character length not
-the byte length.
+the byte length.
Just like with arguments and captures, you can use utf8 literals (or utf8
strings) in $c->uri_for:
http://localhost/example?%E2%99%A5=%E2%99%A5%E2%99%A5
Since again what you want is a properly url encoded version of this. Ultimately what you want
-to send over the wire via HTTP needs to be bytes (not unicode characters).
+to send over the wire via HTTP needs to be bytes (not unicode characters).
Remember if you use any utf8 literals in your source code, you should use the
C<use utf8> pragma.
As a result since L<Catalyst> now serves UTF8 encoded responses by default, this means that
you can mostly rely on incoming form POSTs to be so encoded. L<Catalyst> will make this
assumption and decode accordingly (unless you explicitly turn off encoding...) If you are
-running Catalyst in developer debug, then you will see the correct unicode characters in
+running Catalyst in developer debug, then you will see the correct unicode characters in
the debug output. For example if you generate a POST request:
use Catalyst::Test 'MyApp';
And if you had a controller like this:
package MyApp::Controller::Example;
-
+
use base 'Catalyst::Controller';
sub posted :POST Local {
use Encode 2.21 'decode_utf8';
is decode_utf8($req->content), 'hearts => ♥';
-In this case we decode so that we can print and compare strings with multibyte characters.
+In this case we decode so that we can print and compare strings with multibyte characters.
B<NOTE> In some cases some browsers may not follow the specification and set the form POST
encoding based on the server response. Catalyst itself doesn't attempt any workarounds, but one
my ($self, $c) = @_;
$c->response->content_type('text/html');
$c->response->write("<p>This is stream_write action ♥</p>");
- }
+ }
sub stream_write_fh :Local {
my ($self, $c) = @_;
application/xml
application/vnd.user+xml
-You should set your content type prior to header finalization if you want L<Catalyst> to
+You should set your content type prior to header finalization if you want L<Catalyst> to
encode.
B<NOTE> We do not attempt to encode C<application/json> since the two most commonly used
B<NOTE> If you manually set the content-type character set to whatever $c->encoding->mime_name
is set to, we STILL encode, rather than assume your manual setting is a flag to override. This
-is done to support backward compatible assumptions. If you are going to handle encoding
-manually you may set $c->clear_encoding for a single request response cycle.
+is done to support backward compatible assumptions (in particular L<Catalyst::View::TT> has set
+a utf-8 character set in its default content-type for ages, even though it does not itself do any
+encoding on the body response). If you are going to handle encoding manually you may set
+$c->clear_encoding for a single request response cycle, or as in the above example set an alternative
+encoding.
=head2 Encoding with streaming type responses
missed something please alert the development team (instead of introducing a local hack into
your application that will mean nobody will ever upgrade it...).
+=head2 Setting the response from an external PSGI application.
+
+L<Catalyst::Response> allows one to set the response from an external L<PSGI> application.
+If you do this, and that external application sets a character set on the content-type, we
+C<clear_encoding> for the rest of the response. This is done to prevent double encoding.
+
+B<NOTE> Even if the character set of the content type is the same as the encoding set in
+$c->encoding, we still skip encoding. This is a regrettable difference from the general rule
+outlined above, where if the current character set is the same as the current encoding, we
+encode anyway. Nevertheless I think this is the correct behavior since the earlier rule exists
+only to support backward compatibility with L<Catalyst::View::TT>.
+
+In general if you want L<Catalyst> to handle encoding, you should avoid setting the content
+type character set since Catalyst will do so automatically based on the requested response
+encoding. Its best to request alternative encodings by setting $c->encoding and if you really
+want manual control of encoding you should always $c->clear_encoding so that programmers that
+come after you are very clear as to your intentions.
+
=head2 Disabling default UTF8 encoding
You may encounter issues with your legacy code running under default UTF8 body encoding. If
projects / catagits/Catalyst-Runtime.git / blobdiff