1Catalyst::Delta(3) User Contributed Perl Documentation Catalyst::Delta(3)
2
6 Catalyst::Delta - Overview of changes between versions of Catalyst
7
9 This is an overview of the user-visible changes to Catalyst between
10 major Catalyst releases.
11 VERSION 5.90105
13 This version primarily fixed a regression in the way we preserved
14 $c->state which the previous version introduced. Now in the case when
15 you forward to an action, should that action throw an exception it sets
16 state to 0 and is sure that the return value is false. This is to meet
17 expected behavior based on the documentation. If you relied on the
18 last update behavior you may not have regressions but it was thought
19 that we should make the code behave as documented for more than 10
20 years.
21 We also changed how we compose the request, response and stats base
23 class. We now compose the base class with any configured traits once
24 at the end of the application setup, rather than for each request.
25 This reduced request overhead when you are composing lots of traits.
26 It possible this may break some code that was adding traits after the
27 application setup was finalized. Please shout out if this actually
28 causes you trouble and we'll do the best to accommodate.
29 VERSION 5.90102 - 5.90103
31 A significant change is that we now preserve the value of $c->state
32 from action to following action. This gives you a new way to pass a
33 value between actions in a chain, for example. However any 'auto'
34 actions always have $c->state forced to be set to 0, which is the way
35 its been for a long time, this way an auto action is required to return
36 1 to pass the match. It also exists to maintain compatibility with
37 anyone that exits an auto action with a detach (which is not a
38 documented way to escape matching, but exists in the wild since it
39 worked as a side effect of the code for a long time).
40 Additionally, upon $c->detach we also force set state to 0.
42 Version 5.90102 contains a version of this change but its considered
44 buggy, so that is a version to avoid.
45 VERSION 5.90100
47 Support for type constraints in Args and CaptureArgs has been improved.
48 You may now inherit from a base controller that declares type
49 constraints and use roles that declare type constraints. See
50 Catalyst::RouteMatching for more.
51 You may now. also use a full type constraint namespace instead of
53 importing type constraints into your package namespace.
54 We changed the way the middleware stash works so that it no longer
56 localizes the PSGI env hashref. This was done to fix bugs where people
57 set PSGI ENV hash keys and found them to disappear in certain cases.
58 It also means that now if a sub applications sets stash variables, that
59 stash will now bubble up to the parent application. This may be a
60 breaking change for you since previous versions of this code did not
61 allow that. A workaround is to explicitly delete stash keys in your
62 sub application before returning control to the parent application.
63 VERSION 5.90097
65 Defined how $c->uri_for adds a URI fragment.
66 We now have a specification for creating URIs with fragments (or HTML
68 anchors). Previously you could do this as a side effect of how we
69 create URIs but this side effect behavior was never documented or
70 tested, and was broken when we introduced default UTF-8 encoding. When
71 creating URIs with fragments please follow the new, supported
72 specification:
73 $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment);
75 This will be a breaking change for some codebases, we recommend testing
77 if you are creating URLs with fragments.
78 NOTE If you are using the alternative:
80 $c->uri_for('/foo/bar#baz')
82 construction, we do not attempt to encode this and it will make a URL
84 with a fragment of 'baz'.
85 VERSION 5.90094
87 Multipart form POST with character set headers
88 When we did the UTF8 work, we punted on Form POSTs when the POST
90 envelope was multipart and each part had complex headers such as
91 content-types, character sets and so forth. In those cases instead of
92 returning a possibly incorrect value, we returned an object describing
93 the part so that you could figure it out manually. This turned out to
94 be a bad workaround as people did not expect to find that object. So
95 we changed this to try much harder to get a correct value. We still
96 return an object if we fail but we try much harder now. If you used to
97 check for the object you might find that code is no longer needed
98 (although checking for it should not hurt or break anything either).
99 VERSION 5.90091
101 'case_sensitive' configuration
102 At one point in time we allowed you to set a 'case_sensitive'
104 configuration value so that you could find actions by their private
105 names using mixed case. We highly discourage that. If you are using
106 this 'feature' you should be on notice that we plan to remove the code
107 around it in the near future.
108 VERSION 5.90090+
110 Type constraints on Args and CaptureArgs.
111 You may now use a type constraint (using Moose, MooseX::Types or
113 preferably Type::Tiny in your Args or CaptureArgs action attributes.
114 This can be used to restrict the value of the Arg. For example:
115 sub myaction :Local Args(Int) { ... }
117 Would match '.../myaction/5' but not '.../myaction/string'.
119 When an action (or action chain) has Args (or CaptureArgs) that declare
121 type constraints your arguments to $c->uri_for(...) must match those
122 constraints.
123 See Catalyst::RouteMatching for more.
125 Move CatalystX::InjectComponent into core
127 Catalyst::Utils has a new method 'inject_component' which works the
129 same as the method of the same name in CatalystX::InjectComponent.
130 inject_components
132 New configuration key allows you to inject components directly into
134 your application without any subclasses. For example:
135 MyApp->config({
137 inject_components => {
138 'Controller::Err' => { from_component => 'Local::Controller::Errors' },
139 'Model::Zoo' => { from_component => 'Local::Model::Foo' },
140 'Model::Foo' => { from_component => 'Local::Model::Foo', roles => ['TestRole'] },
141 },
142 'Controller::Err' => { a => 100, b=>200, namespace=>'error' },
143 'Model::Zoo' => { a => 2 },
144 'Model::Foo' => { a => 100 },
145 });
146 Injected components are useful to reduce the amount of nearly empty
148 boilerplate classes you might have, particularly when first starting an
149 application.
150 Component setup changes.
152 Previously you could not depend on an application scoped component
154 doing setup_components since components were setup 'in order'. Now all
155 components are first registered and then setup, so you can now reliably
156 use any component doing setup_components.
157 VERSION 5.90080+
159 The biggest change in this release is that UTF8 encoding is now enabled
160 by default. So you no longer need any plugins (such as
161 Catalyst::Plugin::Unicode::Encoding) which you can just no go ahead and
162 remove. You also don't need to set the encoding configuration
163 (__PACKAGE__->config(encoding=>'UTF-8')) anymore as well (although its
164 presence hurts nothing).
165 If this change causes you trouble, you can disable it:
167 __PACKAGE__->config(encoding=>undef);
169 For further information, please see Catalyst::UTF8
171 But please report bugs. You will find that a number of common Views
173 have been updated for this release (such as Catalyst::View::TT). In
174 all cases that the author is aware of these updates were to fix test
175 cases only. You shouldn't need to update unless you are installing
176 fresh and want tests to pass.
177 Catalyst::Plugin::Compress was updated to be compatible with this
179 release. You will need to upgrade if you are using this plugin.
180 Catalyst::Upgrading also has details.
181 A small change is that the configuration setting "using_frontend_proxy"
183 was not doing the right thing if you started your application with
184 "psgi_app" and did not apply the default middleware. This setting is
185 now honored in all the ways an application may be started. This could
186 cause trouble if you are using the configuration value and also adding
187 the proxy middleware manually with a custom application startup. The
188 solution is that you only need the configuration value set, or the
189 middleware manually added (not both).
190 VERSION 5.90060+
192 Catalyst::Log object autoflush on by default
193 Starting in 5.90065, the Catalyst::Log object has 'autoflush' which is
195 on by default. This causes all messages to be written to the log
196 immediately instead of at the end of startup and then at the end of
197 each request. In order to access the old behavior, you must now call:
198 $c->log->autoflush(0);
200 Deprecate Catalyst::Utils::ensure_class_loaded
202 Going forward we recommend you use Module::Runtime. In fact we will be
204 converting all uses of Class::Load to Module::Runtime. We will also
205 convert Catalyst::Utils\ensure_class_loaded to be based on
206 Module::Runtime to allow some time for you to update code, however at
207 some future point this method will be removed so you should stop using
208 it now.
209 Support passing Body filehandles directly to your Plack server.
211 We changed the way we return body content (from response) to whatever
213 Plack handler you are using (Starman, FastCGI, etc.) We no longer
214 always use the streaming interface for the cases when the body is a
215 simple scalar, object or filehandle like. In those cases we now just
216 pass the simple response on to the plack handler. This might lead to
217 some minor differences in how streaming is handled. For example, you
218 might notice that streaming starts properly supporting chunked encoding
219 when on a server that supports that, or that previously missing headers
220 (possible content-length) might appear suddenly correct. Also, if you
221 are using middleware like Plack::Middleware::XSendfile and are using a
222 filehandle that sets a readable path, your server might now correctly
223 handle the file (rather than as before where Catalyst would stream it
224 very likely very slowly).
225 In other words, some things might be meaninglessly different and some
227 things that were broken codewise but worked because of Catalyst being
228 incorrect might suddenly be really broken. The behavior is now more
229 correct in that Catalyst plays better with features that Plack offers
230 but if you are making heavy use of the streaming interface there could
231 be some differences so you should test carefully (this is probably not
232 the vast majority of people). In particular if you are developing
233 using one server but deploying using a different one, differences in
234 what those server do with streaming should be noted.
235 Please see note below about changes to filehandle support and existing
237 Plack middleware to aid in backwards compatibility.
238 Distinguish between body null versus undef.
240 We also now more carefully distinguish the different between a body set
242 to '' and a body that is undef. This might lead to situations where
243 again you'll get a content-length were you didn't get one before or
244 where a supporting server will start chunking output. If this is an
245 issue you can apply the middleware Plack::Middleware::BufferedStreaming
246 or report specific problems to the dev team.
247 More Catalyst Middleware
249 We have started migrating code in Catalyst to equivalent Plack
251 Middleware when such exists and is correct to do so. For example we
252 now use Plack::Middleware::ContentLength to determine content length of
253 a response when none is provided. This replaces similar code inlined
254 with Catalyst The main advantages to doing this is 1) more similar
255 Catalyst core that is focused on the Catalyst special sauce, 2)
256 Middleware is more broadly shared so we benefit from better
257 collaboration with developers outside Catalyst, 3) In the future you'll
258 be able to change or trim the middleware stack to get additional
259 performance when you don't need all the checks and constraints.
260 Deprecate Filehandle like objects that do read but not getline
262 We also deprecated setting the response body to an object that does
264 'read' but not 'getline'. If you are using a custom IO-Handle like
265 object for response you should verify that 'getline' is supported in
266 your interface. Unless we here this case is a major issue for people,
267 we will be removing support in a near future release of Catalyst. When
268 the code encounters this it will issue a warning. You also may run
269 into this issue with MogileFS::Client which does read but not getline.
270 For now we will just warn when encountering such an object and fallback
271 to the previous behavior (where Catalyst::Engine itself unrolls the
272 filehandle and performs blocking streams). However this backwards
273 compatibility will be removed in an upcoming release so you should
274 either rewrite your custom filehandle objects to support getline or
275 start using the middleware that adapts read for getline
276 Plack::Middleware::AdaptFilehandleRead.
277 Response->headers become read-only after finalizing
279 Once the response headers are finalized, trying to change them is not
281 allowed (in the past you could change them and this would lead to
282 unexpected results).
283 Officially deprecate Catalyst::Engine::PSGI
285 Catalyst::Engine::PSGI is also officially no longer supported. We will
287 no long run test cases against this and can remove backwards
288 compatibility code for it as deemed necessary for the evolution of the
289 platform. You should simply discontinue use of this engine, as
290 Catalyst has been PSGI at the core for several years.
291 Officially deprecate finding the PSGI $env anyplace other than Request
293 A few early releases of Cataplack had the PSGI $env in
295 Catalyst::Engine. Code has been maintained here for backwards
296 compatibility reasons. This is no longer supported and will be removed
297 in upcoming release, so you should update your code and / or upgrade to
298 a newer version of Catalyst
299 Deprecate setting Response->body after using write/write_fh
301 Setting $c->res->body to a filehandle after using $c->res->write or
303 $c->res->write_fh is no longer considered allowed, since we can't send
304 the filehandle to the underlying Plack handler. For now we will
305 continue to support setting body to a simple value since this is
306 possible, but at some future release a choice to use streaming
307 indicates that you will do so for the rest of the request.
308 VERSION 5.90053
310 We are now clarifying the behavior of log, plugins and configuration
311 during the setup phase. Since Plugins might require a log during
312 setup, setup_log must run BEFORE setup_plugins. This has the
313 unfortunate side effect that anyone using the popular ConfigLoader
314 plugin will not be able to supply configuration to custom logs since
315 the configuration is not yet finalized when setup_log is run (when
316 using ConfigLoader, which is a plugin and is not loaded until later.)
317 As a workaround, you can supply custom log configuration directly into
319 the configuration:
320 package MyApp;
322 use Catalyst;
323 __PACKAGE__->config(
325 my_custom_log_info => { %custom_args },
326 );
327 __PACKAGE__->setup;
329 If you wish to configure the custom logger differently based on ENV,
331 you can try:
332 package MyApp;
334 use Catalyst;
336 use Catalyst::Utils;
337 __PACKAGE__->config(
339 Catalyst::Utils::merge_hashes(
340 +{ my_custom_log_info => { %base_custom_args } },
341 +{ do __PACKAGE__->path_to( $ENV{WHICH_CONF}."_conf.pl") },
342 ),
343 );
344 __PACKAGE__->setup;
346 Or create a standalone Configuration class that does the right thing.
348 Basically if you want to configure a logger via Catalyst global
350 configuration you can't use ConfigLoader because it will always be
351 loaded too late to be of any use. Patches and workaround options
352 welcomed!
353 VERSION 5.9XXXX 'cataplack'
355 The Catalyst::Engine sub-classes have all been removed and deprecated,
356 to be replaced with Plack handlers.
357 Plack is an implementation of the PSGI specification, which is a
359 standard interface between web servers and application frameworks.
360 This should be no different for developers, and you should not have to
362 migrate your applications unless you are using a custom engine already.
363 This change benefits Catalyst significantly by reducing the amount of
365 code inside the framework, and means that the framework gets upstream
366 bug fixes in Plack, and automatically gains support for any web server
367 which a PSGI compliant handler is written for.
368 It also allows you more flexibility with your application, and allows
370 the use of cross web framework 'middleware'.
371 Developers are recommended to read Catalyst::Upgrading for notes about
373 upgrading, especially if you are using an unusual deployment method.
374 Documentation for how to take advantage of PSGI can be found in
376 Catalyst::PSGI, and information about deploying your application has
377 been moved to Catalyst::Manual::Deployment.
378 Updated modules:
380 A number of modules have been updated to pass their tests or not
382 produce deprecation warnings with the latest version of Catalyst. It
383 is recommended that you upgrade any of these that you are using after
384 installing this version of Catalyst.
385 These extensions are:
387 Catalyst::Engine::HTTP::Prefork
389 This is now deprecated, see Catalyst::Upgrading.
390 Test::WWW::Mechanize::Catalyst
392 Has been updated to not produce deprecation warnings, upgrade
393 recommended.
394 Catalyst::ActionRole::ACL
396 Has been updated to fix failing tests (although older versions
397 still function perfectly with this version of Catalyst).
398 Catalyst::Plugin::Session::Store::DBIC
400 Has been updated to fix failing tests (although older versions
401 still function perfectly with this version of Catalyst).
402 Catalyst::Plugin::Authentication
404 Has been updated to fix failing tests (although older versions
405 still function perfectly with this version of Catalyst).
406
408 VERSION 5.8XXXX 'catamoose'
409 Deprecations
410 Please see Catalyst::Upgrading for a full description of how changes in
412 the framework may affect your application.
413 Below is a brief list of features which have been deprecated in this
415 release:
416 ::[MVC]:: style naming scheme has been deprecated and will warn
418 NEXT is deprecated for all applications and components, use MRO::Compat
419 Dispatcher methods which are an implementation detail made private,
420 public versions now warn.
421 MyApp->plugin method is deprecated, use Catalyst::Model::Adaptor
422 instead.
423 __PACKAGE__->mk_accessors() is supported for backwards compatibility
424 only, use Moose attributes instead in new code.
425 Use of Catalyst::Base now warns
426 New features
428 Dispatcher
430 Fix forwarding to Catalyst::Action objects.
432 Add the dispatch_type method
433 Restarter
435 The development server restarter has been improved to be compatible
437 with immutable Moose classes, and also to optionally use
438 B::Hooks::OP::Check::StashChange to handle more complex application
439 layouts correctly.
440 $c->uri_for_action method.
442 Give a private path to the Catalyst action you want to create a URI
444 for.
445 Logging
447 Log levels have been made additive.
449 Catalyst::Test
451 Change to use Sub::Exporter.
453 Support mocking multiple virtual hosts
454 New methods like action_ok and action_redirect to write more compact
455 tests
456 Catalyst::Response
458 • New print method which prints @data to the output stream, separated
460 by $,. This lets you pass the response object to functions that
461 want to write to an IO::Handle.
462 • Added code method as an alias for "$res->status"
464 Consequences of the Moose back end
466 • Components are fully compatible with Moose, and all Moose features,
468 such as method modifiers, attributes, roles, BUILD and BUILDARGS
469 methods are fully supported and may be used in components and
470 applications.
471 • Many reusable extensions which would previously have been plugins
473 or base classes are better implemented as Moose roles.
474 • MooseX::MethodAttributes::Role::AttrContainer::Inheritable is used
476 to contain action attributes. This means that attributes are
477 represented in the MOP, and decouples action creation from
478 attributes.
479 • There is a reasonable API in Catalyst::Controller for working with
481 and registering actions, allowing a controller sub-class to replace
482 subroutine attributes for action declarations with an alternate
483 syntax.
484 • Refactored capturing of $app from Catalyst::Controller into
486 Catalyst::Component::ApplicationAttribute for easier reuse in other
487 components.
488 • Your application class is forced to become immutable at the end of
490 compilation.
491 Bug fixes
493 • Don't ignore SIGCHLD while handling requests with the development
495 server, so that system() and other ways of creating child processes
496 work as expected.
497 • Fixes for FastCGI when used with IIS 6.0
499 • Fix a bug in uri_for which could cause it to generate paths with
501 multiple slashes in them.
502 • Fix a bug in Catalyst::Stats, stopping garbage being inserted into
504 the stats if a user calls begin => but no end
505perl v5.38.0 2023-07-24 Catalyst::Delta(3)