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.9XXXX 'cataplack'
  47
  48 The Catalyst::Engine sub-classes have all been removed and deprecated,
  49 to be replaced with Plack handlers.
  50
  51 Plack is an implementation of the L<PSGI> specification, which is
  52 a standard interface between web servers and application frameworks.
  53
  54 This should be no different for developers, and you should not have to
  55 migrate your applications unless you are using a custom engine already.
  56
  57 This change benefits Catalyst significantly by reducing the amount of
  58 code inside the framework, and means that the framework gets upstream
  59 bug fixes in L<Plack>, and automatically gains support for any web server
  60 which a L<PSGI> compliant handler is written for.
  61
  62 It also allows you more flexibility with your application, and allows
  63 the use of cross web framework 'middleware'.
  64
  65 Developers are recommended to read L<Catalyst::Upgrading> for notes about
  66 upgrading, especially if you are using an unusual deployment method.
  67
  68 Documentation for how to take advantage of L<PSGI> can be found in
  69 L<Catalyst::PSGI>, and information about deploying your application
  70 has been moved to L<Catalyst::Manual::Deployment>.
  71
  72 =head3 Updated modules:
  73
  74 A number of modules have been updated to pass their tests or not
  75 produce deprecation warnings with the latest version of Catalyst.
  76 It is recommended that you upgrade any of these that you are using
  77 after installing this version of Catalyst.
  78
  79 These extensions are:
  80
  81 =over
  82
  83 =item L<Catalyst::Engine::HTTP::Prefork>
  84
  85 This is now deprecated, see L<Catalyst::Upgrading>.
  86
  87 =item L<Test::WWW::Mechanize::Catalyst>
  88
  89 Has been updated to not produce deprecation warnings, upgrade recommended.
  90
  91 =item Catalyst::ActionRole::ACL
  92
  93 Has been updated to fix failing tests (although older versions still
  94 function perfectly with this version of Catalyst).
  95
  96 =item Catalyst::Plugin::Session::Store::DBIC
  97
  98 Has been updated to fix failing tests (although older versions still
  99 function perfectly with this version of Catalyst).
 100
 101 =item Catalyst::Plugin::Authentication
 102
 103 Has been updated to fix failing tests (although older versions still
 104 function perfectly with this version of Catalyst).
 105
 106 =back
 107
 108 =head1 PREVIOUS VERSIONS
 109
 110 =head2 VERSION 5.8XXXX 'catamoose'
 111
 112 =head3 Deprecations
 113
 114 Please see L<Catalyst::Upgrading> for a full description of how changes in the
 115 framework may affect your application.
 116
 117 Below is a brief list of features which have been deprecated in this release:
 118
 119 =over
 120
 121 =item ::[MVC]:: style naming scheme has been deprecated and will warn
 122
 123 =item NEXT is deprecated for all applications and components, use MRO::Compat
 124
 125 =item Dispatcher methods which are an implementation detail made private, public versions now warn.
 126
 127 =item MyApp->plugin method is deprecated, use L<Catalyst::Model::Adaptor> instead.
 128
 129 =item __PACKAGE__->mk_accessors() is supported for backward compatibility only, use Moose attributes instead in new code.
 130
 131 =item Use of Catalyst::Base now warns
 132
 133 =back
 134
 135 =head3 New features
 136
 137 =head3 Dispatcher
 138
 139 =over
 140
 141 =item Fix forwarding to Catalyst::Action objects.
 142
 143 =item Add the dispatch_type method
 144
 145 =back
 146
 147 =head3 Restarter
 148
 149 The development server restarter has been improved to be compatible with
 150 immutable Moose classes, and also to optionally use
 151 L<B::Hooks::OP::Check::StashChange> to handle more complex application layouts
 152 correctly.
 153
 154 =head3 $c->uri_for_action method.
 155
 156 Give a private path to the Catalyst action you want to create a URI for.
 157
 158 =head3 Logging
 159
 160 Log levels have been made additive.
 161
 162 =head3 L<Catalyst::Test>
 163
 164 =over
 165
 166 =item Change to use L<Sub::Exporter>.
 167
 168 =item Support mocking multiple virtual hosts
 169
 170 =item New methods like action_ok and action_redirect to write more compact tests
 171
 172 =back
 173
 174 =head3 Catalyst::Response
 175
 176 =over
 177
 178 =item *
 179
 180 New print method which prints @data to the output stream, separated by $,.
 181 This lets you pass the response object to functions that want to write to an
 182 L<IO::Handle>.
 183
 184 =item *
 185
 186 Added code method as an alias for C<< $res->status >>
 187
 188 =back
 189
 190 =head3 Consequences of the Moose back end
 191
 192 =over
 193
 194 =item *
 195
 196 Components are fully compatible with Moose, and all Moose features, such as
 197 method modifiers, attributes, roles, BUILD and BUILDARGS methods are fully
 198 supported and may be used in components and applications.
 199
 200 =item *
 201
 202 Many reusable extensions which would previously have been plugins or base
 203 classes are better implemented as Moose roles.
 204
 205 =item *
 206
 207 L<MooseX::MethodAttributes::Role::AttrContainer::Inheritable> is used to contain action
 208 attributes. This means that attributes are represented in the MOP, and
 209 decouples action creation from attributes.
 210
 211 =item *
 212
 213 There is a reasonable API in Catalyst::Controller for working with
 214 and registering actions, allowing a controller sub-class to replace
 215 subroutine attributes for action declarations with an alternate
 216 syntax.
 217
 218 =item *
 219
 220 Refactored capturing of $app from L<Catalyst::Controller> into
 221 L<Catalyst::Component::ApplicationAttribute> for easier reuse in other
 222 components.
 223
 224 =item *
 225
 226 Your application class is forced to become immutable at the end of compilation.
 227
 228 =back
 229
 230 =head3 Bug fixes
 231
 232 =over
 233
 234 =item *
 235
 236 Don't ignore SIGCHLD while handling requests with the development server, so that
 237 system() and other ways of creating child processes work as expected.
 238
 239 =item *
 240
 241 Fixes for FastCGI when used with IIS 6.0
 242
 243 =item *
 244
 245 Fix a bug in uri_for which could cause it to generate paths with multiple
 246 slashes in them.
 247
 248 =item *
 249
 250 Fix a bug in Catalyst::Stats, stopping garbage being inserted into
 251 the stats if a user calls begin => but no end
 252
 253 =back
 254