updated UTF8 doc to note the new introduced hacks
[catagits/Catalyst-Runtime.git] / lib / Catalyst / UTF8.pod
CommitLineData
a09b49d2 1=encoding UTF-8
2
3=head1 Name
4
d63cc9c8 5Catalyst::UTF8 - All About UTF8 and Catalyst Encoding
a09b49d2 6
7=head1 Description
8
b596572b 9Starting in 5.90080 L<Catalyst> will enable UTF8 encoding by default for
a09b49d2 10text like body responses. In addition we've made a ton of fixes around encoding
11and utf8 scattered throughout the codebase. This document attempts to give
12an overview of the assumptions and practices that L<Catalyst> uses when
13dealing with UTF8 and encoding issues. You should also review the
14Changes file, L<Catalyst::Delta> and L<Catalyst::Upgrading> for more.
15
d63cc9c8 16We attempt to describe all relevant processes, try to give some advice
a09b49d2 17and explain where we may have been exceptional to respect our commitment
18to backwards compatibility.
19
b596572b 20=head1 UTF8 in Controller Actions
a09b49d2 21
22Using UTF8 characters in your Controller classes and actions.
23
24=head2 Summary
25
26In this section we will review changes to how UTF8 characters can be used in
27controller actions, how it looks in the debugging screens (and your logs)
28as well as how you construct L<URL> objects to actions with UTF8 paths
29(or using UTF8 args or captures).
30
31=head2 Unicode in Controllers and URLs
32
33 package MyApp::Controller::Root;
34
473078ff 35 use utf8;
a09b49d2 36 use base 'Catalyst::Controller';
37
38 sub heart_with_arg :Path('♥') Args(1) {
39 my ($self, $c, $arg) = @_;
40 }
41
42 sub base :Chained('/') CaptureArgs(0) {
43 my ($self, $c) = @_;
44 }
45
46 sub capture :Chained('base') PathPart('♥') CaptureArgs(1) {
47 my ($self, $c, $capture) = @_;
48 }
49
50 sub arg :Chained('capture') PathPart('♥') Args(1) {
51 my ($self, $c, $arg) = @_;
52 }
53
54=head2 Discussion
55
56In the example controller above we have constructed two matchable URL routes:
57
58 http://localhost/root/♥/{arg}
59 http://localhost/base/♥/{capture}/♥/{arg}
60
61The first one is a classic Path type action and the second uses Chaining, and
62spans three actions in total. As you can see, you can use unicode characters
473078ff 63in your Path and PathPart attributes (remember to use the C<utf8> pragma to allow
a09b49d2 64these multibyte characters in your source). The two constructed matchable routes
65would match the following incoming URLs:
66
67 (heart_with_arg) -> http://localhost/root/%E2%99%A5/{arg}
68 (base/capture/arg) -> http://localhost/base/%E2%99%A5/{capture}/%E2%99%A5/{arg}
69
70That path path C<%E2%99%A5> is url encoded unicode (assuming you are hitting this with
71a reasonably modern browser). Its basically what goes over HTTP when your type a
72browser location that has the unicode 'heart' in it. However we will use the unicode
73symbol in your debugging messages:
74
75 [debug] Loaded Path actions:
76 .-------------------------------------+--------------------------------------.
77 | Path | Private |
78 +-------------------------------------+--------------------------------------+
79 | /root/♥/* | /root/heart_with_arg |
80 '-------------------------------------+--------------------------------------'
81
82 [debug] Loaded Chained actions:
83 .-------------------------------------+--------------------------------------.
84 | Path Spec | Private |
85 +-------------------------------------+--------------------------------------+
86 | /base/♥/*/♥/* | /root/base (0) |
87 | | -> /root/capture (1) |
88 | | => /root/arg |
89 '-------------------------------------+--------------------------------------'
90
91And if the requested URL uses unicode characters in your captures or args (such as
92C<http://localhost:/base/♥/♥/♥/♥>) you should see the arguments and captures as their
93unicode characters as well:
94
95 [debug] Arguments are "♥"
96 [debug] "GET" request for "base/♥/♥/♥/♥" from "127.0.0.1"
97 .------------------------------------------------------------+-----------.
98 | Action | Time |
99 +------------------------------------------------------------+-----------+
100 | /root/base | 0.000080s |
101 | /root/capture | 0.000075s |
102 | /root/arg | 0.000755s |
103 '------------------------------------------------------------+-----------'
104
105Again, remember that we are display the unicode character and using it to match actions
106containing such multibyte characters BUT over HTTP you are getting these as URL encoded
b596572b 107bytes. For example if you looked at the L<PSGI> C<$env> value for C<REQUEST_URI> you
108would see (for the above request)
a09b49d2 109
110 REQUEST_URI => "/base/%E2%99%A5/%E2%99%A5/%E2%99%A5/%E2%99%A5"
111
112So on the incoming request we decode so that we can match and display unicode characters
113(after decoding the URL encoding). This makes it straightforward to use these types of
114multibyte characters in your actions and see them incoming in captures and arguments. Please
115keep this in might if you are doing for example regular expression matching, length determination
116or other string comparisons, you will need to try these incoming variables as though UTF8
117strings. For example in the following action:
118
119 sub arg :Chained('capture') PathPart('♥') Args(1) {
120 my ($self, $c, $arg) = @_;
121 }
122
123when $arg is "♥" you should expect C<length($arg)> to be C<1> since it is indeed one character
124although it will take more than one byte to store.
125
126=head2 UTF8 in constructing URLs via $c->uri_for
127
128For the reverse (constructing meaningful URLs to actions that contain multibyte characters
129in their paths or path parts, or when you want to include such characters in your captures
130or arguments) L<Catalyst> will do the right thing (again just remember to use the C<utf8>
131pragma).
132
133 use utf8;
134 my $url = $c->uri_for( $c->controller('Root')->action_for('arg'), ['♥','♥']);
135
473078ff 136When you stringify this object (for use in a template, for example) it will automatically
a09b49d2 137do the right thing regarding utf8 encoding and url encoding.
138
139 http://localhost/base/%E2%99%A5/%E2%99%A5/%E2%99%A5/%E2%99%A5
140
141Since again what you want is a properly url encoded version of this. In this case your string
142length will reflect URL encoded bytes, not the character length. Ultimately what you want
143to send over the wire via HTTP needs to be bytes.
144
145=head1 UTF8 in GET Query and Form POST
146
147What Catalyst does with UTF8 in your GET and classic HTML Form POST
148
149=head2 UTF8 in URL query and keywords
150
473078ff 151The same rules that we find in URL paths also cover URL query parts. That is
152if one types a URL like this into the browser
a09b49d2 153
154 http://localhost/example?♥=♥♥
155
156When this goes 'over the wire' to your application server its going to be as
157percent encoded bytes:
158
159
160 http://localhost/example?%E2%99%A5=%E2%99%A5%E2%99%A5
161
162When L<Catalyst> encounters this we decode the percent encoding and the utf8
163so that we can properly display this information (such as in the debugging
164logs or in a response.)
165
166 [debug] Query Parameters are:
167 .-------------------------------------+--------------------------------------.
168 | Parameter | Value |
169 +-------------------------------------+--------------------------------------+
170 | ♥ | ♥♥ |
171 '-------------------------------------+--------------------------------------'
172
173All the values and keys that are part of $c->req->query_parameters will be
174utf8 decoded. So you should not need to do anything special to take those
175values/keys and send them to the body response (since as we will see later
176L<Catalyst> will do all the necessary encoding for you).
177
178Again, remember that values of your parameters are now decode into Unicode strings. so
179for example you'd expect the result of length to reflect the character length not
b596572b 180the byte length.
a09b49d2 181
182Just like with arguments and captures, you can use utf8 literals (or utf8
183strings) in $c->uri_for:
184
185 use utf8;
186 my $url = $c->uri_for( $c->controller('Root')->action_for('example'), {'♥' => '♥♥'});
187
473078ff 188When you stringify this object (for use in a template, for example) it will automatically
a09b49d2 189do the right thing regarding utf8 encoding and url encoding.
190
191 http://localhost/example?%E2%99%A5=%E2%99%A5%E2%99%A5
192
193Since again what you want is a properly url encoded version of this. Ultimately what you want
b596572b 194to send over the wire via HTTP needs to be bytes (not unicode characters).
a09b49d2 195
196Remember if you use any utf8 literals in your source code, you should use the
197C<use utf8> pragma.
198
f9d5afbc 199B<NOTE:> Assuming UTF-8 in your query parameters and keywords may be an issue if you have
200legacy code where you created URL in templates manually and used an encoding other than UTF-8.
201In these cases you may find versions of Catalyst after 5.90080+ will incorrectly decode. For
202backwards compatibility we offer three configurations settings, here described in order of
203precedence:
204
205C<do_not_decode_query>
206
207If true, then do not try to character decode any wide characters in your
208request URL query or keywords.
209
210C<default_query_encoding>
211
212This setting allows one to specify a fixed value for how to decode your query, instead of using
213the default, UTF-8.
214
215C<decode_query_using_global_encoding>
216
217If this is true we decode using whatever you set C<encoding> to.
218
a09b49d2 219=head2 UTF8 in Form POST
220
221In general most modern browsers will follow the specification, which says that POSTed
222form fields should be encoded in the same way that the document was served with. That means
223that if you are using modern Catalyst and serving UTF8 encoded responses, a browser is
224supposed to notice that and encode the form POSTs accordingly.
225
226As a result since L<Catalyst> now serves UTF8 encoded responses by default, this means that
227you can mostly rely on incoming form POSTs to be so encoded. L<Catalyst> will make this
228assumption and decode accordingly (unless you explicitly turn off encoding...) If you are
b596572b 229running Catalyst in developer debug, then you will see the correct unicode characters in
a09b49d2 230the debug output. For example if you generate a POST request:
231
232 use Catalyst::Test 'MyApp';
233 use utf8;
234
235 my $res = request POST "/example/posted", ['♥'=>'♥', '♥♥'=>'♥'];
236
237Running in CATALYST_DEBUG=1 mode you should see output like this:
238
239 [debug] Body Parameters are:
240 .-------------------------------------+--------------------------------------.
241 | Parameter | Value |
242 +-------------------------------------+--------------------------------------+
243 | ♥ | ♥ |
244 | ♥♥ | ♥ |
245 '-------------------------------------+--------------------------------------'
246
247And if you had a controller like this:
248
249 package MyApp::Controller::Example;
b596572b 250
a09b49d2 251 use base 'Catalyst::Controller';
252
253 sub posted :POST Local {
254 my ($self, $c) = @_;
255 $c->res->content_type('text/plain');
256 $c->res->body("hearts => ${\$c->req->post_parameters->{♥}}");
257 }
258
259The following test case would be true:
260
261 use Encode 2.21 'decode_utf8';
262 is decode_utf8($req->content), 'hearts => ♥';
263
b596572b 264In this case we decode so that we can print and compare strings with multibyte characters.
a09b49d2 265
266B<NOTE> In some cases some browsers may not follow the specification and set the form POST
267encoding based on the server response. Catalyst itself doesn't attempt any workarounds, but one
268common approach is to use a hidden form field with a UTF8 value (You might be familiar with
269this from how Ruby on Rails has HTML form helpers that do that automatically). In that case
270some browsers will send UTF8 encoded if it notices the hidden input field contains such a
271character. Also, you can add an HTML attribute to your form tag which many modern browsers
272will respect to set the encoding (accept-charset="utf-8"). And lastly there are some javascript
273based tricks and workarounds for even more odd cases (just search the web for this will return
274a number of approaches. Hopefully as more compliant browsers become popular these edge cases
275will fade.
276
b16a64af 277B<NOTE> It is possible for a form POST multipart response (normally a file upload) to contain
278inline content with mixed content character sets and encoding. For example one might create
279a POST like this:
280
281 use utf8;
282 use HTTP::Request::Common;
283
284 my $utf8 = 'test ♥';
285 my $shiftjs = 'test テスト';
286 my $req = POST '/root/echo_arg',
287 Content_Type => 'form-data',
288 Content => [
289 arg0 => 'helloworld',
290 Encode::encode('UTF-8','♥') => Encode::encode('UTF-8','♥♥'),
291 arg1 => [
292 undef, '',
293 'Content-Type' =>'text/plain; charset=UTF-8',
294 'Content' => Encode::encode('UTF-8', $utf8)],
295 arg2 => [
296 undef, '',
297 'Content-Type' =>'text/plain; charset=SHIFT_JIS',
298 'Content' => Encode::encode('SHIFT_JIS', $shiftjs)],
299 arg2 => [
300 undef, '',
301 'Content-Type' =>'text/plain; charset=SHIFT_JIS',
302 'Content' => Encode::encode('SHIFT_JIS', $shiftjs)],
303 ];
304
305In this case we've created a POST request but each part specifies its own content
306character set (and setting a content encoding would also be possible). Generally one
307would not run into this situation in a web browser context but for completeness sake
308Catalyst will notice if a multipart POST contains parts with complex or extended
309header information and in those cases it will not attempt to apply decoding to the
310form values. Instead the part will be represented as an instance of an object
311L<Catalyst::Request::PartData> which will contain all the header information needed
312for you to perform custom parser of the data.
313
a09b49d2 314=head1 UTF8 Encoding in Body Response
315
316When does L<Catalyst> encode your response body and what rules does it use to
317determine when that is needed.
318
319=head2 Summary
320
321 use utf8;
322 use warnings;
323 use strict;
324
325 package MyApp::Controller::Root;
326
327 use base 'Catalyst::Controller';
328 use File::Spec;
329
330 sub scalar_body :Local {
331 my ($self, $c) = @_;
332 $c->response->content_type('text/html');
333 $c->response->body("<p>This is scalar_body action ♥</p>");
334 }
335
336 sub stream_write :Local {
337 my ($self, $c) = @_;
338 $c->response->content_type('text/html');
339 $c->response->write("<p>This is stream_write action ♥</p>");
b596572b 340 }
a09b49d2 341
342 sub stream_write_fh :Local {
343 my ($self, $c) = @_;
344 $c->response->content_type('text/html');
345
346 my $writer = $c->res->write_fh;
347 $writer->write_encoded('<p>This is stream_write_fh action ♥</p>');
348 $writer->close;
349 }
350
351 sub stream_body_fh :Local {
352 my ($self, $c) = @_;
353 my $path = File::Spec->catfile('t', 'utf8.txt');
354 open(my $fh, '<', $path) || die "trouble: $!";
355 $c->response->content_type('text/html');
356 $c->response->body($fh);
357 }
358
359=head2 Discussion
360
361Beginning with L<Catalyst> version 5.90080 You no longer need to set the encoding
362configuration (although doing so won't hurt anything).
363
364Currently we only encode if the content type is one of the types which generally expects a
365UTF8 encoding. This is determined by the following regular expression:
366
367 our $DEFAULT_ENCODE_CONTENT_TYPE_MATCH = qr{text|xml$|javascript$};
368 $c->response->content_type =~ /$DEFAULT_ENCODE_CONTENT_TYPE_MATCH/
369
370This is a global variable in L<Catalyst::Response> which is stored in the C<encodable_content_type>
371attribute of $c->response. You may currently alter this directly on the response or globally. In
372the future we may offer a configuration setting for this.
373
374This would match content-types like the following (examples)
375
376 text/plain
377 text/html
378 text/xml
379 application/javascript
380 application/xml
381 application/vnd.user+xml
382
b596572b 383You should set your content type prior to header finalization if you want L<Catalyst> to
a09b49d2 384encode.
385
386B<NOTE> We do not attempt to encode C<application/json> since the two most commonly used
387approaches (L<Catalyst::View::JSON> and L<Catalyst::Action::REST>) have already configured
388their JSON encoders to produce properly encoding UTF8 responses. If you are rolling your
389own JSON encoding, you may need to set the encoder to do the right thing (or override
390the global regular expression to include the JSON media type).
391
392=head2 Encoding with Scalar Body
393
394L<Catalyst> supports several methods of supplying your response with body content. The first
395and currently most common is to set the L<Catalyst::Response> ->body with a scalar string (
396as in the example):
397
398 use utf8;
399
400 sub scalar_body :Local {
401 my ($self, $c) = @_;
402 $c->response->content_type('text/html');
403 $c->response->body("<p>This is scalar_body action ♥</p>");
404 }
405
406In general you should need to do nothing else since L<Catalyst> will automatically encode
407this string during body finalization. The only matter to watch out for is to make sure
408the string has not already been encoded, as this will result in double encoding errors.
409
410B<NOTE> pay attention to the content-type setting in the example. L<Catalyst> inspects that
411content type carefully to determine if the body needs encoding).
412
413B<NOTE> If you set the character set of the response L<Catalyst> will skip encoding IF the
473078ff 414character set is set to something that doesn't match $c->encoding->mime_name. We will assume
a09b49d2 415if you are setting an alternative character set, that means you want to handle the encoding
416yourself. However it might be easier to set $c->encoding for a given response cycle since
417you can override this for a given response. For example here's how to override the default
418encoding and set the correct character set in the response:
419
420 sub override_encoding :Local {
421 my ($self, $c) = @_;
422 $c->res->content_type('text/plain');
423 $c->encoding(Encode::find_encoding('Shift_JIS'));
424 $c->response->body("テスト");
425 }
426
427This will use the alternative encoding for a single response.
428
429B<NOTE> If you manually set the content-type character set to whatever $c->encoding->mime_name
430is set to, we STILL encode, rather than assume your manual setting is a flag to override. This
aca337aa 431is done to support backward compatible assumptions (in particular L<Catalyst::View::TT> has set
432a utf-8 character set in its default content-type for ages, even though it does not itself do any
433encoding on the body response). If you are going to handle encoding manually you may set
434$c->clear_encoding for a single request response cycle, or as in the above example set an alternative
435encoding.
a09b49d2 436
437=head2 Encoding with streaming type responses
438
439L<Catalyst> offers two approaches to streaming your body response. Again, you must remember
440to set your content type prior to streaming, since invoking a streaming response will automatically
441finalize and send your HTTP headers (and your content type MUST be one that matches the regular
442expression given above.)
443
444Also, if you are going to override $c->encoding (or invoke $c->clear_encoding), you should do
445that before anything else!
446
447The first streaming method is to use the C<write> method on the response object. This method
448allows 'inlined' streaming and is generally used with blocking style servers.
449
450 sub stream_write :Local {
451 my ($self, $c) = @_;
452 $c->response->content_type('text/html');
453 $c->response->write("<p>This is stream_write action ♥</p>");
454 }
455
456You may call the C<write> method as often as you need to finish streaming all your content.
457L<Catalyst> will encode each line in turn as long as the content-type meets the 'encodable types'
458requirement and $c->encoding is set (which it is, as long as you did not change it).
459
460B<NOTE> If you try to change the encoding after you start the stream, this will invoke an error
473078ff 461response. However since you've already started streaming this will not show up as an HTTP error
a09b49d2 462status code, but rather error information in your body response and an error in your logs.
463
464The second way to stream a response is to get the response writer object and invoke methods
465on that directly:
466
467 sub stream_write_fh :Local {
468 my ($self, $c) = @_;
469 $c->response->content_type('text/html');
470
471 my $writer = $c->res->write_fh;
472 $writer->write_encoded('<p>This is stream_write_fh action ♥</p>');
473 $writer->close;
474 }
475
473078ff 476This can be used just like the C<write> method, but typically you request this object when
a09b49d2 477you want to do a nonblocking style response since the writer object can be closed over or
478sent to a model that will invoke it in a non blocking manner. For more on using the writer
479object for non blocking responses you should review the C<Catalyst> documentation and also
480you can look at several articles from last years advent, in particular:
481
482L<http://www.catalystframework.org/calendar/2013/10>, L<http://www.catalystframework.org/calendar/2013/11>,
483L<http://www.catalystframework.org/calendar/2013/12>, L<http://www.catalystframework.org/calendar/2013/13>,
484L<http://www.catalystframework.org/calendar/2013/14>.
485
486The main difference this year is that previously calling ->write_fh would return the actual
487L<Plack> writer object that was supplied by your plack application handler, whereas now we wrap
488that object in a lightweight decorator object that proxies the C<write> and C<close> methods
489and supplies an additional C<write_encoded> method. C<write_encoded> does the exact same thing
490as C<write> except that it will first encode the string when necessary. In general if you are
491streaming encodable content such as HTML this is the method to use. If you are streaming
492binary content, you should just use the C<write> method (although if the content type is set
493correctly we would skip encoding anyway, but you may as well avoid the extra noop overhead).
494
495The last style of content response that L<Catalyst> supports is setting the body to a filehandle
496like object. In this case the object is passed down to the Plack application handler directly
497and currently we do nothing to set encoding.
498
499 sub stream_body_fh :Local {
500 my ($self, $c) = @_;
501 my $path = File::Spec->catfile('t', 'utf8.txt');
502 open(my $fh, '<', $path) || die "trouble: $!";
503 $c->response->content_type('text/html');
504 $c->response->body($fh);
505 }
506
507In this example we create a filehandle to a text file that contains UTF8 encoded characters. We
508pass this down without modification, which I think is correct since we don't want to double
509encode. However this may change in a future development release so please be sure to double
510check the current docs and changelog. Its possible a future release will require you to to set
511a encoding on the IO layer level so that we can be sure to properly encode at body finalization.
512So this is still an edge case we are writing test examples for. But for now if you are returning
513a filehandle like response, you are expected to make sure you are following the L<PSGI> specification
473078ff 514and return raw bytes.
a09b49d2 515
516=head2 Override the Encoding on Context
517
518As already noted you may change the current encoding (or remove it) by setting an alternative
519encoding on the context;
520
521 $c->encoding(Encode::find_encoding('Shift_JIS'));
522
523Please note that you can continue to change encoding UNTIL the headers have been finalized. The
524last setting always wins. Trying to change encoding after header finalization is an error.
525
526=head2 Setting the Content Encoding HTTP Header
527
528In some cases you may set a content encoding on your response. For example if you are encoding
529your response with gzip. In this case you are again on your own. If we notice that the
530content encoding header is set when we hit finalization, we skip automatic encoding:
531
532 use Encode;
533 use Compress::Zlib;
534 use utf8;
535
536 sub gzipped :Local {
537 my ($self, $c) = @_;
538
539 $c->res->content_type('text/plain');
540 $c->res->content_type_charset('UTF-8');
541 $c->res->content_encoding('gzip');
542
543 $c->response->body(
544 Compress::Zlib::memGzip(
545 Encode::encode_utf8("manual_1 ♥")));
546 }
547
548
549If you are using L<Catalyst::Plugin::Compress> you need to upgrade to the most recent version
550in order to be compatible with changes introduced in L<Catalyst> 5.90080. Other plugins may
551require updates (please open bugs if you find them).
552
553B<NOTE> Content encoding may be set to 'identify' and we will still perform automatic encoding
554if the content type is encodable and an encoding is present for the context.
555
556=head2 Using Common Views
557
558The following common views have been updated so that their tests pass with default UTF8
559encoding for L<Catalyst>:
560
561L<Catalyst::View::TT>, L<Catalyst::View::Mason>, L<Catalyst::View::HTML::Mason>,
562L<Catalyst::View::Xslate>
563
564See L<Catalyst::Upgrading> for additional information on L<Catalyst> extensions that require
565upgrades.
566
567In generally for the common views you should not need to do anything special. If your actual
568template files contain UTF8 literals you should set configuration on your View to enable that.
569For example in TT, if your template has actual UTF8 character in it you should do the following:
570
571 MyApp::View::TT->config(ENCODING => 'utf-8');
572
573However L<Catalyst::View::Xslate> wants to do the UTF8 encoding for you (We assume that the
574authors of that view did this as a workaround to the fact that until now encoding was not core
575to L<Catalyst>. So if you use that view, you either need to tell it to not encode, or you need
576to turn off encoding for Catalyst.
577
578 MyApp::View::Xslate->config(encode_body => 0);
579
580or
581
582 MyApp->config(encoding=>undef);
583
584Preference is to disable it in the View.
585
586Other views may be similar. You should review View documentation and test during upgrading.
587We tried to make sure most common views worked properly and noted all workaround but if we
588missed something please alert the development team (instead of introducing a local hack into
589your application that will mean nobody will ever upgrade it...).
590
aca337aa 591=head2 Setting the response from an external PSGI application.
592
593L<Catalyst::Response> allows one to set the response from an external L<PSGI> application.
594If you do this, and that external application sets a character set on the content-type, we
595C<clear_encoding> for the rest of the response. This is done to prevent double encoding.
596
597B<NOTE> Even if the character set of the content type is the same as the encoding set in
598$c->encoding, we still skip encoding. This is a regrettable difference from the general rule
599outlined above, where if the current character set is the same as the current encoding, we
600encode anyway. Nevertheless I think this is the correct behavior since the earlier rule exists
601only to support backward compatibility with L<Catalyst::View::TT>.
602
603In general if you want L<Catalyst> to handle encoding, you should avoid setting the content
604type character set since Catalyst will do so automatically based on the requested response
605encoding. Its best to request alternative encodings by setting $c->encoding and if you really
606want manual control of encoding you should always $c->clear_encoding so that programmers that
607come after you are very clear as to your intentions.
608
a09b49d2 609=head2 Disabling default UTF8 encoding
610
611You may encounter issues with your legacy code running under default UTF8 body encoding. If
612so you can disable this with the following configurations setting:
613
614 MyApp->config(encoding=>undef);
615
616Where C<MyApp> is your L<Catalyst> subclass.
617
b16a64af 618If you do not wish to disable all the Catalyst encoding features, you may disable specific
619features via two additional configuration options: 'skip_body_param_unicode_decoding'
620and 'skip_complex_post_part_handling'. The first will skip any attempt to decode POST
621parameters in the creating of body parameters and the second will skip creation of instances
622of L<Catalyst::Request::PartData> in the case that the multipart form upload contains parts
623with a mix of content character sets.
624
a09b49d2 625If you believe you have discovered a bug in UTF8 body encoding, I strongly encourage you to
626report it (and not try to hack a workaround in your local code). We also recommend that you
627regard such a workaround as a temporary solution. It is ideal if L<Catalyst> extension
b16a64af 628authors can start to count on L<Catalyst> doing the write thing for encoding.
a09b49d2 629
630=head1 Conclusion
631
632This document has attempted to be a complete review of how UTF8 and encoding works in the
633current version of L<Catalyst> and also to document known issues, gotchas and backward
634compatible hacks. Please report issues to the development team.
635
636=head1 Author
637
638John Napiorkowski L<jjnapiork@cpan.org|email:jjnapiork@cpan.org>
639
640=cut
641