NAME

       Twitter::API::Trait::Migration - Migration support Net::Twitter/::Lite users

VERSION

       version 1.0006

DESCRIPTION

       Twitter::API is a rewrite of Net::Twitter. It's leaner, lighter, and has fasterXfewer
       dependencies, and less baggage. This trait helps Net::Twitter and Net::Twitter::Lite users
       migrate to Twitter::API by providing Net::Twitter compatible behavior where possible and
       warning politely where code should be changed.

Migrating from Net::Twitter

       Twitter::API requires a minimum perl version of 5.14.1. Make sure you have that.

       Just change your constructor call:

               my $client = Net::Twitter->new(
                       traits => [ qw/API::RESTv1_1 OAuth RetryOnError/ ],
                       consumer_key        => $key,
                       consumer_secret     => $secret,
                       access_token        => $token,
                       access_token_secret => $token_secret,
               );

       Becomes:

               my $client = Twitter::API->new_with_traits(
                       traits => [ qw/Migration ApiMethods RetryOnError/ ],
                       consumer_key        => $key,
                       consumer_secret     => $secret,
                       access_token        => $token,
                       access_token_secret => $token_secret,
               );

       Differences:

       •   replace "new" with "new_with_traits"

       •   replace trait "API::RESTv1_1" with "ApiMethods"

       •   drop trait "OAuth", Twitter::API's core includes it

       •   add the Migration trait so Twitter::API will handle oauth key management in a
           Net::Twitter compatible way and warn

   Traits
       Twitter::API supports the following traits:

       •   ApiMethods

       •   AppAuth

       •   DecodeHtmlEntities

       •   NormalizeBooleans

       •   RetryOnError

       •   Enchilada

       ApiMethods is a direct replacement for Net::Twitter's API::RESTv1_1 trait.

       Net::Twitter's InflateObjects trait will be released as a separate distribution to
       minimize Twitter::API's dependencies.

       If you are using the Net::Twitter's WrapResults trait, Twitter::API provides a better way
       to access the what it provides. In list context, API calls return both the API call
       results and a Twitter::API::Context object that provides the same accessors and attributes
       WrapResult provided, including the result accessor.

       So, if you had:

           my $r = $client->home_timeline;
           $r->result;
           $r->rate_limit_remaining;

       You can change that to:

           my ( $result, $context ) = $client->home_timeline;
           $result;
           $context->rate_limit_remaining;

       Or for the smallest change to your code:

           my ( undef, $r ) = $client->home_timeline;
           $r->result; i            # same as before
           $r->rate_limit_remaning; # same as before

       However, there is migration support for WrapResult. Call the constructor with option
       "wrap_result => 1" and Twitter::API will return the context object, only, for API calls.
       This should give you the same behavior you had with WrapResult while you modify your code.
       Twitter::API will warn when this option is used. You may disale warnings with
       "$ENV{TWITTER_API_NO_MIGRATION_WARNINGS} = 1".

       If you are using any other Net::Twitter traits, please contact the author of Twitter::API.
       Additional traits may be added to Twitter::API or released as separate distributions.

       If you are using "decode_html_entities => 1" in Net::Twitter, drop that option and add
       trait DecodeHtmlEntities. Traits AppAuth and RetryOnError provide the same functionality
       in Twitter::API as their Net::Twitter counterparts. So, no changes required, there, if
       you're using them. (Although there is a change to one of AppAuth's methods. See the "OAuth
       changes" discussion.)

       NormalizeBooleans is something you'll probably want. See the NormalizeBooleans
       documentation.

       Enchilda just bundles ApiMethods, NormalizeBooleans, RetryOnError, and DecodeHtmlEntities.

   Other constructor options
       Drop option "ssl => 1". It is no longer necessary. By default, all connections use SSL.

       If you are setting useragent_lass and/or useragent_args to customize the user agent, just
       construct your own pass it to new with "user_agent => $custom_user_agent".

       If you are using ua to set a custom user agent, the attribute name has changed to
       usre_agent. So, pass it to new with "user_agent => $custom_user_agent".

       By default, Twitter::API uses HTTP::Thin as its user agent. You should be able to use any
       user agent you like, as long as it has a request method that takes an HTTP::Request and
       returns an HTTP::Response.

       If you used clientname, clientver, clienturl, or useragent, see "agent" in Twitter::API
       and "default_headers" in Twitter::API. If all you're after is a custom User-Agent header,
       just pass "agent => $user_agent_string".  It will be used for both User-Agent header and
       the X-Twitter-Client header on requests. If you want to include your own application
       version and url, pass "default_headers => \%my_request_headers".

   OAuth changes
       Net::Twitter saved request and access tokens in the client instance as part of the
       3-legged OAuth handshake. That was a poor design decision. Twitter::API returns request
       and access tokens to the caller. It is the caller's responsibility to store and cache them
       appropriately. Hovever, transitional support is provided, with client instance storage, so
       your code can run unmodified while you make the transition.

       The following methods exist only for migration from Net::Twitter and will be removed in a
       future release. A warning is issued on each call to these methods.  To disable the
       warnings, set "$ENV{TWITTER_API_NO_MIGRATION_WARNINGS} = 1".

       •   get_authentication_url

           replace with oauth_authentication_url
             or oauth_request_token and
             oauth_authentication_url

       •   get_authorization_url

           replace with oauth_authorization_url or
             oauth_request_token and
             oauth_authorization_url

       •   get_access_token

           replace with oauth_access_token

       If you are using the AppAuth trait, replace request_access_token calls with oauth2_token
       calls. Method oauth2_token does not set the "access_token" attribute. Method
       "request_access_token" is provided for transitional support, only. It warns like the OAuth
       methods discussed above, and it sets the "access_token" attribute so existing code should
       work as expected during migration. It will be removed in a future release.

Migrating from Net::Twitter::Lite

       The discussion, above applies for Net::Twitter::Lite with a few exceptions.

       Net::Twitter::Lite does not use traits. Change your constructor call from:

           my $client = Net::Twitter::Lite::WithAPIv1_1->new(%args);

       To:

           my $client = Twitter::API->new_with_traits(
               traits => [ qw/Migration ApiMethods/ ],
               %args,
           );

       If you're using the option wrap_result, see the discussion above about the Net::Twitter
       WrapResult trait. There is migration support for wrap_result.  It will be removed in a
       future release.

AUTHOR

       Marc Mims <marc@questright.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2015-2021 by Marc Mims.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.