view release on metacpan or  search on metacpan

lib/Catalyst/Upgrading.pod  view on Meta::CPAN

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
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 occurrences of:

    CatalystX::InjectComponent->inject(...)

Into

    Catalyst::Utils::inject_component(...)

and we expect everything to work the same (we'd consider it not working the same
to be a bug, and please report it.)

We also cored features from L<CatalystX::RoleApplicator> to compose a role into the
request, response and stats classes.  The main difference is that with L<CatalystX::RoleApplicator>
you did:

    package MyApp;

    use Catalyst;
    use CatalystX::RoleApplicator;

    __PACKAGE__->apply_request_class_roles(
      qw/My::Request::Role Other::Request::Role/);

Whereas now we have three class attributes, 'request_class_traits', 'response_class_traits'
and 'stats_class_traits', so you use like this (note this value is an ArrayRef)


    package MyApp;

    use Catalyst;

    __PACKAGE__->request_class_traits([qw/
      My::Request::Role
      Other::Request::Role/]);

(And the same for response_class_traits and stats_class_traits.  We left off the
traits for Engine, since that class does a lot less nowadays, and dispatcher.  If you
used those and can share a use case, we'd be likely to support them.

Lastly, we have some of the feature from L<CatalystX::ComponentsFromConfig> in
core.  This should mostly work the same way in core, except for now the
core version does not create an automatic base wrapper class for your configured
components (it requires these to be catalyst components and injects them directly.
So if you make heavy use of custom base classes in L<CatalystX::ComponentsFromConfig>
you might need a bit of work to use the core version (although there is no reason
to stop using L<CatalystX::ComponentsFromConfig> since it should continue to work
fine and we'd consider issues with it to be bugs).  Here's one way to map from
L<CatalystX::ComponentsFromConfig> to core:

In L<CatalystX::ComponentsFromConfig>:

    MyApp->config(
      'Model::MyClass' => {
          class => 'MyClass',
          args => { %args },

      });