DEV Community: Jeishanul Haque Shishir

🧠 Advanced Error Handling & Monitoring in Laravel APIs: Patterns, Pitfalls, and the Under-Documented Truths

Jeishanul Haque Shishir — Sun, 26 Oct 2025 15:05:22 +0000

⚡ Laravel API Error Handling — Beyond the Defaults

TL;DR: Laravel’s default error handling works fine — until your API hits real-world complexity.
In this guide, we’ll go beyond the docs — into advanced exception handling, structured JSON responses, contextual logging, and proactive monitoring.

🚨 Why Error Handling in Laravel APIs Deserves a Second Look

Laravel’s built-in error handling is great for local dev — but once your API scales or hits production, the defaults start to fail you.

Most developers:

🔄 Rely solely on Handler.php for everything
📜 Log errors without real monitoring
❌ Forget to standardize JSON error responses
⚠️ Leak stack traces or inconsistent messages

Result: confused clients, hidden failures, and an avalanche of meaningless “something went wrong” logs.
Let’s fix that.

⚙️ 1. Understand What You’re Actually Handling

Before you touch Handler.php, build a clear mental model of the three error types your Laravel API will face:

🟢 Operational errors — predictable issues like a missing user, invalid token, or failed validation.
These are client-side fixable problems. Return a structured JSON response to guide correction.

🟠 Programmer errors — bugs in your code (null properties, undefined methods, logic errors).
They should never reach production. Log them and fix the root cause.

🔴 Infrastructure errors — external failures like DB timeouts, Redis crashes, or API outages.
The client can’t fix them, so don’t blame them. Use retries, circuit breakers, or alerts instead.

Mental shortcut: decide whether to return, log, or alert — never lump all exceptions together.

🧩 2. Structure Your JSON Error Responses (Stop Returning Random Stuff)

Here’s a battle-tested JSON structure that keeps clients happy and your logs clean:

{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "The specified user does not exist.",
    "status": 404,
    "details": {
      "request_id": "req_78x1",
      "timestamp": "2025-10-26T12:34:56Z"
    }
  }
}

💡 Why it works

✅ Predictable for clients
⚙️ Machine-readable for apps
🧱 Extensible — add trace_id, docs_link, etc.

🧰 Laravel Implementation

public function register()
{
    $this->renderable(function (Throwable $e, $request) {
        if ($request->is('api/*')) {
            return response()->json([
                'success' => false,
                'error' => [
                    'code' => class_basename($e),
                    'message' => $e->getMessage(),
                    'status' => $this->getStatusCode($e),
                ],
            ], $this->getStatusCode($e));
        }
    });
}

private function getStatusCode(Throwable $e): int
{
    return method_exists($e, 'getStatusCode') ? $e->getStatusCode() : 500;
}

🧱 3. Leverage `withExceptions()` in Laravel 12+

Laravel 12 quietly introduced a cleaner, centralized way to handle exceptions:

$app->withExceptions(function ($exceptions) {
    $exceptions->renderable(function (ValidationException $e, Request $r) {
        return response()->json([
            'success' => false,
            'error' => [
                'code' => 'VALIDATION_ERROR',
                'message' => $e->getMessage(),
                'status' => 422,
            ]
        ], 422);
    });
});

🔥 Why it matters

No more Handler.php chaos
Keeps API error logic modular and maintainable

🔍 4. Logging ≠ Monitoring — Know the Difference

If you’re only logging, you’re already too late.
Logs tell you what happened. Monitoring tells you when and why.

🪵 Logging Best Practices

Add context: user ID, route, payload
Use multiple channels (daily, slack, sentry)
Use proper levels (error, critical, warning)

$this->reportable(function (Throwable $e) {
    logger()->error('API Exception', [
        'exception' => get_class($e),
        'user_id' => auth()->id(),
        'url' => request()->fullUrl(),
        'method' => request()->method(),
    ]);
});

📈 Monitoring Best Practices

Set alert thresholds, not just log entries:

🚨 5% error rate in 5 minutes → alert
⚙️ Queue failures > N → alert
⏱️ External API latency > 500ms → alert

Recommended stack

🧪 Local: Laravel Telescope
🧠 Exceptions: Sentry / Bugsnag / Flare
📡 Metrics & uptime: Better Stack / Datadog / New Relic

⚠️ 5. Common Pitfalls Most Developers Miss

💀 Using dd() in production — breaks JSON output.
🔓 Leaking sensitive data — always set APP_DEBUG=false.
🔁 Inconsistent error structures — breaks API contracts.
🕳️ Ignoring infra-level failures — missing DB or Redis logs.
🧩 No API versioning — schema changes break old clients.

Pro Tip: Treat your error structure as part of your public API contract — version it like any other endpoint.

🧠 6. Bonus: Exception-to-Code Mapping

Give each domain exception its own stable code.

class UserNotFoundException extends Exception {
    public function getErrorCode() { return 'USER_NOT_FOUND'; }
}

Then in your handler:

'code' => method_exists($e, 'getErrorCode')
    ? $e->getErrorCode()
    : class_basename($e)

Benefit: every error gets a consistent, predictable code the frontend can depend on.

📡 7. Add Correlation IDs for Cross-Service Debugging

Distributed systems demand traceability. Add a request_id for every call.

public function handle($request, Closure $next)
{
    $requestId = Str::uuid();
    Log::withContext(['request_id' => $requestId]);
    return $next($request)->header('X-Request-ID', $requestId);
}

Now every log, job, or service can be linked through a single trace ID 🔍.

🧾 8. Your Production-Ready Checklist

✅ Consistent JSON response format
✅ Domain-specific exception classes
✅ Multi-channel logging + alerting
✅ Error budgets & metrics tracking
✅ APP_DEBUG=false in production
✅ Correlation IDs for traceability
✅ Versioned error contracts

If you’ve got all of these — your API is mature, observable, and resilient.

🏁 Conclusion

Laravel gives you the tools — but production-grade stability comes from what the docs don’t teach:
structured error contracts, contextual logging, and real-time observability.

The goal isn’t to eliminate errors.
It’s to make every error actionable, traceable, and non-catastrophic. 🚀

🔔 How to Send Push Notifications in Laravel with Firebase Cloud Messaging (FCM)

Jeishanul Haque Shishir — Wed, 02 Jul 2025 17:46:14 +0000

Learn how to integrate Firebase Cloud Messaging (FCM) with Laravel to send real-time web and mobile push notifications.

Push notifications have become an essential tool for increasing user engagement and retention. Whether you're building a mobile app or a progressive web app (PWA), sending real-time alerts is crucial. In this comprehensive guide, you'll learn how to set up Laravel Firebase push notifications using Firebase Cloud Messaging (FCM)—step by step.

🚀 Why Use Firebase with Laravel?

Firebase Cloud Messaging is a free and reliable cross-platform solution from Google that enables you to send notifications and messages to devices. Laravel, being a powerful PHP framework, can easily integrate with Firebase, allowing your backend to trigger web push notifications and mobile alerts to individual users or groups.

By the end of this tutorial, you’ll have a working setup that supports:

Laravel backend sending FCM push notifications.
Web clients receiving real-time browser alerts.
Storing and managing FCM tokens in the database.

📋 Prerequisites
Before you dive into the code, ensure you have:

Laravel 8 or higher installed.
A Firebase account (Firebase Console).
Composer, Node.js, and npm installed.
Basic understanding of PHP, Laravel, and JavaScript.

🔧 Step 1: Set Up Firebase Project

1.1 Create a Firebase Project
Head to the Firebase Console.

Click on Add Project, name it (e.g., ExampleApp), and follow the prompts.

Take note of the Project ID under Project Settings > General.

1.2 Generate Service Account Key
Go to Settings > Service Accounts.

Click Generate new private key.

Rename and store the downloaded JSON file as firebase_credentials.json in storage/app/firebase/.

1.3 Add a Web App
In the Firebase console, go to Project Settings > General.

Click the </> icon to add a web app and copy the config object:

{
  "apiKey": "your-api-key",
  "authDomain": "your-auth-domain",
  "projectId": "your-project-id",
  "storageBucket": "your-storage-bucket",
  "messagingSenderId": "your-messaging-sender-id",
  "appId": "your-app-id",
  "measurementId": "your-measurement-id"
}

1.4 Retrieve the VAPID Key
Under Cloud Messaging > Web Push certificates, copy your Public Key (VAPID key). You'll need this in the frontend.

⚙️ Step 2: Configure Laravel Project

2.1 Add Environment Variables
Update your .env file:

FIREBASE_CREDENTIALS=app/firebase/firebase_credentials.json
FIREBASE_PROJECT_ID=example-app
FIREBASE_VAPID_KEY=your-vapid-key-here

2.2 Update config/services.php

'firebase' => [
    'credentials' => storage_path(env('FIREBASE_CREDENTIALS')),
    'project_id' => env('FIREBASE_PROJECT_ID'),
],

2.3 Modify Users Table for FCM Tokens
Run the migration:

php artisan make:migration add_fcm_token_to_users_table

Then, in the migration file:

Schema::table('users', function (Blueprint $table) {
    $table->string('fcm_token')->nullable();
});

Apply it:

php artisan migrate

2.4 Install Google Auth Library

composer require google/auth

💡 Step 3: Create Firebase Notification Service

Create a service class app/Services/Notifications/FireBase.php:

<?php

namespace App\Services\Notifications;

use Exception;
use Google\Auth\Credentials\ServiceAccountCredentials;
use GuzzleHttp\Client;

class FireBase
{
    public static function send($heading, $message, $deviceIds, $data = [])
    {
        $deviceIds = array_values(array_filter($deviceIds));
        if (empty($deviceIds)) {
            throw new Exception('No device IDs provided');
        }

        $scopes = ['https://www.googleapis.com/auth/firebase.messaging'];
        $credentials = new ServiceAccountCredentials($scopes, config('services.firebase.credentials'));
        $accessToken = $credentials->fetchAuthToken()['access_token'];
        $projectId = config('services.firebase.project_id');

        $messagePayload = [
            'notification' => [
                'title' => $heading,
                'body' => $message,
            ],
            'android' => [
                'priority' => 'high',
                'notification' => [
                    'sound' => 'default',
                ],
            ],
            'apns' => [
                'payload' => [
                    'aps' => [
                        'sound' => 'default',
                    ],
                ],
            ],
        ];

        if (!empty($data)) {
            $messagePayload['data'] = $data;
        }

        $messagePayload += count($deviceIds) > 1
            ? ['tokens' => $deviceIds]
            : ['token' => $deviceIds[0]];

        $payload = ['message' => $messagePayload];
        $url = "https://fcm.googleapis.com/v1/projects/{$projectId}/messages:send";

        $client = new Client();

        return $client->request('POST', $url, [
            'headers' => [
                'Authorization' => 'Bearer ' . $accessToken,
                'Accept' => 'application/json',
                'Content-Type' => 'application/json',
            ],
            'json' => $payload,
        ]);
    }
}

🖥️ Step 4: Frontend Setup for Web Push Notifications

4.1 Add Firebase Messaging Script
In your Blade template (layouts/app.blade.php):

<script type="module">
    import { initializeApp } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-app.js";
    import { getMessaging, getToken, onMessage } from "https://www.gstatic.com/firebasejs/11.0.1/firebase-messaging.js";

    const firebaseConfig = {
        apiKey: "your-api-key",
        authDomain: "your-auth-domain",
        projectId: "your-project-id",
        storageBucket: "your-storage-bucket",
        messagingSenderId: "your-messaging-sender-id",
        appId: "your-app-id",
        measurementId: "your-measurement-id"
    };

    const app = initializeApp(firebaseConfig);
    const messaging = getMessaging(app);

    async function initFirebaseMessagingRegistration() {
        try {
            const permission = await Notification.requestPermission();
            if (permission === 'granted') {
                const token = await getToken(messaging, {
                    vapidKey: "{{ env('FIREBASE_VAPID_KEY') }}"
                });

                if (token) {
                    await axios.post("{{ route('firebase.token') }}", {
                        _method: "PATCH",
                        fcm_token: token
                    });
                }
            }
        } catch (err) {
            console.error("FCM Token error:", err);
        }
    }

    onMessage(messaging, ({ notification }) => {
        new Notification(notification.title, {
            body: notification.body
        });
    });

    initFirebaseMessagingRegistration();
</script>

4.2 Create the Service Worker
Save this as public/firebase-messaging-sw.js:

importScripts("https://www.gstatic.com/firebasejs/8.3.2/firebase-app.js");
importScripts("https://www.gstatic.com/firebasejs/8.3.2/firebase-messaging.js");

firebase.initializeApp({
    apiKey: "your-api-key",
    authDomain: "your-auth-domain",
    projectId: "your-project-id",
    storageBucket: "your-storage-bucket",
    messagingSenderId: "your-messaging-sender-id",
    appId: "your-app-id",
    measurementId: "your-measurement-id",
});

const messaging = firebase.messaging();

messaging.onBackgroundMessage(({ data: { title, body, icon } }) => {
    self.registration.showNotification(title, { body, icon });
});

📩 Store FCM Tokens in Database

Create Route and Controller
Route:

Route::patch('/firebase/token', [App\Http\Controllers\FirebaseController::class, 'updateToken'])->name('firebase.token');

Controller:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;

class FirebaseController extends Controller
{
    public function updateToken(Request $request)
    {
        Auth::user()->update(['fcm_token' => $request->fcm_token]);
        return response()->json(['success' => true]);
    }
}

✉️ Sending Laravel Push Notifications via Firebase

You can now send notifications using the FireBase service class:

use App\Services\Notifications\FireBase;

FireBase::send(
    'Hello User!',
    'This is your Laravel Firebase push notification.',
    ['user-fcm-token-here'],
    ['customKey' => 'customValue']
);

🛠️ Troubleshooting Common Issues

Notification Permission Denied: Make sure users allow browser notifications.
Invalid Token: Check if FCM tokens are correctly stored.
Firebase Errors: Double-check your API key, VAPID key, and service account JSON.
403 or Auth Errors: Ensure the Firebase service account JSON is correctly set and readable.

📢 Final Thoughts

Setting up Laravel push notifications with Firebase Cloud Messaging unlocks a powerful toolset for improving user experience. Whether you're targeting mobile apps or web browsers, FCM and Laravel make a reliable and scalable combination.

✅ Now you’re ready to build apps that notify your users instantly and keep them engaged!

📬 Contact

For any questions, support, or collaboration, feel free to reach out through the following channels:

📧 Email: shishirjeishanul@gmail.com

💬 WhatsApp: Chat on WhatsApp

💻 GitHub (Main Profile): github.com/jeishanul

📦 Project Repository: Laravel Firebase Notification on GitHub