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.90060+
  11
  12 We changed the way we return body content (from response) to whatever
  13 Plack handler you are using (Starman, FastCGI, etc.)  We no longer
  14 always use the streaming interface for the cases when the body is a
  15 simple scalar, object or filehandle like.  In those cases we now just
  16 pass the simple response on to the plack handler.  This might lead to
  17 some minor differences in how streaming is handled.  For example, you
  18 might notice that streaming starts using chunked encoding when running
  19 on a server that supports that, or that previously missing headers
  20 (possible content-length) might appear suddenly correct.  Also, if you
  21 are using middleware like L<Plack::Middleware::XSendfile> and are using
  22 a filehandle that sets a readable path, your server might now correctly
  23 handle the file (rather than as before where Catalyst would stream it
  24 very likely very slowly).
  25
  26 In other words, some things might be meaninglessly different and some
  27 things that were broken codewise but worked because of Catalyst being
  28 incorrect might suddenly be really broken.  The behavior is now more
  29 correct in that Catalyst plays better with features that Plack offers
  30 but if you are making heavy use of the streaming interface there could
  31 be some differences so you should test carefully (this is probably not
  32 the vast majority of people).  In particular if you are developing
  33 using one server but deploying using a different one, differences in
  34 what those server do with streaming should be noted.
  35
  36 We also now more carefully distingush the different between a body set
  37 to '' and a body that is undef.  This might lead to situations where
  38 again you'll get a content-length were you didn't get one before or
  39 where a supporting server will start chunking output.  If this is an
  40 issue you can apply the middleware L<Plack::Middleware::BufferedStreaming>
  41 or report specific problems to the dev team.
  42
  43 Also, we have started migrating code in Catalyst to equivilent Plack
  44 Middleware when such exists and is correct to do so.
  45
  46 =head2 VERSION 5.90053
  47
  48 We are now clarifying the behavior of log, plugins and configuration during
  49 the setup phase.  Since Plugins might require a log during setup, setup_log
  50 must run BEFORE setup_plugins.   This has the unfortunate side effect that
  51 anyone using the popular ConfigLoader plugin will not be able to supply
  52 configuration to custom logs since the configuration is not yet finalized
  53 when setup_log is run (when using ConfigLoader, which is a plugin and is
  54 not loaded until later.)
  55
  56 As a workaround, you can supply custom log configuration directly into
  57 the configuration:
  58
  59     package MyApp;
  60     use Catalyst;
  61
  62     __PACKAGE__->config(
  63       my_custom_log_info => { %custom_args },
  64     );
  65
  66     __PACKAGE__->setup;
  67
  68 If you wish to configure the custom logger differently based on ENV, you can
  69 try:
  70
  71     package MyApp;
  72
  73     use Catalyst;
  74     use Catalyst::Utils;
  75
  76     __PACKAGE__->config(
  77       Catalyst::Utils::merge_hashes(
  78         +{ my_custom_log_info => { %base_custom_args } },
  79         +{ do __PACKAGE__->path_to( $ENV{WHICH_CONF}."_conf.pl") },
  80       ),
  81     );
  82
  83     __PACKAGE__->setup;
  84
  85 Or create a standalone Configuration class that does the right thing.
  86
  87 Basically if you want to configure a logger via Catalyst global configuration
  88 you can't use ConfigLoader because it will always be loaded too late to be of
  89 any use.  Patches and workaround options welcomed!
  90
  91 =head2 VERSION 5.9XXXX 'cataplack'
  92
  93 The Catalyst::Engine sub-classes have all been removed and deprecated,
  94 to be replaced with Plack handlers.
  95
  96 Plack is an implementation of the L<PSGI> specification, which is
  97 a standard interface between web servers and application frameworks.
  98
  99 This should be no different for developers, and you should not have to
 100 migrate your applications unless you are using a custom engine already.
 101
 102 This change benefits Catalyst significantly by reducing the amount of
 103 code inside the framework, and means that the framework gets upstream
 104 bug fixes in L<Plack>, and automatically gains support for any web server
 105 which a L<PSGI> compliant handler is written for.
 106
 107 It also allows you more flexibility with your application, and allows
 108 the use of cross web framework 'middleware'.
 109
 110 Developers are recommended to read L<Catalyst::Upgrading> for notes about
 111 upgrading, especially if you are using an unusual deployment method.
 112
 113 Documentation for how to take advantage of L<PSGI> can be found in
 114 L<Catalyst::PSGI>, and information about deploying your application
 115 has been moved to L<Catalyst::Manual::Deployment>.
 116
 117 =head3 Updated modules:
 118
 119 A number of modules have been updated to pass their tests or not
 120 produce deprecation warnings with the latest version of Catalyst.
 121 It is recommended that you upgrade any of these that you are using
 122 after installing this version of Catalyst.
 123
 124 These extensions are:
 125
 126 =over
 127
 128 =item L<Catalyst::Engine::HTTP::Prefork>
 129
 130 This is now deprecated, see L<Catalyst::Upgrading>.
 131
 132 =item L<Test::WWW::Mechanize::Catalyst>
 133
 134 Has been updated to not produce deprecation warnings, upgrade recommended.
 135
 136 =item Catalyst::ActionRole::ACL
 137
 138 Has been updated to fix failing tests (although older versions still
 139 function perfectly with this version of Catalyst).
 140
 141 =item Catalyst::Plugin::Session::Store::DBIC
 142
 143 Has been updated to fix failing tests (although older versions still
 144 function perfectly with this version of Catalyst).
 145
 146 =item Catalyst::Plugin::Authentication
 147
 148 Has been updated to fix failing tests (although older versions still
 149 function perfectly with this version of Catalyst).
 150
 151 =back
 152
 153 =head1 PREVIOUS VERSIONS
 154
 155 =head2 VERSION 5.8XXXX 'catamoose'
 156
 157 =head3 Deprecations
 158
 159 Please see L<Catalyst::Upgrading> for a full description of how changes in the
 160 framework may affect your application.
 161
 162 Below is a brief list of features which have been deprecated in this release:
 163
 164 =over
 165
 166 =item ::[MVC]:: style naming scheme has been deprecated and will warn
 167
 168 =item NEXT is deprecated for all applications and components, use MRO::Compat
 169
 170 =item Dispatcher methods which are an implementation detail made private, public versions now warn.
 171
 172 =item MyApp->plugin method is deprecated, use L<Catalyst::Model::Adaptor> instead.
 173
 174 =item __PACKAGE__->mk_accessors() is supported for backward compatibility only, use Moose attributes instead in new code.
 175
 176 =item Use of Catalyst::Base now warns
 177
 178 =back
 179
 180 =head3 New features
 181
 182 =head3 Dispatcher
 183
 184 =over
 185
 186 =item Fix forwarding to Catalyst::Action objects.
 187
 188 =item Add the dispatch_type method
 189
 190 =back
 191
 192 =head3 Restarter
 193
 194 The development server restarter has been improved to be compatible with
 195 immutable Moose classes, and also to optionally use
 196 L<B::Hooks::OP::Check::StashChange> to handle more complex application layouts
 197 correctly.
 198
 199 =head3 $c->uri_for_action method.
 200
 201 Give a private path to the Catalyst action you want to create a URI for.
 202
 203 =head3 Logging
 204
 205 Log levels have been made additive.
 206
 207 =head3 L<Catalyst::Test>
 208
 209 =over
 210
 211 =item Change to use L<Sub::Exporter>.
 212
 213 =item Support mocking multiple virtual hosts
 214
 215 =item New methods like action_ok and action_redirect to write more compact tests
 216
 217 =back
 218
 219 =head3 Catalyst::Response
 220
 221 =over
 222
 223 =item *
 224
 225 New print method which prints @data to the output stream, separated by $,.
 226 This lets you pass the response object to functions that want to write to an
 227 L<IO::Handle>.
 228
 229 =item *
 230
 231 Added code method as an alias for C<< $res->status >>
 232
 233 =back
 234
 235 =head3 Consequences of the Moose back end
 236
 237 =over
 238
 239 =item *
 240
 241 Components are fully compatible with Moose, and all Moose features, such as
 242 method modifiers, attributes, roles, BUILD and BUILDARGS methods are fully
 243 supported and may be used in components and applications.
 244
 245 =item *
 246
 247 Many reusable extensions which would previously have been plugins or base
 248 classes are better implemented as Moose roles.
 249
 250 =item *
 251
 252 L<MooseX::MethodAttributes::Role::AttrContainer::Inheritable> is used to contain action
 253 attributes. This means that attributes are represented in the MOP, and
 254 decouples action creation from attributes.
 255
 256 =item *
 257
 258 There is a reasonable API in Catalyst::Controller for working with
 259 and registering actions, allowing a controller sub-class to replace
 260 subroutine attributes for action declarations with an alternate
 261 syntax.
 262
 263 =item *
 264
 265 Refactored capturing of $app from L<Catalyst::Controller> into
 266 L<Catalyst::Component::ApplicationAttribute> for easier reuse in other
 267 components.
 268
 269 =item *
 270
 271 Your application class is forced to become immutable at the end of compilation.
 272
 273 =back
 274
 275 =head3 Bug fixes
 276
 277 =over
 278
 279 =item *
 280
 281 Don't ignore SIGCHLD while handling requests with the development server, so that
 282 system() and other ways of creating child processes work as expected.
 283
 284 =item *
 285
 286 Fixes for FastCGI when used with IIS 6.0
 287
 288 =item *
 289
 290 Fix a bug in uri_for which could cause it to generate paths with multiple
 291 slashes in them.
 292
 293 =item *
 294
 295 Fix a bug in Catalyst::Stats, stopping garbage being inserted into
 296 the stats if a user calls begin => but no end
 297
 298 =back
 299