3 Catalyst::Delta - Overview of changes between versions of Catalyst
7 This is an overview of the user-visible changes to Catalyst between major
10 =head2 VERSION 5.90060+
12 =head3 Catalyst::Log object autoflush on by default
14 Starting in 5.90065, the Catalyst::Log object has 'autoflush' which is on
15 by default. This causes all messages to be written to the log immediately
16 instead of at the end of startup and then at the end of each request. In
17 order to access the old behavior, you must now call:
19 $c->log->autoflush(0);
21 =head3 Deprecate Catalyst::Utils::ensure_class_loaded
23 Going forward we recommend you use L<Module::Runtime>. In fact we will
24 be converting all uses of L<Class::Load> to L<Module::Runtime>. We will
25 also convert L<Catalyst::Utils\ensure_class_loaded> to be based on
26 L<Module::Runtime> to allow some time for you to update code, however at
27 some future point this method will be removed so you should stop
30 =head3 Support passing Body filehandles directly to your Plack server.
32 We changed the way we return body content (from response) to whatever
33 Plack handler you are using (Starman, FastCGI, etc.) We no longer
34 always use the streaming interface for the cases when the body is a
35 simple scalar, object or filehandle like. In those cases we now just
36 pass the simple response on to the plack handler. This might lead to
37 some minor differences in how streaming is handled. For example, you
38 might notice that streaming starts properly supporting chunked encoding when
39 on a server that supports that, or that previously missing headers
40 (possible content-length) might appear suddenly correct. Also, if you
41 are using middleware like L<Plack::Middleware::XSendfile> and are using
42 a filehandle that sets a readable path, your server might now correctly
43 handle the file (rather than as before where Catalyst would stream it
44 very likely very slowly).
46 In other words, some things might be meaninglessly different and some
47 things that were broken codewise but worked because of Catalyst being
48 incorrect might suddenly be really broken. The behavior is now more
49 correct in that Catalyst plays better with features that Plack offers
50 but if you are making heavy use of the streaming interface there could
51 be some differences so you should test carefully (this is probably not
52 the vast majority of people). In particular if you are developing
53 using one server but deploying using a different one, differences in
54 what those server do with streaming should be noted.
56 Please see note below about changes to filehandle support and existing
57 Plack middleware to aid in backwards compatibility.
59 =head3 Distinguish between body null versus undef.
61 We also now more carefully distingush the different between a body set
62 to '' and a body that is undef. This might lead to situations where
63 again you'll get a content-length were you didn't get one before or
64 where a supporting server will start chunking output. If this is an
65 issue you can apply the middleware L<Plack::Middleware::BufferedStreaming>
66 or report specific problems to the dev team.
68 =head3 More Catalyst Middleware
70 We have started migrating code in Catalyst to equivilent Plack
71 Middleware when such exists and is correct to do so. For example we now use
72 L<Plack::Middleware::ContentLength> to determine content length of a response
73 when none is provided. This replaces similar code inlined with L<Catalyst>
74 The main advantages to doing this is 1) more similar Catalyst core that is
75 focused on the Catalyst special sauce, 2) Middleware is more broadly shared
76 so we benefit from better collaboration with developers outside Catalyst, 3)
77 In the future you'll be able to change or trim the middleware stack to get
78 additional performance when you don't need all the checks and constraints.
80 =head3 Deprecate Filehandle like objects that do read but not getline
82 We also deprecated setting the response body to an object that does 'read'
83 but not 'getline'. If you are using a custom IO-Handle like object for
84 response you should verify that 'getline' is supported in your interface.
85 Unless we here this case is a major issue for people, we will be removing support
86 in a near future release of Catalyst. When the code encounters this it
87 will issue a warning. You also may run into this issue with L<MogileFS::Client>
88 which does read but not getline. For now we will just warn when encountering
89 such an object and fallback to the previous behavior (where L<Catalyst::Engine>
90 itself unrolls the filehandle and performs blocking streams). However
91 this backwards compatibility will be removed in an upcoming release so you should either
92 rewrite your custom filehandle objects to support getline or start using the
93 middleware that adapts read for getline L<Plack::Middleware::AdaptFilehandleRead>.
95 =head3 Response->headers become read-only after finalizing
97 Once the response headers are finalized, trying to change them is not allowed
98 (in the past you could change them and this would lead to unexpected results).
100 =head3 Officially deprecate L<Catalyst::Engine::PSGI>
102 L<Catalyst::Engine::PSGI> is also officially no longer supported. We will
103 no long run test cases against this and can remove backwards compatibility code for it
104 as deemed necessary for the evolution of the platform. You should simply
105 discontinue use of this engine, as L<Catalyst> has been PSGI at the core for
108 =head3 Officially deprecate finding the PSGI $env anyplace other than Request
110 A few early releases of Cataplack had the PSGI $env in L<Catalyst::Engine>.
111 Code has been maintained here for backwards compatibility reasons. This is no
112 longer supported and will be removed in upcoming release, so you should update
113 your code and / or upgrade to a newer version of L<Catalyst>
115 =head3 Deprecate setting Response->body after using write/write_fh
117 Setting $c->res->body to a filehandle after using $c->res->write or
118 $c->res->write_fh is no longer considered allowed, since we can't send
119 the filehandle to the underlying Plack handler. For now we will continue
120 to support setting body to a simple value since this is possible, but at
121 some future release a choice to use streaming indicates that you will do
122 so for the rest of the request.
125 =head2 VERSION 5.90053
127 We are now clarifying the behavior of log, plugins and configuration during
128 the setup phase. Since Plugins might require a log during setup, setup_log
129 must run BEFORE setup_plugins. This has the unfortunate side effect that
130 anyone using the popular ConfigLoader plugin will not be able to supply
131 configuration to custom logs since the configuration is not yet finalized
132 when setup_log is run (when using ConfigLoader, which is a plugin and is
133 not loaded until later.)
135 As a workaround, you can supply custom log configuration directly into
142 my_custom_log_info => { %custom_args },
147 If you wish to configure the custom logger differently based on ENV, you can
156 Catalyst::Utils::merge_hashes(
157 +{ my_custom_log_info => { %base_custom_args } },
158 +{ do __PACKAGE__->path_to( $ENV{WHICH_CONF}."_conf.pl") },
164 Or create a standalone Configuration class that does the right thing.
166 Basically if you want to configure a logger via Catalyst global configuration
167 you can't use ConfigLoader because it will always be loaded too late to be of
168 any use. Patches and workaround options welcomed!
170 =head2 VERSION 5.9XXXX 'cataplack'
172 The Catalyst::Engine sub-classes have all been removed and deprecated,
173 to be replaced with Plack handlers.
175 Plack is an implementation of the L<PSGI> specification, which is
176 a standard interface between web servers and application frameworks.
178 This should be no different for developers, and you should not have to
179 migrate your applications unless you are using a custom engine already.
181 This change benefits Catalyst significantly by reducing the amount of
182 code inside the framework, and means that the framework gets upstream
183 bug fixes in L<Plack>, and automatically gains support for any web server
184 which a L<PSGI> compliant handler is written for.
186 It also allows you more flexibility with your application, and allows
187 the use of cross web framework 'middleware'.
189 Developers are recommended to read L<Catalyst::Upgrading> for notes about
190 upgrading, especially if you are using an unusual deployment method.
192 Documentation for how to take advantage of L<PSGI> can be found in
193 L<Catalyst::PSGI>, and information about deploying your application
194 has been moved to L<Catalyst::Manual::Deployment>.
196 =head3 Updated modules:
198 A number of modules have been updated to pass their tests or not
199 produce deprecation warnings with the latest version of Catalyst.
200 It is recommended that you upgrade any of these that you are using
201 after installing this version of Catalyst.
203 These extensions are:
207 =item L<Catalyst::Engine::HTTP::Prefork>
209 This is now deprecated, see L<Catalyst::Upgrading>.
211 =item L<Test::WWW::Mechanize::Catalyst>
213 Has been updated to not produce deprecation warnings, upgrade recommended.
215 =item Catalyst::ActionRole::ACL
217 Has been updated to fix failing tests (although older versions still
218 function perfectly with this version of Catalyst).
220 =item Catalyst::Plugin::Session::Store::DBIC
222 Has been updated to fix failing tests (although older versions still
223 function perfectly with this version of Catalyst).
225 =item Catalyst::Plugin::Authentication
227 Has been updated to fix failing tests (although older versions still
228 function perfectly with this version of Catalyst).
232 =head1 PREVIOUS VERSIONS
234 =head2 VERSION 5.8XXXX 'catamoose'
238 Please see L<Catalyst::Upgrading> for a full description of how changes in the
239 framework may affect your application.
241 Below is a brief list of features which have been deprecated in this release:
245 =item ::[MVC]:: style naming scheme has been deprecated and will warn
247 =item NEXT is deprecated for all applications and components, use MRO::Compat
249 =item Dispatcher methods which are an implementation detail made private, public versions now warn.
251 =item MyApp->plugin method is deprecated, use L<Catalyst::Model::Adaptor> instead.
253 =item __PACKAGE__->mk_accessors() is supported for backwards compatibility only, use Moose attributes instead in new code.
255 =item Use of Catalyst::Base now warns
265 =item Fix forwarding to Catalyst::Action objects.
267 =item Add the dispatch_type method
273 The development server restarter has been improved to be compatible with
274 immutable Moose classes, and also to optionally use
275 L<B::Hooks::OP::Check::StashChange> to handle more complex application layouts
278 =head3 $c->uri_for_action method.
280 Give a private path to the Catalyst action you want to create a URI for.
284 Log levels have been made additive.
286 =head3 L<Catalyst::Test>
290 =item Change to use L<Sub::Exporter>.
292 =item Support mocking multiple virtual hosts
294 =item New methods like action_ok and action_redirect to write more compact tests
298 =head3 Catalyst::Response
304 New print method which prints @data to the output stream, separated by $,.
305 This lets you pass the response object to functions that want to write to an
310 Added code method as an alias for C<< $res->status >>
314 =head3 Consequences of the Moose back end
320 Components are fully compatible with Moose, and all Moose features, such as
321 method modifiers, attributes, roles, BUILD and BUILDARGS methods are fully
322 supported and may be used in components and applications.
326 Many reusable extensions which would previously have been plugins or base
327 classes are better implemented as Moose roles.
331 L<MooseX::MethodAttributes::Role::AttrContainer::Inheritable> is used to contain action
332 attributes. This means that attributes are represented in the MOP, and
333 decouples action creation from attributes.
337 There is a reasonable API in Catalyst::Controller for working with
338 and registering actions, allowing a controller sub-class to replace
339 subroutine attributes for action declarations with an alternate
344 Refactored capturing of $app from L<Catalyst::Controller> into
345 L<Catalyst::Component::ApplicationAttribute> for easier reuse in other
350 Your application class is forced to become immutable at the end of compilation.
360 Don't ignore SIGCHLD while handling requests with the development server, so that
361 system() and other ways of creating child processes work as expected.
365 Fixes for FastCGI when used with IIS 6.0
369 Fix a bug in uri_for which could cause it to generate paths with multiple
374 Fix a bug in Catalyst::Stats, stopping garbage being inserted into
375 the stats if a user calls begin => but no end