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