1Catalyst::Delta(3)    User Contributed Perl Documentation   Catalyst::Delta(3)
2
3
4

NAME

6       Catalyst::Delta - Overview of changes between versions of Catalyst
7

DESCRIPTION

9       This is an overview of the user-visible changes to Catalyst between
10       major Catalyst releases.
11
12   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
22       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
30   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
41       Additionally, upon $c->detach we also force set state to 0.
42
43       Version 5.90102 contains a version of this change but its considered
44       buggy, so that is a version to avoid.
45
46   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
52       You may now. also use a full type constraint namespace instead of
53       importing type constraints into your package namespace.
54
55       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
64   VERSION 5.90097
65       Defined how $c->uri_for adds a URI fragment.
66
67       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
74           $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment);
75
76       This will be a breaking change for some codebases, we recommend testing
77       if you are creating URLs with fragments.
78
79       NOTE If you are using the alternative:
80
81           $c->uri_for('/foo/bar#baz')
82
83       construction, we do not attempt to encode this and it will make a URL
84       with a fragment of 'baz'.
85
86   VERSION 5.90094
87       Multipart form POST with character set headers
88
89       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
100   VERSION 5.90091
101       'case_sensitive' configuration
102
103       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
109   VERSION 5.90090+
110       Type constraints on Args and CaptureArgs.
111
112       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
116           sub myaction :Local Args(Int) { ... }
117
118       Would match '.../myaction/5' but not '.../myaction/string'.
119
120       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
124       See Catalyst::RouteMatching for more.
125
126       Move CatalystX::InjectComponent into core
127
128       Catalyst::Utils has a new method 'inject_component' which works the
129       same as the method of the same name in CatalystX::InjectComponent.
130
131       inject_components
132
133       New configuration key allows you to inject components directly into
134       your application without any subclasses.  For example:
135
136           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
147       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
151       Component setup changes.
152
153       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
158   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
166       If this change causes you trouble, you can disable it:
167
168           __PACKAGE__->config(encoding=>undef);
169
170       For further information, please see Catalyst::UTF8
171
172       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
178       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
182       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
191   VERSION 5.90060+
192       Catalyst::Log object autoflush on by default
193
194       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
199         $c->log->autoflush(0);
200
201       Deprecate Catalyst::Utils::ensure_class_loaded
202
203       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
210       Support passing Body filehandles directly to your Plack server.
211
212       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
226       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
236       Please see note below about changes to filehandle support and existing
237       Plack middleware to aid in backwards compatibility.
238
239       Distinguish between body null versus undef.
240
241       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
248       More Catalyst Middleware
249
250       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
261       Deprecate Filehandle like objects that do read but not getline
262
263       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
278       Response->headers become read-only after finalizing
279
280       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
284       Officially deprecate Catalyst::Engine::PSGI
285
286       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
292       Officially deprecate finding the PSGI $env anyplace other than Request
293
294       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
300       Deprecate setting Response->body after using write/write_fh
301
302       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
309   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
318       As a workaround, you can supply custom log configuration directly into
319       the configuration:
320
321           package MyApp;
322           use Catalyst;
323
324           __PACKAGE__->config(
325             my_custom_log_info => { %custom_args },
326           );
327
328           __PACKAGE__->setup;
329
330       If you wish to configure the custom logger differently based on ENV,
331       you can try:
332
333           package MyApp;
334
335           use Catalyst;
336           use Catalyst::Utils;
337
338           __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
345           __PACKAGE__->setup;
346
347       Or create a standalone Configuration class that does the right thing.
348
349       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
354   VERSION 5.9XXXX 'cataplack'
355       The Catalyst::Engine sub-classes have all been removed and deprecated,
356       to be replaced with Plack handlers.
357
358       Plack is an implementation of the PSGI specification, which is a
359       standard interface between web servers and application frameworks.
360
361       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
364       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
369       It also allows you more flexibility with your application, and allows
370       the use of cross web framework 'middleware'.
371
372       Developers are recommended to read Catalyst::Upgrading for notes about
373       upgrading, especially if you are using an unusual deployment method.
374
375       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
379       Updated modules:
380
381       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
386       These extensions are:
387
388       Catalyst::Engine::HTTP::Prefork
389           This is now deprecated, see Catalyst::Upgrading.
390
391       Test::WWW::Mechanize::Catalyst
392           Has been updated to not produce deprecation warnings, upgrade
393           recommended.
394
395       Catalyst::ActionRole::ACL
396           Has been updated to fix failing tests (although older versions
397           still function perfectly with this version of Catalyst).
398
399       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
403       Catalyst::Plugin::Authentication
404           Has been updated to fix failing tests (although older versions
405           still function perfectly with this version of Catalyst).
406

PREVIOUS VERSIONS

408   VERSION 5.8XXXX 'catamoose'
409       Deprecations
410
411       Please see Catalyst::Upgrading for a full description of how changes in
412       the framework may affect your application.
413
414       Below is a brief list of features which have been deprecated in this
415       release:
416
417       ::[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
427       New features
428
429       Dispatcher
430
431       Fix forwarding to Catalyst::Action objects.
432       Add the dispatch_type method
433
434       Restarter
435
436       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
441       $c->uri_for_action method.
442
443       Give a private path to the Catalyst action you want to create a URI
444       for.
445
446       Logging
447
448       Log levels have been made additive.
449
450       Catalyst::Test
451
452       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
457       Catalyst::Response
458
459       •   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
463       •   Added code method as an alias for "$res->status"
464
465       Consequences of the Moose back end
466
467       •   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
472       •   Many reusable extensions which would previously have been plugins
473           or base classes are better implemented as Moose roles.
474
475       •   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
480       •   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
485       •   Refactored capturing of $app from Catalyst::Controller into
486           Catalyst::Component::ApplicationAttribute for easier reuse in other
487           components.
488
489       •   Your application class is forced to become immutable at the end of
490           compilation.
491
492       Bug fixes
493
494       •   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
498       •   Fixes for FastCGI when used with IIS 6.0
499
500       •   Fix a bug in uri_for which could cause it to generate paths with
501           multiple slashes in them.
502
503       •   Fix a bug in Catalyst::Stats, stopping garbage being inserted into
504           the stats if a user calls begin => but no end
505
506
507
508perl v5.34.0                      2022-01-21                Catalyst::Delta(3)
Impressum