Merge pull request #184 from getsentry/3.0

First steps toward 3.0 and 2.0 SDK

Author: Jean85

.travis.yml

@@ -5,6 +5,7 @@ dist: trusty
 php:
   - 7.1
   - 7.2
+  - 7.3
 
 cache:
   directories:
@@ -16,7 +17,7 @@ before_install:
   - composer global require hirak/prestissimo
 
 install: 
-  - travis_retry travis_wait composer update --no-interaction --prefer-dist --prefer-stable $COMPOSER_OPTIONS
+  - travis_retry travis_wait composer update --no-interaction --prefer-dist --prefer-stable
 
 script:
   - vendor/bin/phpunit -v
@@ -25,7 +26,11 @@ jobs:
   include:
     - stage: Test
       php: 7.1
-      env: COMPOSER_OPTIONS="--prefer-lowest"
+      env:
+        - DEPS=--prefer-lowest
+      install:
+        - travis_retry travis_wait composer install --no-interaction --prefer-dist
+        - travis_retry travis_wait composer update --no-interaction --prefer-dist --prefer-stable --prefer-lowest
     - stage: Code style and static analysis
       script:
         - composer phpstan

README.md

@@ -9,6 +9,15 @@ Symfony integration for [Sentry](https://getsentry.com/).
 [![Scrutinizer][Master scrutinizer image]][Master scrutinizer link]
 [![Coverage Status][Master coverage image]][Master scrutinizer link]
 
+## Notice 3.0
+> The current master branch contains the 3.0 version of this bundle, which is currently under development. This version
+> will support the newest 2.0 version of the underlying Sentry SDK version.
+>
+> A beta version will be tagged as soon as possible, in the meantime you can continue to use the previous versions.
+> 
+> To know more about the progress of this version see [the relative 
+milestone](https://github.com/getsentry/sentry-symfony/milestone/3)
+
 ## Benefits
 
 Use sentry-symfony for:
@@ -26,17 +35,22 @@ Use sentry-symfony for:
 ## Installation
 
 ### Step 1: Download the Bundle
+You can install this bundle using Composer. Since the Sentry SDK uses HTTPlug to remain transport-agnostic, you need to 
+manually require two additional packages that provides [`php-http/async-client-implementation`](https://packagist.org/providers/php-http/async-client-implementation)
+and [`http-message-implementation`](https://packagist.org/providers/psr/http-message-implementation).
+
+For example, if you want to install/upgrade using Curl as transport and the PSR-7 implementation by Guzzle, you can use:
 
-Open a command console, enter your project directory and execute the
-following command to download the latest stable version of this bundle:
+```bash
+composer require sentry/sentry-symfony:^3.0 php-http/curl-client guzzlehttp/psr7
+```
 
+Or, if you want to use only Guzzle 6, you can use:
 ```bash
-$ composer require sentry/sentry-symfony
+composer require sentry/sentry-symfony:^3.0 php-http/guzzle6-adapter guzzlehttp/psr7
 ```
 
-This command requires you to have Composer installed globally, as explained
-in the [installation chapter](https://getcomposer.org/doc/00-intro.md)
-of the Composer documentation.
+> TODO: Flex recipe
 
 ### Step 2: Enable the Bundle
 
@@ -52,20 +66,18 @@ class AppKernel extends Kernel
 {
     public function registerBundles()
     {
-        $bundles = array(
+        $bundles = [
             // ...
-        );
+            new Sentry\SentryBundle\SentryBundle(),
+        ];
 
-        if (in_array($this->getEnvironment(), ['staging', 'prod'], true)) {
-            $bundles[] = new Sentry\SentryBundle\SentryBundle();
-        }
         // ...
     }
 
     // ...
 }
 ```
-Note that, with this snippet of code, the bundle will be enabled only for the `staging` and `prod` environment; adjust it to your needs. It's discouraged to enable this bundle in the `test` environment, because the Sentry client will change the error handler, which is already used by other packages like Symfony's deprecation handler (see [#46](https://github.com/getsentry/sentry-symfony/issues/46) and [#95](https://github.com/getsentry/sentry-symfony/issues/95)).
+Note that, unlike before version 3, the bundle will be enabled in all environments.
 
 ### Step 3: Configure the SDK
 
@@ -78,250 +90,24 @@ sentry:
 ```
 
 ## Maintained versions
- * 2.x is actively maintained on the master branch, but it requires Symfony 3+ and PHP 7.1+;
- * 1.x is still supported to allow Symfony 2 and PHP 5.6/7.0; it may receive backports of features from the master branch, but it's not guaranteed 
- * 0.8.x is no longer maintained, with the 0.8.8 release containing the latest new features; it may only receive security fixes in the future.
+ * 3.x is actively maintained and developed on the master branch, and uses Sentry SDK 2.0;
+ * 2.x is supported only for fixes; from this version onwards it requires Symfony 3+ and PHP 7.1+;
+ * 1.x is no longer maintained; you can use it for Symfony < 2.8 and PHP 5.6/7.0; 
+ * 0.8.x is no longer maintained.
 
 ## Configuration
 
-The following options can be configured via ``app/config/config.yml``.
-
-### Skip some exceptions
-
-```yaml
-sentry:
-    skip_capture:
-        - 'Symfony\Component\HttpKernel\Exception\HttpExceptionInterface'
-```
-
-### Listeners' priority
-
-You can change the priority of the 3 default listeners of this bundle with the `listener_priorities` key of your config.
-The default value is `0`, and here are the 3 possible sub-keys:
-
-```yaml
-listener_priorities:
-    request: 0
-    kernel_exception: 0
-    console_exception: 0
-```
-
-... respectively for the `onKernelRequest`, `onKernelException` and `onConsoleException` events.
-
-### Options
-
-In the following section you will find some of the available options you can configure, listed alphabetically. All available options and a more detailed description of each can be found [here](https://docs.sentry.io/clients/php/config/), in the Sentry documentation.
-
-#### app_path
-
-The base path to your application. Used to trim prefixes and mark frames of the stack trace as part of your application.
-
-```yaml
-sentry:
-    options:
-        app_path: "/path/to/myapp"
-```
-
-#### environment
-
-The environment your code is running in (e.g. production).
-
-```yaml
-sentry:
-    options:
-        environment: "%kernel.environment%"
-```
-
-#### error types
-
-Define which error types should be reported.
-
-```yaml
-sentry:
-    options:
-        error_types: E_ALL & ~E_DEPRECATED & ~E_NOTICE
-```
-
-#### exception_listener
-
-This is used to replace the default exception listener that this bundle uses. The value must be a FQCN of a class implementing the SentryExceptionListenerInterface interface. See [Create a Custom ExceptionListener](#create-a-custom-exceptionlistener) for more details.
-
-```yaml
-sentry:
-    exception_listener: AppBundle\EventListener\MySentryExceptionListener
-```
-
-#### prefixes
-
-A list of prefixes to strip from filenames. Often these would be vendor/include paths.
-
-```yaml
-sentry:
-    options:
-        prefixes:
-            - /usr/lib/include
-```
-
-#### release
-
-The version of your application. Often this is the Git SHA hash of the commit.
-
-```yaml
-sentry:
-    options:
-        release: "beeee2a06521a60e646bbb8fe38702e61e4929bf"
-```
-
-#### tags
-
-Define tags for the logged errors.
-
-```yaml
-sentry:
-    options:
-        tags:
-            tag1: tagvalue
-            tag2: tagvalue
-```
-
-### Deprecated configuration options
-
-In previous releases of this bundle, up to 0.8.2, some of the previous options where set outside of the options level of the configuration file. Those still work but are deprecated, and they will be dropped in the stable 1.x release, so **you are advised to abandon them**; to provide forward compatibility, they can still be used alongside the standard syntax, but values must match. This is a list of those options:
-
-```yaml
-sentry:
-    app_path: ~
-    environment: ~
-    error_types: ~
-    excluded_app_paths: ~
-    prefixes: ~
-    release: ~
-```
+TODO
 
 ## Customization
 
-It is possible to customize the configuration of the user context, as well as modify the client immediately before an exception is captured by wiring up an event subscriber to the events that are emitted by the default configured `ExceptionListener` (alternatively, you can also just define your own custom exception listener).
-
-### Create a custom ExceptionListener
-
-You can always replace the default `ExceptionListener` with your own custom listener. To do this, assign a different class to the `exception_listener` property in your Sentry configuration, e.g.:
-
-```yaml
-sentry:
-    exception_listener: AppBundle\EventListener\MySentryExceptionListener
-```
-
-... and then define the custom `ExceptionListener` that implements the `SentryExceptionListenerInterface`, e.g.:
-
-```php
-// src/AppBundle/EventSubscriber/MySentryEventListener.php
-namespace AppBundle\EventSubscriber;
-
-use Sentry\SentryBundle\EventListener\SentryExceptionListenerInterface;
-use Symfony\Component\Console\Event\ConsoleExceptionEvent;
-use Symfony\Component\EventDispatcher\EventDispatcherInterface;
-use Symfony\Component\HttpKernel\Event\GetResponseEvent;
-use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
-use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
-use Symfony\Component\Security\Core\Authorization\AuthorizationCheckerInterface;
-
-class MySentryExceptionListener implements SentryExceptionListenerInterface
-{
-    // ...
-
-    public function __construct(TokenStorageInterface $tokenStorage = null, AuthorizationCheckerInterface $authorizationChecker = null, \Raven_Client $client = null, array $skipCapture, EventDispatcherInterface $dispatcher = null)
-    {
-        // ...
-    }
-
-    public function onKernelRequest(GetResponseEvent $event)
-    {
-        // ...
-    }
-
-    public function onKernelException(GetResponseForExceptionEvent $event)
-    {
-        // ...
-    }
-
-    public function onConsoleException(ConsoleExceptionEvent $event)
-    {
-        // ...
-    }
-}
-```
-
-As a side note, while the above demonstrates a custom exception listener that
-does not extend anything you could choose to extend the default
-`ExceptionListener` and only override the functionality that you want to.
-
-### Add an EventSubscriber for Sentry Events
-
-Create a new class, e.g. `MySentryEventSubscriber`:
-
-```php
-// src/AppBundle/EventSubscriber/MySentryEventListener.php
-namespace AppBundle\EventSubscriber;
-
-use Sentry\SentryBundle\Event\SentryUserContextEvent;
-use Sentry\SentryBundle\SentrySymfonyEvents;
-use Symfony\Component\EventDispatcher\EventSubscriberInterface;
-
-class MySentryEventSubscriber implements EventSubscriberInterface
-{
-    /** @var \Raven_Client */
-    protected $client;
-
-    public function __construct(\Raven_Client $client)
-    {
-        $this->client = $client;
-    }
-
-    public static function getSubscribedEvents()
-    {
-        // return the subscribed events, their methods and priorities
-        return array(
-            SentrySymfonyEvents::PRE_CAPTURE => 'onPreCapture',
-            SentrySymfonyEvents::SET_USER_CONTEXT => 'onSetUserContext'
-        );
-    }
+The Sentry 2.0 SDK uses the Unified API, hence it uses the concept of `Scope`s to hold information about the current 
+state of the app, and attach it to any event that is reported. This bundle has two listeners (`RequestListener` and 
+`ConsoleListener`) that adds some easy default information. Those listeners normally are executed with a priority of `1`
+to allow easier customization with custom listener, that by default run with a lower priority of `0`.
 
-    public function onSetUserContext(SentryUserContextEvent $event)
-    {
-        // ...
-    }
-
-    public function onPreCapture(Event $event)
-    {
-        if ($event instanceof GetResponseForExceptionEvent) {
-            // ...
-        }
-        elseif ($event instanceof ConsoleExceptionEvent) {
-            // ...
-        }
-    }
-}
-```
-
-In the example above, if you subscribe to the `PRE_CAPTURE` event you may
-get an event object that caters more toward a response to a web request (e.g.
-`GetResponseForExceptionEvent`) or one for actions taken at the command line
-(e.g. `ConsoleExceptionEvent`). Depending on what and how the code was
-invoked, and whether or not you need to distinguish between these events
-during pre-capture, it might be best to test for the type of the event (as is
-demonstrated above) before you do any relevant processing of the object.
-
-To configure the above add the following configuration to your services
-definitions:
-
-```yaml
-app.my_sentry_event_subscriber:
-    class: AppBundle\EventSubscriber\MySentryEventSubscriber
-    arguments:
-      - '@sentry.client'
-    tags:
-      - { name: kernel.event_subscriber }
-```
+Those listeners are `final` so not extendable, but you can look at those to know how to add more information to the 
+current `Scope` and enrich you Sentry events.
 
 [Last stable image]: https://poser.pugx.org/sentry/sentry-symfony/version.svg
 [Last unstable image]: https://poser.pugx.org/sentry/sentry-symfony/v/unstable.svg