Catalyst::Upgrading - Instructions for upgrading to the latest Catalyst
+=head1 Upgrading to Catalyst 5.90121
+
+A new C<log_stats> method has been added. This will only affect
+subclasses that have a method with this name added.
+
+=head1 Upgrading to Catalyst 5.90100
+
+We changed the way the middleware stash works so that it no longer localizes
+the PSGI env hashref. This was done to fix bugs where people set PSGI ENV hash
+keys and found them to disappear in certain cases. It also means that now if
+a sub applications sets stash variables, that stash will now bubble up to the
+parent application. This may be a breaking change for you since previous
+versions of this code did not allow that. A workaround is to explicitly delete
+stash keys in your sub application before returning control to the parent
+application.
+
+=head1 Upgrading to Catalyst 5.90097
+
+In older versions of Catalyst one could construct a L<URI> with a fragment (such as
+https://localhost/foo/bar#fragment) by using a '#' in the path or final argument, for
+example:
+
+ $c->uri_for($action, 'foo#fragment');
+
+This behavior was never documented and would break if using the Unicode plugin, or when
+adding a query to the arguments:
+
+ $c->uri_for($action, 'foo#fragment', +{ a=>1, b=>2});
+
+would define a fragment like "#fragment?a=1&b=2".
+
+When we introduced UTF-8 encoding by default in Catalyst 5.9008x this side effect behavior
+was broken since we started encoding the '#' when it was part of the URI path.
+
+In version 5.90095 and 5.90096 we attempted to fix this, but all we managed to do was break
+people with URIs that included '#' as part of the path data, when it was not expected to
+be a fragment delimiter.
+
+In general L<Catalyst> prefers an explicit specification rather than relying on side effects
+or domain specific mini languages. As a result we are now defining how to set a fragment
+for a URI via ->uri_for:
+
+ $c->uri_for($action_or_path, \@captures_or_args, @args, \$query, \$fragment);
+
+If you are relying on the previous side effect behavior your URLs will now encode the '#'
+delimiter, which is going to be a breaking change for you. You need to alter your code
+to match the new specification or modify uri_for for your local case. Patches to solve
+this are very welcomed, as long as they don't break existing test cases.
+
+B<NOTE> If you are using the string form of the first argument:
+
+ $c->uri_for('/foo/bar#baz')
+
+construction, we do not attempt to encode this and it will make a URL with a
+fragment of 'baz'.
+
+
+=head1 Upgrading to Catalyst 5.90095
+
+The method C<last_error> in L</Catalyst> was actually returning the first error. This has
+been fixed but there is a small chance it could be a breaking issue for you. If this gives
+you trouble changing to C<shift_errors> is the easiest workaround (although that does
+modify the error stack so if you are relying on that not being changed you should try something
+like @{$c->errors}[-1] instead. Since this method is relatively new and the cases when the
+error stack actually has more than one error in it, we feel the exposure is very low, but bug
+reports are very welcomed.
+
=head1 Upgrading to Catalyst 5.90090
L<Catalyst::Utils> has a new method 'inject_component' which works the same as the method of
the same name in L<CatalystX::InjectComponent>. You should start converting any
use of the non core method in your code as future changes to Catalyst will be
-sychronized to the core method first. We reserve the right to cease support
+synchronized to the core method first. We reserve the right to cease support
of the non core version should we reach a point in time where it cannot be
properly supported as an external module. Luckily this should be a trivial
-search and replace. Change all occurances of:
+search and replace. Change all occurrences of:
CatalystX::InjectComponent->inject(...)
},
);
-Although the cored behavior requires more code, its better separates concerns
-as well as plays more into core Catalyst expections of how configuration shoul
+Although the core behavior requires more code, it better separates concerns
+as well as plays more into core Catalyst expectations of how configuration should
look.
Also we added a new develop console mode only warning when you call a component
with arguments that don't expect or do anything meaningful with those args. Its
-possible if you are logging debug mode in production (please don't...) this
+possible if you are logging debug mode in production (please don't...) this
could add verbosity to those logs if you also happen to be calling for components
and passing pointless arguments. We added this warning to help people not make this
error and to better understand the component resolution flow.
=head2 More backwards compatibility options with UTF-8 changes
-In order to give better backwards compatiblity with the 5.90080+ UTF-8 changes
+In order to give better backwards compatibility with the 5.90080+ UTF-8 changes
we've added several configuration options around control of how we try to decode
your URL keywords / query parameters.
C<do_not_decode_query>
If true, then do not try to character decode any wide characters in your
-request URL query or keywords. Most readings of the relevent specifications
+request URL query or keywords. Most readings of the relevant specifications
suggest these should be UTF-* encoded, which is the default that L<Catalyst>
-will use, hwoever if you are creating a lot of URLs manually or have external
+will use, however if you are creating a lot of URLs manually or have external
evil clients, this might cause you trouble. If you find the changes introduced
-in Catalyst version 5.90080+ break some of your query code, you may disable
+in Catalyst version 5.90080+ break some of your query code, you may disable
the UTF-8 decoding globally using this configuration.
This setting takes precedence over C<default_query_encoding> and
C<default_query_encoding>
By default we decode query and keywords in your request URL using UTF-8, which
-is our reading of the relevent specifications. This setting allows one to
+is our reading of the relevant specifications. This setting allows one to
specify a fixed value for how to decode your query. You might need this if
you are doing a lot of custom encoding of your URLs and not using UTF-8.
projects / catagits/Catalyst-Runtime.git / blobdiff