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