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 Support passing Bpdy filehandles directly to your Plack server.
14 We changed the way we return body content (from response) to whatever
15 Plack handler you are using (Starman, FastCGI, etc.) We no longer
16 always use the streaming interface for the cases when the body is a
17 simple scalar, object or filehandle like. In those cases we now just
18 pass the simple response on to the plack handler. This might lead to
19 some minor differences in how streaming is handled. For example, you
20 might notice that streaming starts properly supportubg chunked encoding when
21 on a server that supports that, or that previously missing headers
22 (possible content-length) might appear suddenly correct. Also, if you
23 are using middleware like L<Plack::Middleware::XSendfile> and are using
24 a filehandle that sets a readable path, your server might now correctly
25 handle the file (rather than as before where Catalyst would stream it
26 very likely very slowly).
28 In other words, some things might be meaninglessly different and some
29 things that were broken codewise but worked because of Catalyst being
30 incorrect might suddenly be really broken. The behavior is now more
31 correct in that Catalyst plays better with features that Plack offers
32 but if you are making heavy use of the streaming interface there could
33 be some differences so you should test carefully (this is probably not
34 the vast majority of people). In particular if you are developing
35 using one server but deploying using a different one, differences in
36 what those server do with streaming should be noted.
38 Please see note below about changes to filehandle support and existing
39 Plack middleware to aid in back compatibility.
41 =head3 Distinguish between body null versus undef.
43 We also now more carefully distingush the different between a body set
44 to '' and a body that is undef. This might lead to situations where
45 again you'll get a content-length were you didn't get one before or
46 where a supporting server will start chunking output. If this is an
47 issue you can apply the middleware L<Plack::Middleware::BufferedStreaming>
48 or report specific problems to the dev team.
50 =head3 More Catalyst Middleware
52 We have started migrating code in Catalyst to equivilent Plack
53 Middleware when such exists and is correct to do so. For example we now use
54 L<Plack::Middleware::ContentLength> to determine content length of a response
55 when none is provided. This replaces similar code inlined with L<Catalyst>
56 The main advantages to doing this is 1) more similar Catalyst core that is
57 focused on the Catalyst special sauce, 2) Middleware is more broadly shared
58 so we benefit from better collaboration with developers outside Catalyst, 3)
59 In the future you'll be able to change or trim the middleware stack to get
60 additional performance when you don't need all the checks and constraints.
62 =head3 Deprecation of Filehandle like objects that do read but not getline
64 We also deprecated setting the response body to an object that does 'read'
65 but not 'getline'. If you are using a custom IO-Handle like object for
66 response you should verify that 'getline' is supported in your interface.
67 You will get a first use warning for this error in your logs. Unless we
68 here this case is a major issue for people, we will be removing support
69 in a near future release of Catalyst. When the code encounters this it
70 will issue a warning. You also may run into this issue with L<MogileFS::Client>
71 which does read but not getline. For now we will just warn when encountering
72 such an object and fallback to the previous behavior (where L<Catalyst::Engine>
73 itself unrolls the filehandle and performs blocking streams). However
74 this backcompat will be removed in an upcoming release so you should either
75 rewrite your custom filehandle objects to support getline or start using the
76 middleware that adapts read for getline L<Plack::Middleware::AdaptFilehandleRead>.
78 =head3 Response->headers become readonly after finalizing
80 Once the response headers are finalized, trying to change them is not allowed
81 (in the past you could change them and this would lead to unexpected results).
83 =head3 Offically deprecation of L<Catalyst::Engine::PSGI>
85 L<Catalyst::Engine::PSGI> is also officially no longer supported. We will
86 no long run test cases against this and can remove backcompat code for it
87 as deemed necessary for the evolution of the platform. You should simple
88 discontinue use of this engine, as L<Catalyst> has been PSGI at the core
91 =head2 Officially deprecate finding the PSGI $env anyplace other than Request
93 A few early releases of Cataplack had the PSGI $env in L<Catalyst::Engine>.
94 Code has been maintained here for backcompat reasons. This is no longer
95 supported and will be removed in upcoming release, so you should update
96 your code and / or upgrade to a newer version of L<Catalyst>
98 =head2 Deprecate setting Response->body after using write/write_fh
100 Setting $c->res->body to a filehandle after using $c->res->write or
101 $c->res->write_fh is no longer considered allowed, since we can't send
102 the filehandle to the underlying Plack handler. For now we will continue
103 to support setting body to a simple value since
105 =head2 VERSION 5.90053
107 We are now clarifying the behavior of log, plugins and configuration during
108 the setup phase. Since Plugins might require a log during setup, setup_log
109 must run BEFORE setup_plugins. This has the unfortunate side effect that
110 anyone using the popular ConfigLoader plugin will not be able to supply
111 configuration to custom logs since the configuration is not yet finalized
112 when setup_log is run (when using ConfigLoader, which is a plugin and is
113 not loaded until later.)
115 As a workaround, you can supply custom log configuration directly into
122 my_custom_log_info => { %custom_args },
127 If you wish to configure the custom logger differently based on ENV, you can
136 Catalyst::Utils::merge_hashes(
137 +{ my_custom_log_info => { %base_custom_args } },
138 +{ do __PACKAGE__->path_to( $ENV{WHICH_CONF}."_conf.pl") },
144 Or create a standalone Configuration class that does the right thing.
146 Basically if you want to configure a logger via Catalyst global configuration
147 you can't use ConfigLoader because it will always be loaded too late to be of
148 any use. Patches and workaround options welcomed!
150 =head2 VERSION 5.9XXXX 'cataplack'
152 The Catalyst::Engine sub-classes have all been removed and deprecated,
153 to be replaced with Plack handlers.
155 Plack is an implementation of the L<PSGI> specification, which is
156 a standard interface between web servers and application frameworks.
158 This should be no different for developers, and you should not have to
159 migrate your applications unless you are using a custom engine already.
161 This change benefits Catalyst significantly by reducing the amount of
162 code inside the framework, and means that the framework gets upstream
163 bug fixes in L<Plack>, and automatically gains support for any web server
164 which a L<PSGI> compliant handler is written for.
166 It also allows you more flexibility with your application, and allows
167 the use of cross web framework 'middleware'.
169 Developers are recommended to read L<Catalyst::Upgrading> for notes about
170 upgrading, especially if you are using an unusual deployment method.
172 Documentation for how to take advantage of L<PSGI> can be found in
173 L<Catalyst::PSGI>, and information about deploying your application
174 has been moved to L<Catalyst::Manual::Deployment>.
176 =head3 Updated modules:
178 A number of modules have been updated to pass their tests or not
179 produce deprecation warnings with the latest version of Catalyst.
180 It is recommended that you upgrade any of these that you are using
181 after installing this version of Catalyst.
183 These extensions are:
187 =item L<Catalyst::Engine::HTTP::Prefork>
189 This is now deprecated, see L<Catalyst::Upgrading>.
191 =item L<Test::WWW::Mechanize::Catalyst>
193 Has been updated to not produce deprecation warnings, upgrade recommended.
195 =item Catalyst::ActionRole::ACL
197 Has been updated to fix failing tests (although older versions still
198 function perfectly with this version of Catalyst).
200 =item Catalyst::Plugin::Session::Store::DBIC
202 Has been updated to fix failing tests (although older versions still
203 function perfectly with this version of Catalyst).
205 =item Catalyst::Plugin::Authentication
207 Has been updated to fix failing tests (although older versions still
208 function perfectly with this version of Catalyst).
212 =head1 PREVIOUS VERSIONS
214 =head2 VERSION 5.8XXXX 'catamoose'
218 Please see L<Catalyst::Upgrading> for a full description of how changes in the
219 framework may affect your application.
221 Below is a brief list of features which have been deprecated in this release:
225 =item ::[MVC]:: style naming scheme has been deprecated and will warn
227 =item NEXT is deprecated for all applications and components, use MRO::Compat
229 =item Dispatcher methods which are an implementation detail made private, public versions now warn.
231 =item MyApp->plugin method is deprecated, use L<Catalyst::Model::Adaptor> instead.
233 =item __PACKAGE__->mk_accessors() is supported for backward compatibility only, use Moose attributes instead in new code.
235 =item Use of Catalyst::Base now warns
245 =item Fix forwarding to Catalyst::Action objects.
247 =item Add the dispatch_type method
253 The development server restarter has been improved to be compatible with
254 immutable Moose classes, and also to optionally use
255 L<B::Hooks::OP::Check::StashChange> to handle more complex application layouts
258 =head3 $c->uri_for_action method.
260 Give a private path to the Catalyst action you want to create a URI for.
264 Log levels have been made additive.
266 =head3 L<Catalyst::Test>
270 =item Change to use L<Sub::Exporter>.
272 =item Support mocking multiple virtual hosts
274 =item New methods like action_ok and action_redirect to write more compact tests
278 =head3 Catalyst::Response
284 New print method which prints @data to the output stream, separated by $,.
285 This lets you pass the response object to functions that want to write to an
290 Added code method as an alias for C<< $res->status >>
294 =head3 Consequences of the Moose back end
300 Components are fully compatible with Moose, and all Moose features, such as
301 method modifiers, attributes, roles, BUILD and BUILDARGS methods are fully
302 supported and may be used in components and applications.
306 Many reusable extensions which would previously have been plugins or base
307 classes are better implemented as Moose roles.
311 L<MooseX::MethodAttributes::Role::AttrContainer::Inheritable> is used to contain action
312 attributes. This means that attributes are represented in the MOP, and
313 decouples action creation from attributes.
317 There is a reasonable API in Catalyst::Controller for working with
318 and registering actions, allowing a controller sub-class to replace
319 subroutine attributes for action declarations with an alternate
324 Refactored capturing of $app from L<Catalyst::Controller> into
325 L<Catalyst::Component::ApplicationAttribute> for easier reuse in other
330 Your application class is forced to become immutable at the end of compilation.
340 Don't ignore SIGCHLD while handling requests with the development server, so that
341 system() and other ways of creating child processes work as expected.
345 Fixes for FastCGI when used with IIS 6.0
349 Fix a bug in uri_for which could cause it to generate paths with multiple
354 Fix a bug in Catalyst::Stats, stopping garbage being inserted into
355 the stats if a user calls begin => but no end