lib/Catalyst/Delta.pod

   1 =head1 NAME
   2
   3 Catalyst::Delta - Overview of changes between versions of Catalyst
   4
   5 =head1 DESCRIPTION
   6
   7 This is an overview of the user-visible changes to Catalyst between major
   8 Catalyst releases.
   9
  10 =head2 VERSION 5.90080+
  11
  12 The biggest change in this release is that UTF8 encoding is now enabled by
  13 default.  So you no longer need any plugins (such as L<Catalyst::Plugin::Unicode::Encoding>)
  14 which you can just no go ahead and remove.  You also don't need to set
  15 the encoding configuration (__PACKAGE__->config(encoding=>'UTF-8')) anymore
  16 as well (although its presense hurts nothing).
  17
  18 If this change causes you trouble, you can disable it:
  19
  20     __PACKAGE__->config(encoding=>undef);
  21
  22 But please report bugs.  You will find that a number of common Views have been
  23 updated for this release (such as L<Catalyst::View::TT>).  In all cases that the
  24 author is aware of these updates were to fix test cases only.  You shouldn't
  25 need to update unless you are installing fresh and want tests to pass.
  26
  27 L<Catalyst::Plugin::Compress> was updated to be compatible with this release.
  28 You will need to upgrade if you are using this plugin.
  29
  30 A small change is that the configuration setting C<using_frontend_proxy>
  31 was not doing the right thing if you started your application with C<psgi_app>
  32 and dod not apply the default middleware.  This setting is now honored in
  33 all the ways an application may be started.  This could cause trouble if you
  34 are using the configuration value and also adding the proxy middleware
  35 manually with a custom application startup.  The solution is that you only
  36 need the configuration value set, or the middleware manually added (not both).
  37
  38 =head2 VERSION 5.90060+
  39
  40 =head3 Catalyst::Log object autoflush on by default
  41
  42 Starting in 5.90065, the Catalyst::Log object has 'autoflush' which is on
  43 by default. This causes all messages to be written to the log immediately
  44 instead of at the end of startup and then at the end of each request. In
  45 order to access the old behavior, you must now call:
  46
  47   $c->log->autoflush(0);
  48
  49 =head3 Deprecate Catalyst::Utils::ensure_class_loaded
  50
  51 Going forward we recommend you use L<Module::Runtime>.  In fact we will
  52 be converting all uses of L<Class::Load> to L<Module::Runtime>.  We will
  53 also convert L<Catalyst::Utils\ensure_class_loaded> to be based on
  54 L<Module::Runtime> to allow some time for you to update code, however at
  55 some future point this method will be removed so you should stop
  56 using it now.
  57
  58 =head3 Support passing Body filehandles directly to your Plack server.
  59
  60 We changed the way we return body content (from response) to whatever
  61 Plack handler you are using (Starman, FastCGI, etc.)  We no longer
  62 always use the streaming interface for the cases when the body is a
  63 simple scalar, object or filehandle like.  In those cases we now just
  64 pass the simple response on to the plack handler.  This might lead to
  65 some minor differences in how streaming is handled.  For example, you
  66 might notice that streaming starts properly supporting chunked encoding when
  67 on a server that supports that, or that previously missing headers
  68 (possible content-length) might appear suddenly correct.  Also, if you
  69 are using middleware like L<Plack::Middleware::XSendfile> and are using
  70 a filehandle that sets a readable path, your server might now correctly
  71 handle the file (rather than as before where Catalyst would stream it
  72 very likely very slowly).
  73
  74 In other words, some things might be meaninglessly different and some
  75 things that were broken codewise but worked because of Catalyst being
  76 incorrect might suddenly be really broken.  The behavior is now more
  77 correct in that Catalyst plays better with features that Plack offers
  78 but if you are making heavy use of the streaming interface there could
  79 be some differences so you should test carefully (this is probably not
  80 the vast majority of people).  In particular if you are developing
  81 using one server but deploying using a different one, differences in
  82 what those server do with streaming should be noted.
  83
  84 Please see note below about changes to filehandle support and existing
  85 Plack middleware to aid in backwards compatibility.
  86
  87 =head3 Distinguish between body null versus undef.
  88
  89 We also now more carefully distingush the different between a body set
  90 to '' and a body that is undef.  This might lead to situations where
  91 again you'll get a content-length were you didn't get one before or
  92 where a supporting server will start chunking output.  If this is an
  93 issue you can apply the middleware L<Plack::Middleware::BufferedStreaming>
  94 or report specific problems to the dev team.
  95
  96 =head3 More Catalyst Middleware
  97
  98 We have started migrating code in Catalyst to equivilent Plack
  99 Middleware when such exists and is correct to do so.  For example we now use
 100 L<Plack::Middleware::ContentLength> to determine content length of a response
 101 when none is provided.  This replaces similar code inlined with L<Catalyst>
 102 The main advantages to doing this is 1) more similar Catalyst core that is
 103 focused on the Catalyst special sauce, 2) Middleware is more broadly shared
 104 so we benefit from better collaboration with developers outside Catalyst, 3)
 105 In the future you'll be able to change or trim the middleware stack to get
 106 additional performance when you don't need all the checks and constraints.
 107
 108 =head3 Deprecate Filehandle like objects that do read but not getline
 109
 110 We also deprecated setting the response body to an object that does 'read'
 111 but not 'getline'.  If you are using a custom IO-Handle like object for
 112 response you should verify that 'getline' is supported in your interface.
 113 Unless we here this case is a major issue for people, we will be removing support
 114 in a near future release of Catalyst.  When the code encounters this it
 115 will issue a warning.  You also may run into this issue with L<MogileFS::Client>
 116 which does read but not getline.  For now we will just warn when encountering
 117 such an object and fallback to the previous behavior (where L<Catalyst::Engine>
 118 itself unrolls the filehandle and performs blocking streams).  However
 119 this backwards compatibility will be removed in an upcoming release so you should either
 120 rewrite your custom filehandle objects to support getline or start using the
 121 middleware that adapts read for getline L<Plack::Middleware::AdaptFilehandleRead>.
 122
 123 =head3 Response->headers become read-only after finalizing
 124
 125 Once the response headers are finalized, trying to change them is not allowed
 126 (in the past you could change them and this would lead to unexpected results).
 127
 128 =head3 Officially deprecate L<Catalyst::Engine::PSGI>
 129
 130 L<Catalyst::Engine::PSGI> is also officially no longer supported.  We will
 131 no long run test cases against this and can remove backwards compatibility code for it
 132 as deemed necessary for the evolution of the platform.  You should simply
 133 discontinue use of this engine, as L<Catalyst> has been PSGI at the core for
 134 several years.
 135
 136 =head3 Officially deprecate finding the PSGI $env anyplace other than Request
 137
 138 A few early releases of Cataplack had the PSGI $env in L<Catalyst::Engine>.
 139 Code has been maintained here for backwards compatibility reasons.  This is no
 140 longer supported and will be removed in upcoming release, so you should update
 141 your code and / or upgrade to a newer version of L<Catalyst>
 142
 143 =head3 Deprecate setting Response->body after using write/write_fh
 144
 145 Setting $c->res->body to a filehandle after using $c->res->write or
 146 $c->res->write_fh is no longer considered allowed, since we can't send
 147 the filehandle to the underlying Plack handler.  For now we will continue
 148 to support setting body to a simple value since this is possible, but at
 149 some future release a choice to use streaming indicates that you will do
 150 so for the rest of the request.
 151
 152
 153 =head2 VERSION 5.90053
 154
 155 We are now clarifying the behavior of log, plugins and configuration during
 156 the setup phase.  Since Plugins might require a log during setup, setup_log
 157 must run BEFORE setup_plugins.   This has the unfortunate side effect that
 158 anyone using the popular ConfigLoader plugin will not be able to supply
 159 configuration to custom logs since the configuration is not yet finalized
 160 when setup_log is run (when using ConfigLoader, which is a plugin and is
 161 not loaded until later.)
 162
 163 As a workaround, you can supply custom log configuration directly into
 164 the configuration:
 165
 166     package MyApp;
 167     use Catalyst;
 168
 169     __PACKAGE__->config(
 170       my_custom_log_info => { %custom_args },
 171     );
 172
 173     __PACKAGE__->setup;
 174
 175 If you wish to configure the custom logger differently based on ENV, you can
 176 try:
 177
 178     package MyApp;
 179
 180     use Catalyst;
 181     use Catalyst::Utils;
 182
 183     __PACKAGE__->config(
 184       Catalyst::Utils::merge_hashes(
 185         +{ my_custom_log_info => { %base_custom_args } },
 186         +{ do __PACKAGE__->path_to( $ENV{WHICH_CONF}."_conf.pl") },
 187       ),
 188     );
 189
 190     __PACKAGE__->setup;
 191
 192 Or create a standalone Configuration class that does the right thing.
 193
 194 Basically if you want to configure a logger via Catalyst global configuration
 195 you can't use ConfigLoader because it will always be loaded too late to be of
 196 any use.  Patches and workaround options welcomed!
 197
 198 =head2 VERSION 5.9XXXX 'cataplack'
 199
 200 The Catalyst::Engine sub-classes have all been removed and deprecated,
 201 to be replaced with Plack handlers.
 202
 203 Plack is an implementation of the L<PSGI> specification, which is
 204 a standard interface between web servers and application frameworks.
 205
 206 This should be no different for developers, and you should not have to
 207 migrate your applications unless you are using a custom engine already.
 208
 209 This change benefits Catalyst significantly by reducing the amount of
 210 code inside the framework, and means that the framework gets upstream
 211 bug fixes in L<Plack>, and automatically gains support for any web server
 212 which a L<PSGI> compliant handler is written for.
 213
 214 It also allows you more flexibility with your application, and allows
 215 the use of cross web framework 'middleware'.
 216
 217 Developers are recommended to read L<Catalyst::Upgrading> for notes about
 218 upgrading, especially if you are using an unusual deployment method.
 219
 220 Documentation for how to take advantage of L<PSGI> can be found in
 221 L<Catalyst::PSGI>, and information about deploying your application
 222 has been moved to L<Catalyst::Manual::Deployment>.
 223
 224 =head3 Updated modules:
 225
 226 A number of modules have been updated to pass their tests or not
 227 produce deprecation warnings with the latest version of Catalyst.
 228 It is recommended that you upgrade any of these that you are using
 229 after installing this version of Catalyst.
 230
 231 These extensions are:
 232
 233 =over
 234
 235 =item L<Catalyst::Engine::HTTP::Prefork>
 236
 237 This is now deprecated, see L<Catalyst::Upgrading>.
 238
 239 =item L<Test::WWW::Mechanize::Catalyst>
 240
 241 Has been updated to not produce deprecation warnings, upgrade recommended.
 242
 243 =item Catalyst::ActionRole::ACL
 244
 245 Has been updated to fix failing tests (although older versions still
 246 function perfectly with this version of Catalyst).
 247
 248 =item Catalyst::Plugin::Session::Store::DBIC
 249
 250 Has been updated to fix failing tests (although older versions still
 251 function perfectly with this version of Catalyst).
 252
 253 =item Catalyst::Plugin::Authentication
 254
 255 Has been updated to fix failing tests (although older versions still
 256 function perfectly with this version of Catalyst).
 257
 258 =back
 259
 260 =head1 PREVIOUS VERSIONS
 261
 262 =head2 VERSION 5.8XXXX 'catamoose'
 263
 264 =head3 Deprecations
 265
 266 Please see L<Catalyst::Upgrading> for a full description of how changes in the
 267 framework may affect your application.
 268
 269 Below is a brief list of features which have been deprecated in this release:
 270
 271 =over
 272
 273 =item ::[MVC]:: style naming scheme has been deprecated and will warn
 274
 275 =item NEXT is deprecated for all applications and components, use MRO::Compat
 276
 277 =item Dispatcher methods which are an implementation detail made private, public versions now warn.
 278
 279 =item MyApp->plugin method is deprecated, use L<Catalyst::Model::Adaptor> instead.
 280
 281 =item __PACKAGE__->mk_accessors() is supported for backwards compatibility only, use Moose attributes instead in new code.
 282
 283 =item Use of Catalyst::Base now warns
 284
 285 =back
 286
 287 =head3 New features
 288
 289 =head3 Dispatcher
 290
 291 =over
 292
 293 =item Fix forwarding to Catalyst::Action objects.
 294
 295 =item Add the dispatch_type method
 296
 297 =back
 298
 299 =head3 Restarter
 300
 301 The development server restarter has been improved to be compatible with
 302 immutable Moose classes, and also to optionally use
 303 L<B::Hooks::OP::Check::StashChange> to handle more complex application layouts
 304 correctly.
 305
 306 =head3 $c->uri_for_action method.
 307
 308 Give a private path to the Catalyst action you want to create a URI for.
 309
 310 =head3 Logging
 311
 312 Log levels have been made additive.
 313
 314 =head3 L<Catalyst::Test>
 315
 316 =over
 317
 318 =item Change to use L<Sub::Exporter>.
 319
 320 =item Support mocking multiple virtual hosts
 321
 322 =item New methods like action_ok and action_redirect to write more compact tests
 323
 324 =back
 325
 326 =head3 Catalyst::Response
 327
 328 =over
 329
 330 =item *
 331
 332 New print method which prints @data to the output stream, separated by $,.
 333 This lets you pass the response object to functions that want to write to an
 334 L<IO::Handle>.
 335
 336 =item *
 337
 338 Added code method as an alias for C<< $res->status >>
 339
 340 =back
 341
 342 =head3 Consequences of the Moose back end
 343
 344 =over
 345
 346 =item *
 347
 348 Components are fully compatible with Moose, and all Moose features, such as
 349 method modifiers, attributes, roles, BUILD and BUILDARGS methods are fully
 350 supported and may be used in components and applications.
 351
 352 =item *
 353
 354 Many reusable extensions which would previously have been plugins or base
 355 classes are better implemented as Moose roles.
 356
 357 =item *
 358
 359 L<MooseX::MethodAttributes::Role::AttrContainer::Inheritable> is used to contain action
 360 attributes. This means that attributes are represented in the MOP, and
 361 decouples action creation from attributes.
 362
 363 =item *
 364
 365 There is a reasonable API in Catalyst::Controller for working with
 366 and registering actions, allowing a controller sub-class to replace
 367 subroutine attributes for action declarations with an alternate
 368 syntax.
 369
 370 =item *
 371
 372 Refactored capturing of $app from L<Catalyst::Controller> into
 373 L<Catalyst::Component::ApplicationAttribute> for easier reuse in other
 374 components.
 375
 376 =item *
 377
 378 Your application class is forced to become immutable at the end of compilation.
 379
 380 =back
 381
 382 =head3 Bug fixes
 383
 384 =over
 385
 386 =item *
 387
 388 Don't ignore SIGCHLD while handling requests with the development server, so that
 389 system() and other ways of creating child processes work as expected.
 390
 391 =item *
 392
 393 Fixes for FastCGI when used with IIS 6.0
 394
 395 =item *
 396
 397 Fix a bug in uri_for which could cause it to generate paths with multiple
 398 slashes in them.
 399
 400 =item *
 401
 402 Fix a bug in Catalyst::Stats, stopping garbage being inserted into
 403 the stats if a user calls begin => but no end
 404
 405 =back
 406