1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "Catalyst::Upgrading 3"
132 .TH Catalyst::Upgrading 3 "2009-11-23" "perl v5.8.7" "User Contributed Perl Documentation"
134 Catalyst::Upgrading \- Instructions for upgrading to the latest Catalyst
135 .SH "Upgrading to Catalyst 5.80"
136 .IX Header "Upgrading to Catalyst 5.80"
137 Most applications and plugins should run unaltered on Catalyst 5.80.
139 However, a lot of refactoring work has taken place, and several changes have
140 been made which could cause incompatibilities. If your application or plugin
141 is using deprecated code, or relying on side effects, then you could have
142 issues upgrading to this release.
144 Most issues found with pre-existing components have been easy to
145 solve. This document provides a complete description of behavior changes
146 which may cause compatibility issues, and of new Catalyst warnings which
149 If you think you have found an upgrade-related issue which is not covered in
150 this document, please email the Catalyst list to discuss the problem.
152 .IX Header "Moose features"
153 .Sh "Application class roles"
154 .IX Subsection "Application class roles"
155 You can only apply method modifiers after the application's \f(CW\*(C`\->setup\*(C'\fR
156 method has been called. This means that modifiers will not work with methods
157 which run during the call to \f(CW\*(C`\->setup\*(C'\fR.
159 See Catalyst::Manual::ExtendingCatalyst for more information about using
160 Moose in your applications.
161 .Sh "Controller actions in Moose roles"
162 .IX Subsection "Controller actions in Moose roles"
163 You can use MooseX::MethodAttributes::Role if you want to declare actions
165 .Sh "Using Moose in Components"
166 .IX Subsection "Using Moose in Components"
167 The correct way to use Moose in a component in a both forward and backwards
171 \& package TestApp::Controller::Root;
173 \& BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
176 See \*(L"Components which inherit from Moose::Object before Catalyst::Component\*(R".
177 .SH "Known backwards compatibility breakages"
178 .IX Header "Known backwards compatibility breakages"
179 .Sh "Applications in a single file"
180 .IX Subsection "Applications in a single file"
181 Applications must be in their own file, and loaded at compile time. This
182 issue generally only affects the tests of \s-1CPAN\s0 distributions. Your
183 application will fail if you try to define an application inline in a
184 block, and use plugins which supply a \f(CW\*(C` new \*(C'\fR method, then use that
185 application latter in tests within the same file.
187 This is due to the fact that Catalyst is inlining a new method on your
188 application class allowing it to be compatible with Moose. The method
189 used to do this changed in 5.80004 to avoid the possibility of reporting
190 an 'Unknown Error' if your application failed to compile.
191 .Sh "Issues with Class::C3"
192 .IX Subsection "Issues with Class::C3"
193 Catalyst 5.80 uses the Algorithm::C3 method dispatch order. This is
194 built into Perl 5.10, and comes via Class::C3 for Perl 5.8. This
195 replaces \s-1NEXT\s0 with Class::C3::Adopt::NEXT, forcing all components
196 to resolve methods using C3, rather than the unpredictable dispatch
197 order of \s-1NEXT\s0.
199 This issue is characterised by your application failing to start due to an
200 error message about having a non-linear \f(CW@ISA\fR.
202 The Catalyst plugin most often causing this is
203 Catalyst::Plugin::Session::Store::FastMmap \- if you are using this
204 plugin and see issues, then please upgrade your plugins, as it has been
205 fixed. Note that Makefile.PL in the distribution will warn about known
206 incompatible components.
208 This issue can, however, be found in your own application \- the only solution is
209 to go through each base class of the class the error was reported against, until
210 you identify the ones in conflict, and resolve them.
212 To be able to generate a linear \f(CW@ISA\fR, the list of superclasses for each
213 class must be resolvable using the C3 algorithm. Unfortunately, when
214 superclasses are being used as mixins (to add functionality used in your class),
215 and with multiple inheritence, it is easy to get this wrong.
217 Most common is the case of:
220 \& package Component1; # Note, this is the common case
221 \& use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
225 \& package Component2; # Accidentally saying it this way causes a failure
226 \& use base qw/Class::Data::Inheritable Class::Accessor::Fast/;
231 \& use base qw/Component1 Component2/;
234 Any situation like this will cause your application to fail to start.
236 For additional documentation about this issue, and how to resolve it, see
237 Class::C3::Adopt::NEXT.
238 .Sh "Components which inherit from Moose::Object before Catalyst::Component"
239 .IX Subsection "Components which inherit from Moose::Object before Catalyst::Component"
240 Moose components which say:
243 \& package TestApp::Controller::Example;
245 \& extends qw/Moose::Object Catalyst::Component/;
248 to use the constructor provided by Moose, while working (if you do some hacks
249 with the \f(CW\*(C` BUILDARGS \*(C'\fR method), will not work with Catalyst 5.80 as
250 \&\f(CW\*(C`Catalyst::Component\*(C'\fR inherits from \f(CW\*(C`Moose::Object\*(C'\fR, and so \f(CW @ISA \fR fails
253 The correct way to use Moose in a component in a both forward and backwards
257 \& package TestApp::Controller::Root;
259 \& BEGIN { extends 'Catalyst::Component' }; # Or ::Controller, or whatever
262 Note that the \f(CW\*(C` extends \*(C'\fR declaration needs to occur in a begin block for
263 attributes to operate correctly.
265 This way you do not inherit directly from \f(CW\*(C`Moose::Object\*(C'\fR
266 yourself. Having components which do not inherit their constructor from
267 \&\f(CW\*(C`Catalyst::Component\*(C'\fR is \fBunsupported\fR, and has never been recommended,
268 therefore you're on your own if you're using this technique. You'll need
269 to detect the version of Catalyst your application is running, and deal
270 with it appropriately.
272 You also don't get the Moose::Object constructor, and therefore attribute
273 initialization will not work as normally expected. If you want to use Moose
274 attributes, then they need to be made lazy to correctly initialize.
276 Note that this only applies if your component needs to maintain component
277 backwards compatibility for Catalyst versions before 5.71001 \- in 5.71001
278 attributes work as expected, and the \s-1BUILD\s0 method is called normally
279 (although \s-1BUILDARGS\s0 is not).
281 If you depend on Catalyst 5.8, then \fBall\fR Moose features work as expected.
283 You will also see this issue if you do the following:
286 \& package TestApp::Controller::Example;
288 \& use base 'Catalyst::Controller';
291 as \f(CW\*(C` use base \*(C'\fR appends to \f(CW@ISA\fR.
293 \fIuse Moose in MyApp\fR
294 .IX Subsection "use Moose in MyApp"
296 Similar to the above, this will also fail:
304 \& __PACKAGE__\->setup;
307 If you need to use Moose in your application class (e.g. for method modifiers
308 etc.) then the correct technique is:
317 \& extends 'Catalyst';
321 \& __PACKAGE__\->config( name => 'MyApp' );
322 \& __PACKAGE__\->setup(qw/
326 .Sh "Anonymous closures installed directly into the symbol table"
327 .IX Subsection "Anonymous closures installed directly into the symbol table"
328 If you have any code which installs anonymous subroutine references directly
329 into the symbol table, you may encounter breakages. The simplest solution is
330 to use Sub::Name to name the subroutine. Example:
333 \& # Original code, likely to break:
334 \& my $full_method_name = join('::', $package_name, $method_name);
335 \& *$full_method_name = sub { ... };
340 \& use Sub::Name 'subname';
341 \& my $full_method_name = join('::',$package_name, $method_name);
342 \& *$full_method_name = subname $full_method_name, sub { ... };
345 Additionally, you can take advantage of Catalyst's use of Class::MOP and
346 install the closure using the appropriate metaclass. Example:
350 \& my $metaclass = Moose::Meta::Class\->initialize($package_name);
351 \& $metaclass\->add_method($method_name => sub { ... });
353 .Sh "Hooking into application setup"
354 .IX Subsection "Hooking into application setup"
355 To execute code during application start\-up, the following snippet in MyApp.pm
360 \& my ($class, @args) = @_;
361 \& $class\->NEXT::setup(@args);
362 \& ... # things to do after the actual setup
366 With Catalyst 5.80 this won't work anymore, because Catalyst no longer
367 uses \s-1NEXT\s0.pm for method resolution. The functionality was only ever
368 originally operational as \s-1NEXT\s0 remembers what methods have already
369 been called, and will not call them again.
371 Using this now causes infinite recursion between MyApp::setup and
372 Catalyst::setup, due to other backwards compatibility issues related to how
373 plugin setup works. Moose method modifiers like \f(CW\*(C`before|after|around 'setup
374 => sub { ... };\*(C'\fR also will not operate correctly on the setup method.
376 The right way to do it is this:
379 \& after setup_finalize => sub {
380 \& ... # things to do after the actual setup
384 The setup_finalize hook was introduced as a way to avoid this issue.
385 .Sh "Components with a new method which returns false"
386 .IX Subsection "Components with a new method which returns false"
387 Previously, if you had a component which inherited from Catalyst::COMPONENT,
388 but overrode the new method to return false, then your class's configuration
389 would be blessed into a hash on your behalf, and this would be returned from
390 the \s-1COMPONENT\s0 method.
392 This behavior makes no sense, and so has been removed. Implementing your own
393 \&\f(CW\*(C` new \*(C'\fR method in components is \fBhighly\fR discouraged. Instead, you should
394 inherit the new method from Catalyst::Component, and use Moose's \s-1BUILD\s0
395 functionality and/or Moose attributes to perform any construction work
396 necessary for your class.
397 .Sh "_\|_PACKAGE_\|_\->mk_accessor('meta');"
398 .IX Subsection "__PACKAGE__->mk_accessor('meta');"
399 Won't work due to a limitation of Moose. This is currently being fixed
401 .Sh "Class::Data::Inheritable side effects"
402 .IX Subsection "Class::Data::Inheritable side effects"
403 Previously, writing to a class data accessor would copy the accessor method
404 down into your package.
406 This behavior has been removed. While the class data is still stored
407 per\-class, it is stored on the metaclass of the class defining the accessor.
409 Therefore anything relying on the side effect of the accessor being copied down
412 The following test demonstrates the problem:
416 \& package BaseClass;
417 \& use base qw/Class::Data::Inheritable/;
418 \& __PACKAGE__\->mk_classdata('foo');
425 \& use base qw/BaseClass/;
430 \& BaseClass\->foo('base class');
431 \& Child\->foo('sub class');
436 \& isnt(BaseClass\->can('foo'), Child\->can('foo'));
438 .Sh "Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors"
439 .IX Subsection "Extending Catalyst::Request or other classes in an ad-hoc manner using mk_accessors"
440 Previously, it was possible to add additional accessors to Catalyst::Request
441 (or other classes) by calling the mk_accessors class method.
443 This is no longer supported \- users should make a subclass of the class whose
444 behavior they would like to change, rather than globally polluting the
446 .Sh "Confused multiple inheritance with Catalyst::Component::COMPONENT"
447 .IX Subsection "Confused multiple inheritance with Catalyst::Component::COMPONENT"
448 Previously, Catalyst's \s-1COMPONENT\s0 method would delegate to the method on
449 the right hand side, which could then delegate back again with
450 \&\s-1NEXT\s0. This is poor practice, and in addition, makes no sense with C3
451 method dispatch order, and is therefore no longer supported.
453 If a \s-1COMPONENT\s0 method is detected in the inheritance hierarchy to the right
454 hand side of Catalyst::Component::COMPONENT, then the following warning
455 message will be emitted:
458 \& There is a COMPONENT method resolving after Catalyst::Component
459 \& in ${next_package}.
462 The correct fix is to re-arrange your class's inheritance hierarchy so that the
463 \&\s-1COMPONENT\s0 method you would like to inherit is the first (left\-hand most)
464 \&\s-1COMPONENT\s0 method in your \f(CW@ISA\fR.
466 .IX Header "WARNINGS"
467 .Sh "Actions in your application class"
468 .IX Subsection "Actions in your application class"
469 Having actions in your application class will now emit a warning at application
470 startup as this is deprecated. It is highly recommended that these actions are moved
471 into a MyApp::Controller::Root (as demonstrated by the scaffold application
472 generated by catalyst.pl).
474 This warning, also affects tests. You should move actions in your test,
475 creating a myTest::Controller::Root, like the following example:
478 \& package MyTest::Controller::Root;
487 \& use parent 'Catalyst::Controller';
491 \& __PACKAGE__\->config(namespace => '');
495 \& sub action : Local {
496 \& my ( $self, $c ) = @_;
497 \& $c\->do_something;
504 .Sh "::[\s-1MVC\s0]:: naming scheme"
505 .IX Subsection "::[MVC]:: naming scheme"
506 Having packages called MyApp::[\s-1MVC\s0]::XX is deprecated and can no longer be generated
509 This is still supported, but it is recommended that you rename your application
510 components to Model/View/Controller.
512 A warning will be issued at application startup if the ::[\s-1MVC\s0]:: naming scheme is
515 .IX Subsection "Catalyst::Base"
516 Any code using Catalyst::Base will now emit a warning; this
517 module will be removed in a future release.
518 .Sh "Methods in Catalyst::Dispatcher"
519 .IX Subsection "Methods in Catalyst::Dispatcher"
520 The following methods in Catalyst::Dispatcher are implementation
521 details, which may change in the 5.8X release series, and therefore their use
522 is highly deprecated.
526 .IP "dispatch_types" 4
527 .IX Item "dispatch_types"
528 .IP "registered_dispatch_types" 4
529 .IX Item "registered_dispatch_types"
530 .IP "method_action_class" 4
531 .IX Item "method_action_class"
533 .IX Item "action_hash"
534 .IP "container_hash" 4
535 .IX Item "container_hash"
538 The first time one of these methods is called, a warning will be emitted:
541 \& Class $class is calling the deprecated method Catalyst::Dispatcher::$public_method_name,
542 \& this will be removed in Catalyst 5.9X
545 You should \fB\s-1NEVER\s0\fR be calling any of these methods from application code.
547 Plugin authors and maintainers whose plugins currently call these methods
548 should change to using the public \s-1API\s0, or, if you do not feel the public \s-1API\s0
549 adequately supports your use case, please email the development list to
550 discuss what \s-1API\s0 features you need so that you can be appropriately supported.
551 .Sh "Class files with names that don't correspond to the packages they define"
552 .IX Subsection "Class files with names that don't correspond to the packages they define"
553 In this version of Catalyst, if a component is loaded from disk, but no
554 symbols are defined in that component's name space after it is loaded, this
555 warning will be issued:
558 \& require $class was successful but the package is not defined.
561 This is to protect against confusing bugs caused by mistyping package names,
562 and will become a fatal error in a future version.
564 Please note that 'inner packages' (via Devel::InnerPackage) are still fully
565 supported; this warning is only issued when component file naming does not map
566 to \fBany\fR of the packages defined within that component.
567 .Sh "$c\->plugin method"
568 .IX Subsection "$c->plugin method"
569 Calling the plugin method is deprecated, and calling it at run time is \fBhighly
572 Instead you are recommended to use Catalyst::Model::Adaptor or similar to
573 compose the functionality you need outside of the main application name space.
575 Calling the plugin method will not be supported past Catalyst 5.81.
projects / catagits/Gitalist.git / blob