Add note about new method in Upgrading.pod
[catagits/Catalyst-Runtime.git] / lib / Catalyst / Upgrading.pod
8c57b129 1=head1 NAME
3Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
eb7421fd 5=head1 Upgrading to Catalyst 5.90121
7A new C<log_stats> method has been added. This will only affect
8subclasses that have a method with this name added.
5e7e6b27 10=head1 Upgrading to Catalyst 5.90100
12We changed the way the middleware stash works so that it no longer localizes
13the PSGI env hashref. This was done to fix bugs where people set PSGI ENV hash
79fb8f95 14keys and found them to disappear in certain cases. It also means that now if
5e7e6b27 15a sub applications sets stash variables, that stash will now bubble up to the
16parent application. This may be a breaking change for you since previous
17versions of this code did not allow that. A workaround is to explicitly delete
18stash keys in your sub application before returning control to the parent
6b9f9ef7 21=head1 Upgrading to Catalyst 5.90097
23In older versions of Catalyst one could construct a L<URI> with a fragment (such as
24https://localhost/foo/bar#fragment) by using a '#' in the path or final argument, for
6b9f9ef7 27 $c->uri_for($action, 'foo#fragment');
29This behavior was never documented and would break if using the Unicode plugin, or when
30adding a query to the arguments:
32 $c->uri_for($action, 'foo#fragment', +{ a=>1, b=>2});
34would define a fragment like "#fragment?a=1&b=2".
36When we introduced UTF-8 encoding by default in Catalyst 5.9008x this side effect behavior
37was broken since we started encoding the '#' when it was part of the URI path.
39In version 5.90095 and 5.90096 we attempted to fix this, but all we managed to do was break
40people with URIs that included '#' as part of the path data, when it was not expected to
41be a fragment delimiter.
43In general L<Catalyst> prefers an explicit specification rather than relying on side effects
44or domain specific mini languages. As a result we are now defining how to set a fragment
45for a URI via ->uri_for:
47 $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment);
49If you are relying on the previous side effect behavior your URLs will now encode the '#'
50delimiter, which is going to be a breaking change for you. You need to alter your code
51to match the new specification or modify uri_for for your local case. Patches to solve
02336198 52this are very welcomed, as long as they don't break existing test cases.
a1dba4cf 54B<NOTE> If you are using the string form of the first argument:
02336198 55
56 $c->uri_for('/foo/bar#baz')
58construction, we do not attempt to encode this and it will make a URL with a
59fragment of 'baz'.
6b9f9ef7 61
62=head1 Upgrading to Catalyst 5.90095
e5ac67e5 63
64The method C<last_error> in L</Catalyst> was actually returning the first error. This has
65been fixed but there is a small chance it could be a breaking issue for you. If this gives
66you trouble changing to C<shift_errors> is the easiest workaround (although that does
67modify the error stack so if you are relying on that not being changed you should try something
68like @{$c->errors}[-1] instead. Since this method is relatively new and the cases when the
69error stack actually has more than one error in it, we feel the exposure is very low, but bug
70reports are very welcomed.
ec4d7259 72=head1 Upgrading to Catalyst 5.90090
74L<Catalyst::Utils> has a new method 'inject_component' which works the same as the method of
75the same name in L<CatalystX::InjectComponent>. You should start converting any
76use of the non core method in your code as future changes to Catalyst will be
79fb8f95 77synchronized to the core method first. We reserve the right to cease support
ec4d7259 78of the non core version should we reach a point in time where it cannot be
79properly supported as an external module. Luckily this should be a trivial
0fb9642d 80search and replace. Change all occurrences of:
ec4d7259 81
82 CatalystX::InjectComponent->inject(...)
86 Catalyst::Utils::inject_component(...)
88and we expect everything to work the same (we'd consider it not working the same
89to be a bug, and please report it.)
a791afa9 91We also cored features from L<CatalystX::RoleApplicator> to compose a role into the
92request, response and stats classes. The main difference is that with L<CatalystX::RoleApplicator>
93you did:
95 package MyApp;
97 use Catalyst;
98 use CatalystX::RoleApplicator;
100 __PACKAGE__->apply_request_class_roles(
101 qw/My::Request::Role Other::Request::Role/);
103Whereas now we have three class attributes, 'request_class_traits', 'response_class_traits'
104and 'stats_class_traits', so you use like this (note this value is an ArrayRef)
107 package MyApp;
109 use Catalyst;
111 __PACKAGE__->request_class_traits([qw/
112 My::Request::Role
113 Other::Request::Role/]);
115(And the same for response_class_traits and stats_class_traits. We left off the
116traits for Engine, since that class does a lot less nowadays, and dispatcher. If you
117used those and can share a use case, we'd be likely to support them.
3e560748 119Lastly, we have some of the feature from L<CatalystX::ComponentsFromConfig> in
120core. This should mostly work the same way in core, except for now the
121core version does not create an automatic base wrapper class for your configured
122components (it requires these to be catalyst components and injects them directly.
123So if you make heavy use of custom base classes in L<CatalystX::ComponentsFromConfig>
124you might need a bit of work to use the core version (although there is no reason
125to stop using L<CatalystX::ComponentsFromConfig> since it should continue to work
126fine and we'd consider issues with it to be bugs). Here's one way to map from
127L<CatalystX::ComponentsFromConfig> to core:
129In L<CatalystX::ComponentsFromConfig>:
131 MyApp->config(
132 'Model::MyClass' => {
044e7667 133 class => 'MyClass',
134 args => { %args },
3e560748 135
136 });
044e7667 138and now in core:
140 MyApp->config(
141 inject_components => {
142 'Model::MyClass' => { from_component => 'My::Class' },
143 },
144 'Model::MyClass' => {
145 %args
146 },
147 );
79fb8f95 149Although the core behavior requires more code, it better separates concerns
150as well as plays more into core Catalyst expectations of how configuration should
044e7667 151look.
3e560748 152
153Also we added a new develop console mode only warning when you call a component
154with arguments that don't expect or do anything meaningful with those args. Its
88e5a8b0 155possible if you are logging debug mode in production (please don't...) this
3e560748 156could add verbosity to those logs if you also happen to be calling for components
157and passing pointless arguments. We added this warning to help people not make this
158error and to better understand the component resolution flow.
7a504990 160=head1 Upgrading to Catalyst 5.90085
162In this version of Catalyst we made a small change to Chained Dispatching so
163that when two or more actions all have the same path specification AND they
164all have Args(0), we break the tie by choosing the last action defined, and
165not the first one defined. This was done to normalize Chaining to following
166the 'longest Path wins, and when several actions match the same Path specification
167we choose the last defined.' rule. Previously Args(0) was hard coded to be a special
168case such that the first action defined would match (which is not the case when
169Args is not zero.)
171Its possible that this could be a breaking change for you, if you had used
172action roles (custom or otherwise) to add additional matching rules to differentiate
173between several Args(0) actions that share the same root action chain. For
174example if you have code now like this:
176 sub check_default :Chained(/) CaptureArgs(0) { ... }
178 sub default_get :Chained('check_default') PathPart('') Args(0) GET {
179 pop->res->body('get3');
180 }
182 sub default_post :Chained('check_default') PathPart('') Args(0) POST {
183 pop->res->body('post3');
184 }
186 sub chain_default :Chained('check_default') PathPart('') Args(0) {
187 pop->res->body('chain_default');
188 }
190The way that chaining will work previous is that when two or more equal actions can
191match, the 'top' one wins. So if the request is "GET .../check_default" BOTH
192actions 'default_get' AND 'chain_default' would match. To break the tie in
193the case when Args is 0, we'd previous take the 'top' (or first defined) action.
194Unfortunately this treatment of Args(0) is special case. In all other cases
195we choose the 'last defined' action to break a tie. So this version of
196Catalyst changed the dispatcher to make Args(0) no longer a special case for
197breaking ties. This means that the above code must now become:
199 sub check_default :Chained(/) CaptureArgs(0) { ... }
201 sub chain_default :Chained('check_default') PathPart('') Args(0) {
202 pop->res->body('chain_default');
203 }
205 sub default_get :Chained('check_default') PathPart('') Args(0) GET {
206 pop->res->body('get3');
207 }
209 sub default_post :Chained('check_default') PathPart('') Args(0) POST {
210 pop->res->body('post3');
211 }
213If we want it to work as expected (for example we we GET to match 'default_get' and
214POST to match 'default_post' and any other http Method to match 'chain_default').
216In other words Arg(0) and chained actions must now follow the normal rule where
217in a tie the last defined action wins and you should place all your less defined
218or 'catch all' actions first.
220If this causes you trouble and you can't fix your code to conform, you may set the
221application configuration setting "use_chained_args_0_special_case" to true and
222that will revert you code to the previous behavior.
6cf77e11 224=head2 More backwards compatibility options with UTF-8 changes
79fb8f95 226In order to give better backwards compatibility with the 5.90080+ UTF-8 changes
6cf77e11 227we've added several configuration options around control of how we try to decode
228your URL keywords / query parameters.
232If true, then do not try to character decode any wide characters in your
79fb8f95 233request URL query or keywords. Most readings of the relevant specifications
6cf77e11 234suggest these should be UTF-* encoded, which is the default that L<Catalyst>
79fb8f95 235will use, however if you are creating a lot of URLs manually or have external
6cf77e11 236evil clients, this might cause you trouble. If you find the changes introduced
88e5a8b0 237in Catalyst version 5.90080+ break some of your query code, you may disable
6cf77e11 238the UTF-8 decoding globally using this configuration.
240This setting takes precedence over C<default_query_encoding> and
245By default we decode query and keywords in your request URL using UTF-8, which
79fb8f95 246is our reading of the relevant specifications. This setting allows one to
6cf77e11 247specify a fixed value for how to decode your query. You might need this if
248you are doing a lot of custom encoding of your URLs and not using UTF-8.
250This setting take precedence over C<decode_query_using_global_encoding>.
254Setting this to true will default your query decoding to whatever your
255general global encoding is (the default is UTF-8).
b8b29bac 258=head1 Upgrading to Catalyst 5.90080
260UTF8 encoding is now default. For temporary backwards compatibility, if this
261change is causing you trouble, you can disable it by setting the application
262configuration option to undef:
264 MyApp->config(encoding => undef);
266But please consider this a temporary measure since it is the intention that
267UTF8 is enabled going forwards and the expectation is that other ecosystem
268projects will assume this as well. At some point you application will not
269correctly function without this setting.
0d94e986 271As of 5.90084 we've added two additional configuration flags for more selective
272control over some encoding changes: 'skip_body_param_unicode_decoding' and
273'skip_complex_post_part_handling'. You may use these to more selectively
274disable new features while you are seeking a long term fix. Please review
275CONFIGURATION in L<Catalyst>.
d63cc9c8 277For further information, please see L<Catalyst::UTF8>
b8b29bac 279A number of projects in the wider ecosystem required minor updates to be able
280to work correctly. Here's the known list:
282L<Catalyst::View::TT>, L<Catalyst::View::Mason>, L<Catalyst::View::HTML::Mason>,
283L<Catalyst::View::Xslate>, L<Test::WWW::Mechanize::Catalyst>
285You will need to update to modern versions in most cases, although quite a few
286of these only needed minor test case and documentation changes so you will need
287to review the changelog of each one that is relevant to you to determine your
288true upgrade needs.
78acc1f7 290=head1 Upgrading to Catalyst 5.90060
292Starting in the v5.90059_001 development release, the regexp dispatch type is
293no longer automatically included as a dependency. If you are still using this
294dispatch type, you need to add L<Catalyst::DispatchType::Regex> into your build
297The standalone distribution of Regexp will be supported for the time being, but
298should we find that supporting it prevents us from moving L<Catalyst> forward
299in necessary ways, we reserve the right to drop that support. It is highly
300recommended that you use this last stage of deprecation to change your code.
ba7766f8 302=head1 Upgrading to Catalyst 5.90040
717fc5c9 303
8275d3b9 304=head2 Catalyst::Plugin::Unicode::Encoding is now core
306The previously stand alone Unicode support module L<Catalyst::Plugin::Unicode::Encoding>
307has been brought into core as a default plugin. Going forward, all you need is
308to add a configuration setting for the encoding type. For example:
310 package Myapp::Web;
312 use Catalyst;
314 __PACKAGE__->config( encoding => 'UTF-8' );
316Please note that this is different from the old stand alone plugin which applied
317C<UTF-8> encoding by default (that is, if you did not set an explicit
5fa5b709 318C<encoding> configuration value, it assumed you wanted UTF-8). In order to
8275d3b9 319preserve backwards compatibility you will need to explicitly turn it on via the
320configuration setting. THIS MIGHT CHANGE IN THE FUTURE, so please consider
321starting to test your application with proper UTF-8 support and remove all those
322crappy hacks you munged into the code because you didn't know the Plugin
323existed :)
325For people that are using the Plugin, you will note a startup warning suggesting
326that you can remove it from the plugin list. When you do so, please remember to
327add the configuration setting, since you can no longer rely on the default being
328UTF-8. We'll add it for you if you continue to use the stand alone plugin and
329we detect this, but this backwards compatibility shim will likely be removed in
330a few releases (trying to clean up the codebase after all).
332If you have trouble with any of this, please bring it to the attention of the
333Catalyst maintainer group.
335=head2 basic async and event loop support
717fc5c9 337This version of L<Catalyst> offers some support for using L<AnyEvent> and
e37f92f5 338L<IO::Async> event loops in your application. These changes should work
339fine for most applications however if you are already trying to perform
340some streaming, minor changes in this area of the code might affect your
4e6e0ab2 341functionality. Please see L<Catalyst::Response\write_fh> for more and for a
342basic example.
8275d3b9 343
344We consider this feature experimental. We will try not to break it, but we
345reserve the right to make necessary changes to fix major issues that people
346run into when the use this functionality in the wild.
717fc5c9 347
ba7766f8 348=head1 Upgrading to Catalyst 5.90030
350=head2 Regex dispatch type is deprecated.
352The Regex dispatchtype (L<Catalyst::DispatchType::Regex>) has been deprecated.
354You are encouraged to move your application to Chained dispatch (L<Catalyst::DispatchType::Chained>).
356If you cannot do so, please add a dependency to Catalyst::DispatchType::Regex to your application's
dacd8b0e 359=head1 Upgrading to Catalyst 5.9
5d5f4a73 360
e6006848 361The major change is that L<Plack>, a toolkit for using the L<PSGI>
862a7989 362specification, now replaces most of the subclasses of L<Catalyst::Engine>. If
e6006848 363you are using one of the standard subclasses of L<Catalyst::Engine> this
364should be a straightforward upgrade for you. It was a design goal for
365this release to preserve as much backwards compatibility as possible.
366However, since L<Plack> is different from L<Catalyst::Engine>, it is
367possible that differences exist for edge cases. Therefore, we recommend
368that care be taken with this upgrade and that testing should be greater
369than would be the case with a minor point update. Please inform the
370Catalyst developers of any problems so that we can fix them and
371incorporate tests.
5d5f4a73 372
773b3b08 373It is highly recommended that you become familiar with the L<Plack> ecosystem
ae908e7e 374and documentation. Being able to take advantage of L<Plack> development and
375middleware is a major bonus to this upgrade. Documentation about how to
376take advantage of L<Plack::Middleware> by writing your own C<< .psgi >> file
377is contained in L<Catalyst::PSGI>.
5d5f4a73 378
e6006848 379If you have created a custom subclass of L<Catalyst:Engine>, you will
380need to convert it to be a subclass of L<Plack::Handler>.
5d5f4a73 381
382If you are using the L<Plack> engine, L<Catalyst::Engine::PSGI>, this new
773b3b08 383release supersedes that code.
5d5f4a73 384
e6006848 385If you are using a subclass of L<Catalyst::Engine> that is aimed at
386nonstandard or internal/testing uses, such as
387L<Catalyst::Engine::Embeddable>, you should still be able to continue
388using that engine.
5d5f4a73 389
390Advice for specific subclasses of L<Catalyst::Engine> follows:
93d60cae 392=head2 Upgrading the FastCGI Engine
5d5f4a73 393
e6006848 394No upgrade is needed if your script is already upgraded
395to use L<Catalyst::Script::FastCGI>.
5d5f4a73 396
93d60cae 397=head2 Upgrading the mod_perl / Apache Engines
5d5f4a73 398
e6006848 399The engines that are built upon the various iterations of mod_perl,
14148e06 400L<Catalyst::Engine::Apache::MP13> (for mod_perl 1, and Apache 1.x) and
862a7989 401L<Catalyst::Engine::Apache2::MP20> (for mod_perl 2, and Apache 2.x),
bd85860b 402should be seamless upgrades and will work using L<Plack::Handler::Apache1>
14148e06 403or L<Plack::Handler::Apache2> as required.
5d5f4a73 404
e6006848 405L<Catalyst::Engine::Apache2::MP19>, however, is no longer supported, as
862a7989 406Plack does not support mod_perl version 1.99. This is unlikely to be a
407problem for anyone, as 1.99 was a brief beta-test release for mod_perl
4082, and all users of mod_perl 1.99 are encouraged to upgrade to a
409supported release of Apache 2 and mod_perl 2.
5d5f4a73 410
93d60cae 411=head2 Upgrading the HTTP Engine
5d5f4a73 412
040835f0 413The default development server that comes with the L<Catalyst> distribution
414should continue to work as expected with no changes as long as your C<myapp_server>
415script is upgraded to use L<Catalyst::Script::HTTP>.
5d5f4a73 416
93d60cae 417=head2 Upgrading the CGI Engine
5d5f4a73 418
697a3e9e 419If you were using L<Catalyst::Engine::CGI> there is no upgrade needed if your
e6006848 script is already upgraded to use L<Catalyst::Script::CGI>.
5d5f4a73 421
cf8eab35 422=head2 Upgrading Catalyst::Engine::HTTP::Prefork
5d5f4a73 423
040835f0 424If you were using L<Catalyst::Engine::HTTP::Prefork> then L<Starman>
da9eab5a 425is automatically loaded. You should (at least) change your C<Makefile.PL>
426to depend on Starman.
0ea8962d 427
da9eab5a 428You can regenerate your C<> script with C<>
429and implement a C<MyApp::Script::Server> class that looks like this:
431 package MyApp::Script::Server;
432 use Moose;
433 use namespace::autoclean;
435 extends 'CatalystX::Script::Server::Starman';
437 1;
e6006848 439This takes advantage of the new script system, and will add a number of
440options to the standard server script as extra options are added by
da9eab5a 442
443More information about these options can be seen at
446An alternate route to implement this functionality is to write a simple .psgi
e6006848 447file for your application, and then use the L<plackup> utility to start the
da9eab5a 448server.
5d5f4a73 449
93d60cae 450=head2 Upgrading the PSGI Engine
5d5f4a73 451
e6006848 452If you were using L<Catalyst::Engine::PSGI>, this new release supersedes
453this engine in supporting L<Plack>. By default the Engine is now always
454L<Plack>. As a result, you can remove the dependency on
455L<Catalyst::Engine::PSGI> in your C<Makefile.PL>.
8f912f0b 456
457Applications that were using L<Catalyst::Engine::PSGI>
458previously should entirely continue to work in this release with no changes.
e6006848 460However, if you have an C<app.psgi> script, then you no longer need to
461specify the PSGI engine. Instead, the L<Catalyst> application class now
462has a new method C<psgi_app> which returns a L<PSGI> compatible coderef
463which you can wrap in the middleware of your choice.
8f912f0b 464
465Catalyst will use the .psgi for your application if it is located in the C<home>
e6006848 466directory of the application.
697a3e9e 467
93a57b4b 468For example, if you were using L<Catalyst::Engine::PSGI> in the past, you will
8f912f0b 469have written (or generated) a C<script/myapp.psgi> file similar to this one:
697a3e9e 470
471 use Plack::Builder;
472 use MyCatalytApp;
474 MyCatalystApp->setup_engine('PSGI');
476 builder {
477 enable ... # enable your desired middleware
478 sub { MyCatalystApp->run(@_) };
479 };
8f912f0b 481Instead, you now say:
697a3e9e 482
483 use Plack::Builder;
484 use MyCatalystApp;
486 builder {
487 enable ... #enable your desired middleware
75d68821 488 MyCatalystApp->psgi_app;
697a3e9e 489 };
5d5f4a73 490
34effbc7 491In the simplest case:
8f912f0b 492
34effbc7 493 MyCatalystApp->setup_engine('PSGI');
494 my $app = sub { MyCatalystApp->run(@_) }
34effbc7 498 my $app = MyCatalystApp->psgi_app(@_);
502 my $app = sub { MyCatalystApp->psgi_app(@_) };
503 # If you make ^^ this mistake, your app won't work, and will confuse the hell out of you!
e6006848 505You can now move C<< script/myapp.psgi >> to C<< myapp.psgi >>, and the built-in
773b3b08 506Catalyst scripts and your test suite will start using your .psgi file.
ad15c817 507
e6006848 508B<NOTE:> If you rename your .psgi file without these modifications, then
509any tests run via L<Catalyst::Test> will not be compatible with the new
510release, and will result in the development server starting, rather than
511the expected test running.
93a57b4b 512
c47cd2ce 513B<NOTE:> If you are directly accessing C<< $c->req->env >> to get the PSGI
514environment then this accessor is moved to C<< $c->engine->env >>,
515you will need to update your code.
e6006848 517=head2 Engines which are known to be broken
93a57b4b 518
e6006848 519The following engines B<DO NOT> work as of Catalyst version 5.9. The
520core team will be happy to work with the developers and/or users of
521these engines to help them port to the new Plack/Engine system, but for
522now, applications which are currently using these engines B<WILL NOT>
523run without modification to the engine code.
93a57b4b 524
527=item Catalyst::Engine::Wx
ad15c817 529=item Catalyst::Engine::Zeus
531=item Catalyst::Engine::JobQueue::POE
533=item Catalyst::Engine::XMPP2
535=item Catalyst::Engine::SCGI
93a57b4b 537=back
5d5f4a73 539=head2 Engines with unknown status
e6006848 541The following engines are untested or have unknown compatibility.
542Reports are highly encouraged:
5d5f4a73 543
ad15c817 544=over
546=item Catalyst::Engine::Mojo
e6006848 548=item Catalyst::Engine::Server (marked as Deprecated)
ad15c817 549
e6006848 550=item Catalyst::Engine::HTTP::POE (marked as Deprecated)
ad15c817 551
5d5f4a73 553
3f22de0b 554=head2 Plack functionality
040835f0 555
3f22de0b 556See L<Catalyst::PSGI>.
0aafa77a 557
dacd8b0e 558=head2 Tests in 5.9
4db14a9a 559
e6006848 560Tests should generally work the same in Catalyst 5.9, but there are
561some differences.
4db14a9a 562
e6006848 563Previously, if using L<Catalyst::Test> and doing local requests (against
564a local server), if the application threw an exception then this
565exception propagated into the test.
4db14a9a 566
e6006848 567This behavior has been removed, and now a 500 response will be returned
568to the test. This change standardizes behavior, so that local test
569requests behave similarly to remote requests.
4db14a9a 570
7e2ec16e 571=head1 Upgrading to Catalyst 5.80
5687c7f9 573Most applications and plugins should run unaltered on Catalyst 5.80.
7e2ec16e 574
8f61d649 575However, a lot of refactoring work has taken place, and several changes have
1a98f036 576been made which could cause incompatibilities. If your application or plugin
8f61d649 577is using deprecated code, or relying on side effects, then you could have
ba03ccca 578issues upgrading to this release.
5687c7f9 579
cf8eab35 580Most issues found with existing components have been easy to
8f61d649 581solve. This document provides a complete description of behavior changes
582which may cause compatibility issues, and of new Catalyst warnings which
773b3b08 583might be unclear.
7e2ec16e 584
8f61d649 585If you think you have found an upgrade-related issue which is not covered in
586this document, please email the Catalyst list to discuss the problem.
7e2ec16e 587
85f0a66f 588=head1 Moose features
8f61d649 590=head2 Application class roles
85f0a66f 591
8f61d649 592You can only apply method modifiers after the application's C<< ->setup >>
85f0a66f 593method has been called. This means that modifiers will not work with methods
773b3b08 594run during the call to C<< ->setup >>.
85f0a66f 595
a6eb852a 596See L<Catalyst::Manual::ExtendingCatalyst> for more information about using
597L<Moose> in your applications.
85f0a66f 599=head2 Controller actions in Moose roles
d76c88f3 601You can use L<MooseX::MethodAttributes::Role> if you want to declare actions
602inside Moose roles.
85f0a66f 603
d935773d 604=head2 Using Moose in Components
606The correct way to use Moose in a component in a both forward and backwards
607compatible way is:
609 package TestApp::Controller::Root;
610 use Moose;
611 BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
613See L<Components which inherit from Moose::Object before Catalyst::Component>.
8f61d649 615=head1 Known backwards compatibility breakages
7e2ec16e 616
8f61d649 617=head2 Applications in a single file
85f0a66f 618
619Applications must be in their own file, and loaded at compile time. This
8f61d649 620issue generally only affects the tests of CPAN distributions. Your
621application will fail if you try to define an application inline in a
622block, and use plugins which supply a C< new > method, then use that
623application latter in tests within the same file.
85f0a66f 624
625This is due to the fact that Catalyst is inlining a new method on your
8f61d649 626application class allowing it to be compatible with Moose. The method
627used to do this changed in 5.80004 to avoid the possibility of reporting
628an 'Unknown Error' if your application failed to compile.
85f0a66f 629
38f90e49 630=head2 Issues with Class::C3
8f61d649 632Catalyst 5.80 uses the L<Algorithm::C3> method dispatch order. This is
633built into Perl 5.10, and comes via L<Class::C3> for Perl 5.8. This
634replaces L<NEXT> with L<Class::C3::Adopt::NEXT>, forcing all components
635to resolve methods using C3, rather than the unpredictable dispatch
636order of L<NEXT>.
38f90e49 637
cf8eab35 638This issue manifests itself by your application failing to start due to an
5d06547d 639error message about having a non-linear @ISA.
8f61d649 641The Catalyst plugin most often causing this is
642L<Catalyst::Plugin::Session::Store::FastMmap> - if you are using this
643plugin and see issues, then please upgrade your plugins, as it has been
644fixed. Note that Makefile.PL in the distribution will warn about known
645incompatible components.
5d06547d 646
647This issue can, however, be found in your own application - the only solution is
648to go through each base class of the class the error was reported against, until
649you identify the ones in conflict, and resolve them.
651To be able to generate a linear @ISA, the list of superclasses for each
652class must be resolvable using the C3 algorithm. Unfortunately, when
653superclasses are being used as mixins (to add functionality used in your class),
ae7da8f5 654and with multiple inheritance, it is easy to get this wrong.
38f90e49 655
656Most common is the case of:
658 package Component1; # Note, this is the common case
659 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
8f61d649 661 package Component2; # Accidentally saying it this way causes a failure
38f90e49 662 use base qw/Class::Data::Inheritable Class::Accessor::Fast/;
664 package GoesBang;
665 use base qw/Component1 Component2/;
5d06547d 667Any situation like this will cause your application to fail to start.
38f90e49 668
8f61d649 669For additional documentation about this issue, and how to resolve it, see
5d06547d 670L<Class::C3::Adopt::NEXT>.
38f90e49 671
6f04e56a 672=head2 Components which inherit from Moose::Object before Catalyst::Component
7e2ec16e 673
6f04e56a 674Moose components which say:
7e2ec16e 675
6f04e56a 676 package TestApp::Controller::Example;
677 use Moose;
845bfcd2 678 extends qw/Moose::Object Catalyst::Component/;
7e2ec16e 679
8f61d649 680to use the constructor provided by Moose, while working (if you do some hacks
1a98f036 681with the C< BUILDARGS > method), will not work with Catalyst 5.80 as
6f04e56a 682C<Catalyst::Component> inherits from C<Moose::Object>, and so C< @ISA > fails
25f61108 683to linearize.
6f04e56a 684
6f04e56a 685The correct way to use Moose in a component in a both forward and backwards
686compatible way is:
688 package TestApp::Controller::Root;
689 use Moose;
690 BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
ba03ccca 692Note that the C< extends > declaration needs to occur in a begin block for
3df46b1b 693L<attributes> to operate correctly.
d935773d 695This way you do not inherit directly from C<Moose::Object>
696yourself. Having components which do not inherit their constructor from
697C<Catalyst::Component> is B<unsupported>, and has never been recommended,
698therefore you're on your own if you're using this technique. You'll need
699to detect the version of Catalyst your application is running, and deal
700with it appropriately.
eaae9a92 702You also don't get the L<Moose::Object> constructor, and therefore attribute
703initialization will not work as normally expected. If you want to use Moose
3df46b1b 704attributes, then they need to be made lazy to correctly initialize.
706Note that this only applies if your component needs to maintain component
707backwards compatibility for Catalyst versions before 5.71001 - in 5.71001
708attributes work as expected, and the BUILD method is called normally
eaae9a92 709(although BUILDARGS is not).
3df46b1b 710
711If you depend on Catalyst 5.8, then B<all> Moose features work as expected.
8566c0de 712
d935773d 713You will also see this issue if you do the following:
715 package TestApp::Controller::Example;
716 use Moose;
717 use base 'Catalyst::Controller';
719as C< use base > appends to @ISA.
e11cac87 721=head3 use Moose in MyApp
723Similar to the above, this will also fail:
725 package MyApp;
726 use Moose;
727 use Catalyst qw/
728 ConfigLoader
729 /;
730 __PACKAGE__->setup;
732If you need to use Moose in your application class (e.g. for method modifiers
8f61d649 733etc.) then the correct technique is:
e11cac87 734
735 package MyApp;
736 use Moose;
5b6f82d2 737 use Catalyst;
e11cac87 739 extends 'Catalyst';
5b6f82d2 740
741 __PACKAGE__->config( name => 'MyApp' );
e11cac87 742 __PACKAGE__->setup(qw/
743 ConfigLoader
744 /);
04a48104 746=head2 Anonymous closures installed directly into the symbol table
748If you have any code which installs anonymous subroutine references directly
749into the symbol table, you may encounter breakages. The simplest solution is
750to use L<Sub::Name> to name the subroutine. Example:
e11cac87 752 # Original code, likely to break:
1a98f036 753 my $full_method_name = join('::', $package_name, $method_name);
04a48104 754 *$full_method_name = sub { ... };
e11cac87 756 # Fixed Code
04a48104 757 use Sub::Name 'subname';
758 my $full_method_name = join('::',$package_name, $method_name);
759 *$full_method_name = subname $full_method_name, sub { ... };
8f61d649 761Additionally, you can take advantage of Catalyst's use of L<Class::MOP> and
762install the closure using the appropriate metaclass. Example:
04a48104 763
764 use Class::MOP;
765 my $metaclass = Moose::Meta::Class->initialize($package_name);
766 $metaclass->add_method($method_name => sub { ... });
780654ad 768=head2 Hooking into application setup
8f61d649 770To execute code during application start-up, the following snippet in
780654ad 771used to work:
773 sub setup {
774 my ($class, @args) = @_;
775 $class->NEXT::setup(@args);
776 ... # things to do after the actual setup
777 }
8f61d649 779With Catalyst 5.80 this won't work anymore, because Catalyst no longer
780uses for method resolution. The functionality was only ever
781originally operational as L<NEXT> remembers what methods have already
782been called, and will not call them again.
780654ad 783
1a98f036 784Using this now causes infinite recursion between MyApp::setup and
785Catalyst::setup, due to other backwards compatibility issues related to how
e6c5b548 786plugin setup works. Moose method modifiers like C<< before|after|around setup
1a98f036 787=> sub { ... }; >> also will not operate correctly on the setup method.
780654ad 788
789The right way to do it is this:
791 after setup_finalize => sub {
792 ... # things to do after the actual setup
793 };
ade00972 795The setup_finalize hook was introduced as a way to avoid this issue.
1a98f036 796
e11cac87 797=head2 Components with a new method which returns false
7e2ec16e 798
8dd2f514 799Previously, if you had a component which inherited from Catalyst::COMPONENT,
8f61d649 800but overrode the new method to return false, then your class's configuration
8dd2f514 801would be blessed into a hash on your behalf, and this would be returned from
a87f5aa5 802the COMPONENT method.
7e2ec16e 803
8f61d649 804This behavior makes no sense, and so has been removed. Implementing your own
805C< new > method in components is B<highly> discouraged. Instead, you should
806inherit the new method from Catalyst::Component, and use Moose's BUILD
1a98f036 807functionality and/or Moose attributes to perform any construction work
808necessary for your class.
7e2ec16e 809
810=head2 __PACKAGE__->mk_accessor('meta');
e11cac87 812Won't work due to a limitation of L<Moose>. This is currently being fixed
813inside Moose.
7e2ec16e 814
815=head2 Class::Data::Inheritable side effects
8dd2f514 817Previously, writing to a class data accessor would copy the accessor method
818down into your package.
8f61d649 820This behavior has been removed. While the class data is still stored
8dd2f514 821per-class, it is stored on the metaclass of the class defining the accessor.
7e2ec16e 822
8f61d649 823Therefore anything relying on the side effect of the accessor being copied down
8dd2f514 824will be broken.
7e2ec16e 825
1a98f036 826The following test demonstrates the problem:
8dd2f514 827
828 {
829 package BaseClass;
830 use base qw/Class::Data::Inheritable/;
831 __PACKAGE__->mk_classdata('foo');
832 }
834 {
835 package Child;
836 use base qw/BaseClass/;
837 }
839 BaseClass->foo('base class');
840 Child->foo('sub class');
eaae9a92 841
e11cac87 842 use Test::More;
8dd2f514 843 isnt(BaseClass->can('foo'), Child->can('foo'));
7e2ec16e 844
f4dda4a8 845=head2 Extending Catalyst::Request or other classes in an ad hoc manner using mk_accessors
7e2ec16e 846
8dd2f514 847Previously, it was possible to add additional accessors to Catalyst::Request
848(or other classes) by calling the mk_accessors class method.
7e2ec16e 849
8f61d649 850This is no longer supported - users should make a subclass of the class whose
851behavior they would like to change, rather than globally polluting the
e11cac87 852Catalyst objects.
8be895a7 853
10011c19 854=head2 Confused multiple inheritance with Catalyst::Component::COMPONENT
8be895a7 855
8f61d649 856Previously, Catalyst's COMPONENT method would delegate to the method on
857the right hand side, which could then delegate back again with
858NEXT. This is poor practice, and in addition, makes no sense with C3
859method dispatch order, and is therefore no longer supported.
bcc773b9 860
ba03ccca 861If a COMPONENT method is detected in the inheritance hierarchy to the right
bcc773b9 862hand side of Catalyst::Component::COMPONENT, then the following warning
863message will be emitted:
7e2ec16e 864
8dd2f514 865 There is a COMPONENT method resolving after Catalyst::Component
5687c7f9 866 in ${next_package}.
8dd2f514 867
8f61d649 868The correct fix is to re-arrange your class's inheritance hierarchy so that the
bcc773b9 869COMPONENT method you would like to inherit is the first (left-hand most)
870COMPONENT method in your @ISA.
7e2ec16e 871
7e9340de 872=head2 Development server relying on environment variables
874Previously, the development server would allow propagation of system
875environment variables into the request environment, this has changed with the
876adoption of Plack. You can use L<Plack::Middleware::ForceEnv> to achieve the
877same effect.
c571d2c8 879=head1 WARNINGS
63b546b1 881=head2 Actions in your application class
883Having actions in your application class will now emit a warning at application
e256d0e1 884startup as this is deprecated. It is highly recommended that these actions are moved
63b546b1 885into a MyApp::Controller::Root (as demonstrated by the scaffold application
5fa5b709 886generated by
da73c6af 887
e256d0e1 888This warning, also affects tests. You should move actions in your test,
889creating a myTest::Controller::Root, like the following example:
da73c6af 890
891 package MyTest::Controller::Root;
95a52a01 892
da73c6af 893 use strict;
894 use warnings;
95a52a01 895
da73c6af 896 use parent 'Catalyst::Controller';
95a52a01 897
da73c6af 898 __PACKAGE__->config(namespace => '');
95a52a01 899
da73c6af 900 sub action : Local {
901 my ( $self, $c ) = @_;
5fa5b709 902 $c->do_something;
da73c6af 903 }
95a52a01 904
da73c6af 905 1;
63b546b1 906
ac9279b0 907=head2 ::[MVC]:: naming scheme
909Having packages called MyApp::[MVC]::XX is deprecated and can no longer be generated
912This is still supported, but it is recommended that you rename your application
913components to Model/View/Controller.
915A warning will be issued at application startup if the ::[MVC]:: naming scheme is
916in use.
ade00972 918=head2 Catalyst::Base
8f61d649 920Any code using L<Catalyst::Base> will now emit a warning; this
921module will be removed in a future release.
ade00972 922
c571d2c8 923=head2 Methods in Catalyst::Dispatcher
8f61d649 925The following methods in Catalyst::Dispatcher are implementation
926details, which may change in the 5.8X release series, and therefore their use
bcc773b9 927is highly deprecated.
c571d2c8 928
8dd2f514 931=item tree
c571d2c8 932
8dd2f514 933=item dispatch_types
c571d2c8 934
8dd2f514 935=item registered_dispatch_types
c571d2c8 936
8dd2f514 937=item method_action_class
c571d2c8 938
8dd2f514 939=item action_hash
c571d2c8 940
941=item container_hash
945The first time one of these methods is called, a warning will be emitted:
7e2ec16e 946
bcc773b9 947 Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
dacd8b0e 948 this will be removed in Catalyst 5.9
7e2ec16e 949
c571d2c8 950You should B<NEVER> be calling any of these methods from application code.
8f61d649 952Plugin authors and maintainers whose plugins currently call these methods
8f5a2bd9 953should change to using the public API, or, if you do not feel the public API
8f61d649 954adequately supports your use case, please email the development list to
8f5a2bd9 955discuss what API features you need so that you can be appropriately supported.
7e2ec16e 956
95b20422 957=head2 Class files with names that don't correspond to the packages they define
7e2ec16e 958
e11cac87 959In this version of Catalyst, if a component is loaded from disk, but no
ba03ccca 960symbols are defined in that component's name space after it is loaded, this
bcc773b9 961warning will be issued:
7e2ec16e 962
bcc773b9 963 require $class was successful but the package is not defined.
7e2ec16e 964
8f61d649 965This is to protect against confusing bugs caused by mistyping package names,
bcc773b9 966and will become a fatal error in a future version.
968Please note that 'inner packages' (via L<Devel::InnerPackage>) are still fully
8f61d649 969supported; this warning is only issued when component file naming does not map
bcc773b9 970to B<any> of the packages defined within that component.
7e2ec16e 971
5687c7f9 972=head2 $c->plugin method
25f61108 974Calling the plugin method is deprecated, and calling it at run time is B<highly
8dd2f514 975deprecated>.
7e2ec16e 976
95a52a01 977Instead you are recommended to use L<Catalyst::Model::Adaptor> or similar to
ba03ccca 978compose the functionality you need outside of the main application name space.
7e2ec16e 979
4e68badc 980Calling the plugin method will not be supported past Catalyst 5.81.
bcc773b9 981
7e2ec16e 982=cut
4e68badc 983