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