README

This Contao bundle provides an easy integration of sentry.io for Contao 4.13 and 5.x.

--

This is a "wrapper extension" for the sentry/sentry-symfony bundle.

Setup in the Contao Managed Edition

The basic integration is automatically configured to some sane defaults. To enable the integration, configure the SENTRY_DSN variable in your .env.local file.

Additionally, you can name the SENTRY_ENV in your .env.local file, which can be useful if you e.g. have a test and prod installation.

If you need to change any of the defaults, simply configure the sentry/sentry-symfony bundle according to the Documentation.

Manual configuration

If you do not use the Contao Managed Edition, you need to configure this bundle as you would configure the sentry/sentry-symfony bundle: Documentation

Special case before_send callback

In the sentry/sentry-symfony bundle, there can only be one service responsible for filtering events before sending them to sentry. You'd configure it like so:

sentry:
    options:
        before_send: 'my_service_id'

However, this conflicts with the idea of this bundle to be extensible. Hence, this bundle ships with a default callback that dispatches the BeforeSendEvent. Thus giving other extensions (or your app), the option to filter the events before sending, without replacing each other.

Usage:

use Oneup\ContaoSentryBundle\Event\BeforeSendEvent;
use Sentry\Event;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
class SentryBeforeSendListener
{
    public function __invoke(BeforeSendEvent $beforeSendEvent): void
    {
        // Might have been unset already by a different listener
        $event = $beforeSendEvent->getEvent();
        if (null === $event) {
            return;
        }

        // Your custom logic
        if ($this->shouldEventBeIgnored($event)) {
            $beforeSendEvent->setEvent(null);
        }
    }
}

User feedback

On the other hand you might want to implement the User feedback feature of sentry. The user feedback is primarily useful to let the users know that you've gotten notified about the issue and to let users give the opportunity to add some comments.

In order to integrate this feature, you have to alter the error page template. Place a copy of vendor/contao/core-bundle/src/Resources/views/Error/layout.html.twig in the directory templates/ContaoCoreBundle/views/Error/.

Modify the copied template and place the following snippet just before the closing </body> tag:

{% set sentry_id = ''|sentry_last_event_id %}
{% if sentry_id %}
    <script src="https://browser.sentry-cdn.com/8.7.0/bundle.feedback.min.js"
            integrity="sha384-If5t0OtWMly236c4qvXxYalt8pOLHOj9qKZaXu/xDqMqJ5xmdMCwVwXP6dlPyALI"
            crossorigin="anonymous"></script>
    <script>
        Sentry.init({dsn: '{{ ''|sentry_dsn }}'});
        Sentry.showReportDialog({eventId: '{{ sentry_id }}'})

        // You can also bind the "show" method to an event, e.g. to open the modal on button click
        {#document.querySelector('.btn-report').addEventListener('click', function (e) {#}
        {#    e.preventDefault();#}
        {#    Sentry.showReportDialog({eventId: '{{ sentry_id }}'})#}
        {#});#}
    </script>
{% endif %}

Error tracking helper

The Oneup\ContaoSentryBundle\ErrorHandlingTrait adds useful Sentry helpers.

• ErrorHandlingTrait::sentryOrThrow will either log an error/exception to sentry, or it will throw an exception if Sentry integration is not available (e.g. on localhost or in dev environment). It is mostly useful when running looping cronjobs, like synchronizing Contao with a remote system, so an error on syncing a record will not prevent the sync loop from finishing other records.

• ErrorHandlingTraig::sentryCheckIn has been added for the new Sentry Cron job monitoring. Call sentryCheckIn() without argument to start a check in, and subsequently with a boolean true or false after the job has successfully run or failed.