Lern81 Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require webmaster-hm/lern81
   

   Publish the configuration file:

   php artisan vendor:publish --provider="WebmasterHM\Lern81\Lern81ServiceProvider"
   

2. Configure Edit .env and config/lern81.php:

   LERN81_ENABLED=true
   LERN81_NOTIFY_ON=[production,staging]  # Comma-separated environments
   

   Define notification channels (e.g., Slack, Email) in config/lern81.php.

3. First Use Case Trigger an exception in a route or controller:

   use WebmasterHM\Lern81\Facades\Lern81;
   
   route('test-error', function () {
       Lern81::record(new \RuntimeException('Test error'));
       // Or let Laravel handle it naturally (LERN catches it automatically).
   });
   

   Verify the exception appears in lern81_exceptions table and check your configured notification channel.

Implementation Patterns

Core Workflows

1. Automatic Exception Logging LERN hooks into Laravel’s exception handler (App\Exceptions\Handler). No manual try-catch needed—just throw exceptions as usual.

2. Conditional Notifications Use environment-based filtering:

   // config/lern81.php
   'notify_on' => ['production', 'staging'], // Only notify in these envs
   

3. Custom Exception Handling Extend the base Exception model (WebmasterHM\Lern81\Models\Exception) to add custom fields:

   namespace App\Models;
   
   use WebmasterHM\Lern81\Models\Exception as BaseException;
   
   class Exception extends BaseException {
       protected $casts = [
           'user_id' => 'integer',
           'custom_data' => 'array',
       ];
   }
   

4. Manual Logging Log exceptions manually (e.g., for non-HTTP errors):

   Lern81::record(new \LogicException('Manual error'), [
       'context' => ['user_id' => auth()->id()],
   ]);
   

Integration Tips

• Queue Notifications Configure config/lern81.php to use queues for notifications:

  'queue_notifications' => true,
  

  Run the queue worker:

  php artisan queue:work
  

• Sentry Integration Forward LERN exceptions to Sentry:

  // config/lern81.php
  'sentry' => [
      'enabled' => true,
      'dsn' => env('SENTRY_DSN'),
  ],
  

• Slack/Rich Notifications Use Slack’s attachments for structured messages:

  // config/lern81.php (Slack section)
  'slack' => [
      'webhook_url' => env('SLACK_WEBHOOK'),
      'attachments' => [
          'color' => 'danger',
          'fields' => [
              ['title' => 'User', 'value' => auth()->user()->name, 'short' => true],
          ],
      ],
  ],
  

Gotchas and Tips

Pitfalls

1. Double Logging If using both LERN and Laravel’s default exception logging, ensure config/lern81.php has:

   'log_to_laravel' => false, // Avoid duplicate logs
   

2. Queue Stuck Jobs If notifications fail silently, check the failed_jobs table and ensure the queue worker is running.

3. Sensitive Data Leakage Avoid logging password or api_token fields. Use config/lern81.php to whitelist safe fields:

   'ignored_fields' => ['password', 'api_token', 'secret*'],
   

4. Environment Mismatch Verify notify_on in config/lern81.php matches your .env APP_ENV. Test locally with:

   LERN81_NOTIFY_ON=local
   

Debugging

• Check Logs View raw exception data in storage/logs/lern81.log:

  tail -f storage/logs/lern81.log
  

• Test Notifications Use php artisan lern81:notify-test to send a test alert to all configured channels.

• Database Schema If migrations fail, manually run:

  php artisan migrate --path=vendor/webmaster-hm/lern81/src/database/migrations
  

Extension Points

1. Custom Notifiers Create a new notifier by extending WebmasterHM\Lern81\Notifications\Notifier:

   namespace App\Notifications;
   
   use WebmasterHM\Lern81\Notifications\Notifier;
   
   class CustomNotifier extends Notifier {
       public function send($exception) {
           // Custom logic (e.g., HTTP request to a webhook)
       }
   }
   

   Register it in config/lern81.php:

   'notifiers' => [
       'custom' => \App\Notifications\CustomNotifier::class,
   ],
   

2. Exception Filters Filter exceptions before logging (e.g., ignore 404 errors):

   // app/Providers/Lern81ServiceProvider.php
   public function boot() {
       Lern81::filter(function ($exception) {
           return !($exception instanceof \Symfony\Component\HttpKernel\Exception\NotFoundHttpException);
       });
   }
   

3. Dynamic Context Attach dynamic context (e.g., request data) via middleware:

   namespace App\Http\Middleware;
   
   use Closure;
   use WebmasterHM\Lern81\Facades\Lern81;
   
   class AddRequestContext {
       public function handle($request, Closure $next) {
           Lern81::setContext(['request' => $request->all()]);
           return $next($request);
       }
   }
   

   Register in app/Http/Kernel.php:

   protected $middleware = [
       \App\Http\Middleware\AddRequestContext::class,
   ];