Sentry (Error Tracking)

The artiframe add sentry extension seamlessly integrates the sentry/sentry package into ArtiFrame. It automatically catches errors, exceptions, and even fatal PHP errors that occur on your live servers, sending them to Sentry with detailed stack traces.

1. Installation and Configuration

To install the extension, execute the following command in your terminal:

terminal
$ artiframe add sentry

Following this, the DSN configuration will be appended to your .env file. You should place your DSN URL obtained from the Sentry panel here.

.env
SENTRY_DSN=https://[email protected]/0
Automatic Booting: The Sentry extension integrates directly into ArtiFrame's core Exception Handler. You do not need to manually initialize it with Sentry\init() anywhere; it activates globally the moment the system boots.
2. Catching Errors
Uncaught Exceptions (Automatic)

Any uncaught error occurring in your code is automatically detected and sent to Sentry. You don't need to write any extra code.

UserController.php
<?php
public function show($id) {
    // Let's assume there is no table named 'users_old'
    // This SQL error is automatically caught by ArtiFrame's global error handler
    // and reported to Sentry with the Stack Trace.
    $user = DB::query("SELECT * FROM users_old WHERE id = ?", [$id]);
}
Manual Error Reporting (Manual Capture)

If you catch errors with try-catch but still want to report them to Sentry, you can use the \Sentry\captureException() method directly.

PaymentController.php
<?php
try {
    $apiResponse = ExternalPaymentApi::charge($amount);
} catch (\Exception $e) {
    // Send it to Sentry
    \Sentry\captureException($e);

    // Continue the normal flow, show a user-friendly message to the customer
    echo "Payment system is temporarily unavailable.";
}
3. Advanced Features
User Tracking (User Context)

To identify which user experienced an error in Sentry, you can set the User Context.

example.php
<?php
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setUser([
        'id' => 123,
        'email' => '[email protected]',
        'username' => 'janedoe'
    ]);
});
Adding Custom Tags and Breadcrumbs

You can add tags to categorize errors and breadcrumbs to see what the user did prior to the error.

example.php
<?php
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    // Categorization
    $scope->setTag('page.locale', 'tr');
    $scope->setTag('payment.gateway', 'iyzico');

    // Extra Data
    $scope->setExtra('cart_items', ['item_1', 'item_2']);
});

// Breadcrumb (Traces to understand how the error occurred)
\Sentry\addBreadcrumb(
    new \Sentry\Breadcrumb(
        \Sentry\Breadcrumb::LEVEL_INFO,
        \Sentry\Breadcrumb::TYPE_USER,
        'ui.click',
        'User clicked checkout button'
    )
);