1Catalyst::Upgrading(3)User Contributed Perl DocumentationCatalyst::Upgrading(3)
2
6 Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
7
9 We changed the way the middleware stash works so that it no longer
10 localizes the PSGI env hashref. This was done to fix bugs where people
11 set PSGI ENV hash keys and found them to disappear in certain cases.
12 It also means that now if a sub applications sets stash variables, that
13 stash will now bubble up to the parent application. This may be a
14 breaking change for you since previous versions of this code did not
15 allow that. A workaround is to explicitly delete stash keys in your
16 sub application before returning control to the parent application.
17
19 In older versions of Catalyst one could construct a URI with a fragment
20 (such as https://localhost/foo/bar#fragment) by using a '#' in the path
21 or final argument, for example:
22 $c->uri_for($action, 'foo#fragment');
24 This behavior was never documented and would break if using the Unicode
26 plugin, or when adding a query to the arguments:
27 $c->uri_for($action, 'foo#fragment', +{ a=>1, b=>2});
29 would define a fragment like "#fragment?a=1&b=2".
31 When we introduced UTF-8 encoding by default in Catalyst 5.9008x this
33 side effect behavior was broken since we started encoding the '#' when
34 it was part of the URI path.
35 In version 5.90095 and 5.90096 we attempted to fix this, but all we
37 managed to do was break people with URIs that included '#' as part of
38 the path data, when it was not expected to be a fragment delimiter.
39 In general Catalyst prefers an explicit specification rather than
41 relying on side effects or domain specific mini languages. As a result
42 we are now defining how to set a fragment for a URI via ->uri_for:
43 $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment);
45 If you are relying on the previous side effect behavior your URLs will
47 now encode the '#' delimiter, which is going to be a breaking change
48 for you. You need to alter your code to match the new specification or
49 modify uri_for for your local case. Patches to solve this are very
50 welcomed, as long as they don't break existing test cases.
51 NOTE If you are using the string form of the first argument:
53 $c->uri_for('/foo/bar#baz')
55 construction, we do not attempt to encode this and it will make a URL
57 with a fragment of 'baz'.
58
60 The method "last_error" in "Catalyst" was actually returning the first
61 error. This has been fixed but there is a small chance it could be a
62 breaking issue for you. If this gives you trouble changing to
63 "shift_errors" is the easiest workaround (although that does modify the
64 error stack so if you are relying on that not being changed you should
65 try something like @{$c->errors}[-1] instead. Since this method is
66 relatively new and the cases when the error stack actually has more
67 than one error in it, we feel the exposure is very low, but bug reports
68 are very welcomed.
69
71 Catalyst::Utils has a new method 'inject_component' which works the
72 same as the method of the same name in CatalystX::InjectComponent. You
73 should start converting any use of the non core method in your code as
74 future changes to Catalyst will be synchronized to the core method
75 first. We reserve the right to cease support of the non core version
76 should we reach a point in time where it cannot be properly supported
77 as an external module. Luckily this should be a trivial search and
78 replace. Change all occurrences of:
79 CatalystX::InjectComponent->inject(...)
81 Into
83 Catalyst::Utils::inject_component(...)
85 and we expect everything to work the same (we'd consider it not working
87 the same to be a bug, and please report it.)
88 We also cored features from CatalystX::RoleApplicator to compose a role
90 into the request, response and stats classes. The main difference is
91 that with CatalystX::RoleApplicator you did:
92 package MyApp;
94 use Catalyst;
96 use CatalystX::RoleApplicator;
97 __PACKAGE__->apply_request_class_roles(
99 qw/My::Request::Role Other::Request::Role/);
100 Whereas now we have three class attributes, 'request_class_traits',
102 'response_class_traits' and 'stats_class_traits', so you use like this
103 (note this value is an ArrayRef)
104 package MyApp;
106 use Catalyst;
108 __PACKAGE__->request_class_traits([qw/
110 My::Request::Role
111 Other::Request::Role/]);
112 (And the same for response_class_traits and stats_class_traits. We
114 left off the traits for Engine, since that class does a lot less
115 nowadays, and dispatcher. If you used those and can share a use case,
116 we'd be likely to support them.
117 Lastly, we have some of the feature from
119 CatalystX::ComponentsFromConfig in core. This should mostly work the
120 same way in core, except for now the core version does not create an
121 automatic base wrapper class for your configured components (it
122 requires these to be catalyst components and injects them directly. So
123 if you make heavy use of custom base classes in
124 CatalystX::ComponentsFromConfig you might need a bit of work to use the
125 core version (although there is no reason to stop using
126 CatalystX::ComponentsFromConfig since it should continue to work fine
127 and we'd consider issues with it to be bugs). Here's one way to map
128 from CatalystX::ComponentsFromConfig to core:
129 In CatalystX::ComponentsFromConfig:
131 MyApp->config(
133 'Model::MyClass' => {
134 class => 'MyClass',
135 args => { %args },
136 });
138 and now in core:
140 MyApp->config(
142 inject_components => {
143 'Model::MyClass' => { from_component => 'My::Class' },
144 },
145 'Model::MyClass' => {
146 %args
147 },
148 );
149 Although the core behavior requires more code, it better separates
151 concerns as well as plays more into core Catalyst expectations of how
152 configuration should look.
153 Also we added a new develop console mode only warning when you call a
155 component with arguments that don't expect or do anything meaningful
156 with those args. Its possible if you are logging debug mode in
157 production (please don't...) this could add verbosity to those logs if
158 you also happen to be calling for components and passing pointless
159 arguments. We added this warning to help people not make this error
160 and to better understand the component resolution flow.
161
163 In this version of Catalyst we made a small change to Chained
164 Dispatching so that when two or more actions all have the same path
165 specification AND they all have Args(0), we break the tie by choosing
166 the last action defined, and not the first one defined. This was done
167 to normalize Chaining to following the 'longest Path wins, and when
168 several actions match the same Path specification we choose the last
169 defined.' rule. Previously Args(0) was hard coded to be a special case
170 such that the first action defined would match (which is not the case
171 when Args is not zero.)
172 Its possible that this could be a breaking change for you, if you had
174 used action roles (custom or otherwise) to add additional matching
175 rules to differentiate between several Args(0) actions that share the
176 same root action chain. For example if you have code now like this:
177 sub check_default :Chained(/) CaptureArgs(0) { ... }
179 sub default_get :Chained('check_default') PathPart('') Args(0) GET {
181 pop->res->body('get3');
182 }
183 sub default_post :Chained('check_default') PathPart('') Args(0) POST {
185 pop->res->body('post3');
186 }
187 sub chain_default :Chained('check_default') PathPart('') Args(0) {
189 pop->res->body('chain_default');
190 }
191 The way that chaining will work previous is that when two or more equal
193 actions can match, the 'top' one wins. So if the request is "GET
194 .../check_default" BOTH actions 'default_get' AND 'chain_default' would
195 match. To break the tie in the case when Args is 0, we'd previous take
196 the 'top' (or first defined) action. Unfortunately this treatment of
197 Args(0) is special case. In all other cases we choose the 'last
198 defined' action to break a tie. So this version of Catalyst changed
199 the dispatcher to make Args(0) no longer a special case for breaking
200 ties. This means that the above code must now become:
201 sub check_default :Chained(/) CaptureArgs(0) { ... }
203 sub chain_default :Chained('check_default') PathPart('') Args(0) {
205 pop->res->body('chain_default');
206 }
207 sub default_get :Chained('check_default') PathPart('') Args(0) GET {
209 pop->res->body('get3');
210 }
211 sub default_post :Chained('check_default') PathPart('') Args(0) POST {
213 pop->res->body('post3');
214 }
215 If we want it to work as expected (for example we we GET to match
217 'default_get' and POST to match 'default_post' and any other http
218 Method to match 'chain_default').
219 In other words Arg(0) and chained actions must now follow the normal
221 rule where in a tie the last defined action wins and you should place
222 all your less defined or 'catch all' actions first.
223 If this causes you trouble and you can't fix your code to conform, you
225 may set the application configuration setting
226 "use_chained_args_0_special_case" to true and that will revert you code
227 to the previous behavior.
228 More backwards compatibility options with UTF-8 changes
230 In order to give better backwards compatibility with the 5.90080+ UTF-8
231 changes we've added several configuration options around control of how
232 we try to decode your URL keywords / query parameters.
233 "do_not_decode_query"
235 If true, then do not try to character decode any wide characters in
237 your request URL query or keywords. Most readings of the relevant
238 specifications suggest these should be UTF-* encoded, which is the
239 default that Catalyst will use, however if you are creating a lot of
240 URLs manually or have external evil clients, this might cause you
241 trouble. If you find the changes introduced in Catalyst version
242 5.90080+ break some of your query code, you may disable the UTF-8
243 decoding globally using this configuration.
244 This setting takes precedence over "default_query_encoding" and
246 "decode_query_using_global_encoding"
247 "default_query_encoding"
249 By default we decode query and keywords in your request URL using
251 UTF-8, which is our reading of the relevant specifications. This
252 setting allows one to specify a fixed value for how to decode your
253 query. You might need this if you are doing a lot of custom encoding
254 of your URLs and not using UTF-8.
255 This setting take precedence over "decode_query_using_global_encoding".
257 "decode_query_using_global_encoding"
259 Setting this to true will default your query decoding to whatever your
261 general global encoding is (the default is UTF-8).
262
264 UTF8 encoding is now default. For temporary backwards compatibility,
265 if this change is causing you trouble, you can disable it by setting
266 the application configuration option to undef:
267 MyApp->config(encoding => undef);
269 But please consider this a temporary measure since it is the intention
271 that UTF8 is enabled going forwards and the expectation is that other
272 ecosystem projects will assume this as well. At some point you
273 application will not correctly function without this setting.
274 As of 5.90084 we've added two additional configuration flags for more
276 selective control over some encoding changes:
277 'skip_body_param_unicode_decoding' and
278 'skip_complex_post_part_handling'. You may use these to more
279 selectively disable new features while you are seeking a long term fix.
280 Please review CONFIGURATION in Catalyst.
281 For further information, please see Catalyst::UTF8
283 A number of projects in the wider ecosystem required minor updates to
285 be able to work correctly. Here's the known list:
286 Catalyst::View::TT, Catalyst::View::Mason, Catalyst::View::HTML::Mason,
288 Catalyst::View::Xslate, Test::WWW::Mechanize::Catalyst
289 You will need to update to modern versions in most cases, although
291 quite a few of these only needed minor test case and documentation
292 changes so you will need to review the changelog of each one that is
293 relevant to you to determine your true upgrade needs.
294
296 Starting in the v5.90059_001 development release, the regexp dispatch
297 type is no longer automatically included as a dependency. If you are
298 still using this dispatch type, you need to add
299 Catalyst::DispatchType::Regex into your build system.
300 The standalone distribution of Regexp will be supported for the time
302 being, but should we find that supporting it prevents us from moving
303 Catalyst forward in necessary ways, we reserve the right to drop that
304 support. It is highly recommended that you use this last stage of
305 deprecation to change your code.
306
308 Catalyst::Plugin::Unicode::Encoding is now core
309 The previously stand alone Unicode support module
310 Catalyst::Plugin::Unicode::Encoding has been brought into core as a
311 default plugin. Going forward, all you need is to add a configuration
312 setting for the encoding type. For example:
313 package Myapp::Web;
315 use Catalyst;
317 __PACKAGE__->config( encoding => 'UTF-8' );
319 Please note that this is different from the old stand alone plugin
321 which applied "UTF-8" encoding by default (that is, if you did not set
322 an explicit "encoding" configuration value, it assumed you wanted
323 UTF-8). In order to preserve backwards compatibility you will need to
324 explicitly turn it on via the configuration setting. THIS MIGHT CHANGE
325 IN THE FUTURE, so please consider starting to test your application
326 with proper UTF-8 support and remove all those crappy hacks you munged
327 into the code because you didn't know the Plugin existed :)
328 For people that are using the Plugin, you will note a startup warning
330 suggesting that you can remove it from the plugin list. When you do
331 so, please remember to add the configuration setting, since you can no
332 longer rely on the default being UTF-8. We'll add it for you if you
333 continue to use the stand alone plugin and we detect this, but this
334 backwards compatibility shim will likely be removed in a few releases
335 (trying to clean up the codebase after all).
336 If you have trouble with any of this, please bring it to the attention
338 of the Catalyst maintainer group.
339 basic async and event loop support
341 This version of Catalyst offers some support for using AnyEvent and
342 IO::Async event loops in your application. These changes should work
343 fine for most applications however if you are already trying to perform
344 some streaming, minor changes in this area of the code might affect
345 your functionality. Please see Catalyst::Response\write_fh for more
346 and for a basic example.
347 We consider this feature experimental. We will try not to break it,
349 but we reserve the right to make necessary changes to fix major issues
350 that people run into when the use this functionality in the wild.
351
353 Regex dispatch type is deprecated.
354 The Regex dispatchtype (Catalyst::DispatchType::Regex) has been
355 deprecated.
356 You are encouraged to move your application to Chained dispatch
358 (Catalyst::DispatchType::Chained).
359 If you cannot do so, please add a dependency to
361 Catalyst::DispatchType::Regex to your application's Makefile.PL
362
364 The major change is that Plack, a toolkit for using the PSGI
365 specification, now replaces most of the subclasses of Catalyst::Engine.
366 If you are using one of the standard subclasses of Catalyst::Engine
367 this should be a straightforward upgrade for you. It was a design goal
368 for this release to preserve as much backwards compatibility as
369 possible. However, since Plack is different from Catalyst::Engine, it
370 is possible that differences exist for edge cases. Therefore, we
371 recommend that care be taken with this upgrade and that testing should
372 be greater than would be the case with a minor point update. Please
373 inform the Catalyst developers of any problems so that we can fix them
374 and incorporate tests.
375 It is highly recommended that you become familiar with the Plack
377 ecosystem and documentation. Being able to take advantage of Plack
378 development and middleware is a major bonus to this upgrade.
379 Documentation about how to take advantage of Plack::Middleware by
380 writing your own ".psgi" file is contained in Catalyst::PSGI.
381 If you have created a custom subclass of <Catalyst:Engine>, you will
383 need to convert it to be a subclass of Plack::Handler.
384 If you are using the Plack engine, Catalyst::Engine::PSGI, this new
386 release supersedes that code.
387 If you are using a subclass of Catalyst::Engine that is aimed at
389 nonstandard or internal/testing uses, such as
390 Catalyst::Engine::Embeddable, you should still be able to continue
391 using that engine.
392 Advice for specific subclasses of Catalyst::Engine follows:
394 Upgrading the FastCGI Engine
396 No upgrade is needed if your myapp_fastcgi.pl script is already
397 upgraded to use Catalyst::Script::FastCGI.
398 Upgrading the mod_perl / Apache Engines
400 The engines that are built upon the various iterations of mod_perl,
401 Catalyst::Engine::Apache::MP13 (for mod_perl 1, and Apache 1.x) and
402 Catalyst::Engine::Apache2::MP20 (for mod_perl 2, and Apache 2.x),
403 should be seamless upgrades and will work using Plack::Handler::Apache1
404 or Plack::Handler::Apache2 as required.
405 Catalyst::Engine::Apache2::MP19, however, is no longer supported, as
407 Plack does not support mod_perl version 1.99. This is unlikely to be a
408 problem for anyone, as 1.99 was a brief beta-test release for mod_perl
409 2, and all users of mod_perl 1.99 are encouraged to upgrade to a
410 supported release of Apache 2 and mod_perl 2.
411 Upgrading the HTTP Engine
413 The default development server that comes with the Catalyst
414 distribution should continue to work as expected with no changes as
415 long as your "myapp_server" script is upgraded to use
416 Catalyst::Script::HTTP.
417 Upgrading the CGI Engine
419 If you were using Catalyst::Engine::CGI there is no upgrade needed if
420 your myapp_cgi.pl script is already upgraded to use
421 Catalyst::Script::CGI.
422 Upgrading Catalyst::Engine::HTTP::Prefork
424 If you were using Catalyst::Engine::HTTP::Prefork then Starman is
425 automatically loaded. You should (at least) change your "Makefile.PL"
426 to depend on Starman.
427 You can regenerate your "myapp_server.pl" script with "catalyst.pl" and
429 implement a "MyApp::Script::Server" class that looks like this:
430 package MyApp::Script::Server;
432 use Moose;
433 use namespace::autoclean;
434 extends 'CatalystX::Script::Server::Starman';
436 1;
438 This takes advantage of the new script system, and will add a number of
440 options to the standard server script as extra options are added by
441 Starman.
442 More information about these options can be seen at "SYNOPSIS" in
444 CatalystX::Script::Server::Starman.
445 An alternate route to implement this functionality is to write a simple
447 .psgi file for your application, and then use the plackup utility to
448 start the server.
449 Upgrading the PSGI Engine
451 If you were using Catalyst::Engine::PSGI, this new release supersedes
452 this engine in supporting Plack. By default the Engine is now always
453 Plack. As a result, you can remove the dependency on
454 Catalyst::Engine::PSGI in your "Makefile.PL".
455 Applications that were using Catalyst::Engine::PSGI previously should
457 entirely continue to work in this release with no changes.
458 However, if you have an "app.psgi" script, then you no longer need to
460 specify the PSGI engine. Instead, the Catalyst application class now
461 has a new method "psgi_app" which returns a PSGI compatible coderef
462 which you can wrap in the middleware of your choice.
463 Catalyst will use the .psgi for your application if it is located in
465 the "home" directory of the application.
466 For example, if you were using Catalyst::Engine::PSGI in the past, you
468 will have written (or generated) a "script/myapp.psgi" file similar to
469 this one:
470 use Plack::Builder;
472 use MyCatalytApp;
473 MyCatalystApp->setup_engine('PSGI');
475 builder {
477 enable ... # enable your desired middleware
478 sub { MyCatalystApp->run(@_) };
479 };
480 Instead, you now say:
482 use Plack::Builder;
484 use MyCatalystApp;
485 builder {
487 enable ... #enable your desired middleware
488 MyCatalystApp->psgi_app;
489 };
490 In the simplest case:
492 MyCatalystApp->setup_engine('PSGI');
494 my $app = sub { MyCatalystApp->run(@_) }
495 becomes
497 my $app = MyCatalystApp->psgi_app(@_);
499 NOT:
501 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!
504 You can now move "script/myapp.psgi" to "myapp.psgi", and the built-in
506 Catalyst scripts and your test suite will start using your .psgi file.
507 NOTE: If you rename your .psgi file without these modifications, then
509 any tests run via Catalyst::Test will not be compatible with the new
510 release, and will result in the development server starting, rather
511 than the expected test running.
512 NOTE: If you are directly accessing "$c->req->env" to get the PSGI
514 environment then this accessor is moved to "$c->engine->env", you will
515 need to update your code.
516 Engines which are known to be broken
518 The following engines DO NOT work as of Catalyst version 5.9. The core
519 team will be happy to work with the developers and/or users of these
520 engines to help them port to the new Plack/Engine system, but for now,
521 applications which are currently using these engines WILL NOT run
522 without modification to the engine code.
523 Catalyst::Engine::Wx
525 Catalyst::Engine::Zeus
526 Catalyst::Engine::JobQueue::POE
527 Catalyst::Engine::XMPP2
528 Catalyst::Engine::SCGI
529 Engines with unknown status
531 The following engines are untested or have unknown compatibility.
532 Reports are highly encouraged:
533 Catalyst::Engine::Mojo
535 Catalyst::Engine::Server (marked as Deprecated)
536 Catalyst::Engine::HTTP::POE (marked as Deprecated)
537 Plack functionality
539 See Catalyst::PSGI.
540 Tests in 5.9
542 Tests should generally work the same in Catalyst 5.9, but there are
543 some differences.
544 Previously, if using Catalyst::Test and doing local requests (against a
546 local server), if the application threw an exception then this
547 exception propagated into the test.
548 This behavior has been removed, and now a 500 response will be returned
550 to the test. This change standardizes behavior, so that local test
551 requests behave similarly to remote requests.
552
554 Most applications and plugins should run unaltered on Catalyst 5.80.
555 However, a lot of refactoring work has taken place, and several changes
557 have been made which could cause incompatibilities. If your application
558 or plugin is using deprecated code, or relying on side effects, then
559 you could have issues upgrading to this release.
560 Most issues found with existing components have been easy to solve.
562 This document provides a complete description of behavior changes which
563 may cause compatibility issues, and of new Catalyst warnings which
564 might be unclear.
565 If you think you have found an upgrade-related issue which is not
567 covered in this document, please email the Catalyst list to discuss the
568 problem.
569
571 Application class roles
572 You can only apply method modifiers after the application's "->setup"
573 method has been called. This means that modifiers will not work with
574 methods run during the call to "->setup".
575 See Catalyst::Manual::ExtendingCatalyst for more information about
577 using Moose in your applications.
578 Controller actions in Moose roles
580 You can use MooseX::MethodAttributes::Role if you want to declare
581 actions inside Moose roles.
582 Using Moose in Components
584 The correct way to use Moose in a component in a both forward and
585 backwards compatible way is:
586 package TestApp::Controller::Root;
588 use Moose;
589 BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
590 See "Components which inherit from Moose::Object before
592 Catalyst::Component".
593
595 Applications in a single file
596 Applications must be in their own file, and loaded at compile time.
597 This issue generally only affects the tests of CPAN distributions. Your
598 application will fail if you try to define an application inline in a
599 block, and use plugins which supply a " new " method, then use that
600 application latter in tests within the same file.
601 This is due to the fact that Catalyst is inlining a new method on your
603 application class allowing it to be compatible with Moose. The method
604 used to do this changed in 5.80004 to avoid the possibility of
605 reporting an 'Unknown Error' if your application failed to compile.
606 Issues with Class::C3
608 Catalyst 5.80 uses the Algorithm::C3 method dispatch order. This is
609 built into Perl 5.10, and comes via Class::C3 for Perl 5.8. This
610 replaces NEXT with Class::C3::Adopt::NEXT, forcing all components to
611 resolve methods using C3, rather than the unpredictable dispatch order
612 of NEXT.
613 This issue manifests itself by your application failing to start due to
615 an error message about having a non-linear @ISA.
616 The Catalyst plugin most often causing this is
618 Catalyst::Plugin::Session::Store::FastMmap - if you are using this
619 plugin and see issues, then please upgrade your plugins, as it has been
620 fixed. Note that Makefile.PL in the distribution will warn about known
621 incompatible components.
622 This issue can, however, be found in your own application - the only
624 solution is to go through each base class of the class the error was
625 reported against, until you identify the ones in conflict, and resolve
626 them.
627 To be able to generate a linear @ISA, the list of superclasses for each
629 class must be resolvable using the C3 algorithm. Unfortunately, when
630 superclasses are being used as mixins (to add functionality used in
631 your class), and with multiple inheritance, it is easy to get this
632 wrong.
633 Most common is the case of:
635 package Component1; # Note, this is the common case
637 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
638 package Component2; # Accidentally saying it this way causes a failure
640 use base qw/Class::Data::Inheritable Class::Accessor::Fast/;
641 package GoesBang;
643 use base qw/Component1 Component2/;
644 Any situation like this will cause your application to fail to start.
646 For additional documentation about this issue, and how to resolve it,
648 see Class::C3::Adopt::NEXT.
649 Components which inherit from Moose::Object before Catalyst::Component
651 Moose components which say:
652 package TestApp::Controller::Example;
654 use Moose;
655 extends qw/Moose::Object Catalyst::Component/;
656 to use the constructor provided by Moose, while working (if you do some
658 hacks with the " BUILDARGS " method), will not work with Catalyst 5.80
659 as "Catalyst::Component" inherits from "Moose::Object", and so @ISA
660 fails to linearize.
661 The correct way to use Moose in a component in a both forward and
663 backwards compatible way is:
664 package TestApp::Controller::Root;
666 use Moose;
667 BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
668 Note that the " extends " declaration needs to occur in a begin block
670 for attributes to operate correctly.
671 This way you do not inherit directly from "Moose::Object" yourself.
673 Having components which do not inherit their constructor from
674 "Catalyst::Component" is unsupported, and has never been recommended,
675 therefore you're on your own if you're using this technique. You'll
676 need to detect the version of Catalyst your application is running, and
677 deal with it appropriately.
678 You also don't get the Moose::Object constructor, and therefore
680 attribute initialization will not work as normally expected. If you
681 want to use Moose attributes, then they need to be made lazy to
682 correctly initialize.
683 Note that this only applies if your component needs to maintain
685 component backwards compatibility for Catalyst versions before 5.71001
686 - in 5.71001 attributes work as expected, and the BUILD method is
687 called normally (although BUILDARGS is not).
688 If you depend on Catalyst 5.8, then all Moose features work as
690 expected.
691 You will also see this issue if you do the following:
693 package TestApp::Controller::Example;
695 use Moose;
696 use base 'Catalyst::Controller';
697 as " use base " appends to @ISA.
699 use Moose in MyApp
701 Similar to the above, this will also fail:
703 package MyApp;
705 use Moose;
706 use Catalyst qw/
707 ConfigLoader
708 /;
709 __PACKAGE__->setup;
710 If you need to use Moose in your application class (e.g. for method
712 modifiers etc.) then the correct technique is:
713 package MyApp;
715 use Moose;
716 use Catalyst;
717 extends 'Catalyst';
719 __PACKAGE__->config( name => 'MyApp' );
721 __PACKAGE__->setup(qw/
722 ConfigLoader
723 /);
724 Anonymous closures installed directly into the symbol table
726 If you have any code which installs anonymous subroutine references
727 directly into the symbol table, you may encounter breakages. The
728 simplest solution is to use Sub::Name to name the subroutine. Example:
729 # Original code, likely to break:
731 my $full_method_name = join('::', $package_name, $method_name);
732 *$full_method_name = sub { ... };
733 # Fixed Code
735 use Sub::Name 'subname';
736 my $full_method_name = join('::',$package_name, $method_name);
737 *$full_method_name = subname $full_method_name, sub { ... };
738 Additionally, you can take advantage of Catalyst's use of Class::MOP
740 and install the closure using the appropriate metaclass. Example:
741 use Class::MOP;
743 my $metaclass = Moose::Meta::Class->initialize($package_name);
744 $metaclass->add_method($method_name => sub { ... });
745 Hooking into application setup
747 To execute code during application start-up, the following snippet in
748 MyApp.pm used to work:
749 sub setup {
751 my ($class, @args) = @_;
752 $class->NEXT::setup(@args);
753 ... # things to do after the actual setup
754 }
755 With Catalyst 5.80 this won't work anymore, because Catalyst no longer
757 uses NEXT.pm for method resolution. The functionality was only ever
758 originally operational as NEXT remembers what methods have already been
759 called, and will not call them again.
760 Using this now causes infinite recursion between MyApp::setup and
762 Catalyst::setup, due to other backwards compatibility issues related to
763 how plugin setup works. Moose method modifiers like
764 "before|after|around setup => sub { ... };" also will not operate
765 correctly on the setup method.
766 The right way to do it is this:
768 after setup_finalize => sub {
770 ... # things to do after the actual setup
771 };
772 The setup_finalize hook was introduced as a way to avoid this issue.
774 Components with a new method which returns false
776 Previously, if you had a component which inherited from
777 Catalyst::COMPONENT, but overrode the new method to return false, then
778 your class's configuration would be blessed into a hash on your behalf,
779 and this would be returned from the COMPONENT method.
780 This behavior makes no sense, and so has been removed. Implementing
782 your own " new " method in components is highly discouraged. Instead,
783 you should inherit the new method from Catalyst::Component, and use
784 Moose's BUILD functionality and/or Moose attributes to perform any
785 construction work necessary for your class.
786 __PACKAGE__->mk_accessor('meta');
788 Won't work due to a limitation of Moose. This is currently being fixed
789 inside Moose.
790 Class::Data::Inheritable side effects
792 Previously, writing to a class data accessor would copy the accessor
793 method down into your package.
794 This behavior has been removed. While the class data is still stored
796 per-class, it is stored on the metaclass of the class defining the
797 accessor.
798 Therefore anything relying on the side effect of the accessor being
800 copied down will be broken.
801 The following test demonstrates the problem:
803 {
805 package BaseClass;
806 use base qw/Class::Data::Inheritable/;
807 __PACKAGE__->mk_classdata('foo');
808 }
809 {
811 package Child;
812 use base qw/BaseClass/;
813 }
814 BaseClass->foo('base class');
816 Child->foo('sub class');
817 use Test::More;
819 isnt(BaseClass->can('foo'), Child->can('foo'));
820 Extending Catalyst::Request or other classes in an ad hoc manner using
822 mk_accessors
823 Previously, it was possible to add additional accessors to
824 Catalyst::Request (or other classes) by calling the mk_accessors class
825 method.
826 This is no longer supported - users should make a subclass of the class
828 whose behavior they would like to change, rather than globally
829 polluting the Catalyst objects.
830 Confused multiple inheritance with Catalyst::Component::COMPONENT
832 Previously, Catalyst's COMPONENT method would delegate to the method on
833 the right hand side, which could then delegate back again with NEXT.
834 This is poor practice, and in addition, makes no sense with C3 method
835 dispatch order, and is therefore no longer supported.
836 If a COMPONENT method is detected in the inheritance hierarchy to the
838 right hand side of Catalyst::Component::COMPONENT, then the following
839 warning message will be emitted:
840 There is a COMPONENT method resolving after Catalyst::Component
842 in ${next_package}.
843 The correct fix is to re-arrange your class's inheritance hierarchy so
845 that the COMPONENT method you would like to inherit is the first (left-
846 hand most) COMPONENT method in your @ISA.
847 Development server relying on environment variables
849 Previously, the development server would allow propagation of system
850 environment variables into the request environment, this has changed
851 with the adoption of Plack. You can use Plack::Middleware::ForceEnv to
852 achieve the same effect.
853
855 Actions in your application class
856 Having actions in your application class will now emit a warning at
857 application startup as this is deprecated. It is highly recommended
858 that these actions are moved into a MyApp::Controller::Root (as
859 demonstrated by the scaffold application generated by catalyst.pl).
860 This warning, also affects tests. You should move actions in your test,
862 creating a myTest::Controller::Root, like the following example:
863 package MyTest::Controller::Root;
865 use strict;
867 use warnings;
868 use parent 'Catalyst::Controller';
870 __PACKAGE__->config(namespace => '');
872 sub action : Local {
874 my ( $self, $c ) = @_;
875 $c->do_something;
876 }
877 1;
879 ::[MVC]:: naming scheme
881 Having packages called MyApp::[MVC]::XX is deprecated and can no longer
882 be generated by catalyst.pl
883 This is still supported, but it is recommended that you rename your
885 application components to Model/View/Controller.
886 A warning will be issued at application startup if the ::[MVC]:: naming
888 scheme is in use.
889 Catalyst::Base
891 Any code using Catalyst::Base will now emit a warning; this module will
892 be removed in a future release.
893 Methods in Catalyst::Dispatcher
895 The following methods in Catalyst::Dispatcher are implementation
896 details, which may change in the 5.8X release series, and therefore
897 their use is highly deprecated.
898 tree
900 dispatch_types
901 registered_dispatch_types
902 method_action_class
903 action_hash
904 container_hash
905 The first time one of these methods is called, a warning will be
907 emitted:
908 Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
910 this will be removed in Catalyst 5.9
911 You should NEVER be calling any of these methods from application code.
913 Plugin authors and maintainers whose plugins currently call these
915 methods should change to using the public API, or, if you do not feel
916 the public API adequately supports your use case, please email the
917 development list to discuss what API features you need so that you can
918 be appropriately supported.
919 Class files with names that don't correspond to the packages they define
921 In this version of Catalyst, if a component is loaded from disk, but no
922 symbols are defined in that component's name space after it is loaded,
923 this warning will be issued:
924 require $class was successful but the package is not defined.
926 This is to protect against confusing bugs caused by mistyping package
928 names, and will become a fatal error in a future version.
929 Please note that 'inner packages' (via Devel::InnerPackage) are still
931 fully supported; this warning is only issued when component file naming
932 does not map to any of the packages defined within that component.
933 $c->plugin method
935 Calling the plugin method is deprecated, and calling it at run time is
936 highly deprecated.
937 Instead you are recommended to use Catalyst::Model::Adaptor or similar
939 to compose the functionality you need outside of the main application
940 name space.
941 Calling the plugin method will not be supported past Catalyst 5.81.
943perl v5.28.0 2018-09-16 Catalyst::Upgrading(3)