Skip to content

Latest commit

 

History

History
63 lines (52 loc) · 5.23 KB

UPGRADE-3.0.md

File metadata and controls

63 lines (52 loc) · 5.23 KB
Raw

Upgrade to 3.0

The 3.0 major release of this bundle has some major changes. This document will try to list them all, to help users during the upgrade path.

Sentry SDK 2.0

The major change is in the fact that we now require the sentry/sdk metapackage; this, in turn, requires the original sentry/sentry package, but at major version 2. This new version has been completely rewritten: if you use this bundle and you interact directly with the underlying SDK and client, you should read through the relative upgrade document.

Changes in the configuration

There are only two BC impacting the configuration:

  • the skip_capture option has been removed: the same feature has been implemented in the new SDK, with the PHP excluded_exceptions option; you just have to move your values from sentry.skip_capture to sentry.options.excluded_exceptions
  • Symfony internal exceptions are no longer ignored by default: Sentry will start getting events for 404 or 403, or even 403 which are followed by a (remembered) login. Add new values to the sentry.options.excluded_exceptions option; notice that it works with an instanceof against the exception, so you could ignore multiple kind of events using a common ancestor class.
  • The sentry.options values reflect the options of the PHP SDK; many of those have been removed, and there are some new ones. You can read the appropriate section of the upgrade document, with the exception of the server to dsn migration, which is still handled in the same way by the bundle, under sentry.dsn
  • A new notable option is send_default_pii: it's a new option of the new SDK with by default is turned off, for GDPR compliance. You need to set sentry.options.send_default_pii: true to have the user's username and IP address attached to the events, as in the 2.0 bundle.

HTTPlug

Since SDK 2.0 uses HTTPlug to remain transport-agnostic, you need to have installed two packages that provides php-http/async-client-implementation and http-message-implementation.

The metapackage already solves this need, requiring the Curl client and Guzzle's message factories.

If instead you want to use a different HTTP client or message factory, you'll need to require manually those additional packages:

composer require sentry/sentry:^2.0 php-http/guzzle6-adapter guzzlehttp/psr7

The sentry/sentry package is required directly to override sentry/sdk, and the other two packages are up to your choice; in the current example, we're using both Guzzle's components (client and message factory).

Changes in the services

Due to the SDK changes, and to follow newer Symfony best practices, the services exposed by the bundle are completely changed:

  • All services are now private; declare public aliases to access them if needed; you can still use the Sentry SDK global functions if you want just to capture messages manually without injecting Sentry services in your code
  • All services uses the full qualified name of their interfaces to name them
  • The ExceptionListener has been split and renamed: we now have a simpler ErrorListener, and three other listeners dedicated to enriching events of data (RequestListener, SubRequestListener and ConsoleListener)
  • The listeners are now final; append your own listeners to override their behavior
  • The SentrySymfonyEvents::PRE_CAPTURE and SentrySymfonyEvents::SET_USER_CONTEXT events are dropped; if you want to inject data into your events, write your own listener in a similar fashion to RequestListener, using the Hub and the Scope to handle how and when the new information is attached to events
  • The listeners are registered with a priority of 1; they will run just before the default priority of 0, to ease the registration of custom listener that will change Scope data
  • Configuration options of the bundle are now aligned with the new ones of the 2.0 SDK

New services

This is a brief description of the services registered by this bundle:

  • Sentry\State\HubInterface: this is the central root of the SDK; it's the Hub that the bundle will instantiate at startup, and the current one too if you do not change it
  • Sentry\ClientInterface: this is the proper client; compared to the 1.x SDK version it's a lot more slimmed down, since a lot of the stuff has been split in separated components, so you probably will not interact with it as much as in the past. You also have to remind you that the client is bound to the Hub, and has to be changed there if you want to use a different one automatically in error reporting
  • Sentry\ClientBuilderInterface: this is the factory that builds the client; you can call its methods to change all the settings and dependencies that will be injected in the latter created client. You can use this service to obtain more customized clients for your needs
  • Sentry\Options: this class holds all the configuration used in the client and other SDK components; it's populated starting from the bundle configuration