Sdk Core Laravel Package

Technical Evaluation

Architecture Fit

• PSR Compliance: The package adheres to PSR-3 (LoggerInterface), PSR-18 (HTTP Client), and PSR-17 (HTTP Factories), making it a seamless fit for modern PHP applications (Laravel included). Laravel’s built-in Monolog (PSR-3) and GuzzleHttp (PSR-18) align perfectly, reducing integration friction.
• Framework-Agnostic Core: While designed for framework adapters (e.g., applogger/symfony-bundle), the core SDK can be directly integrated into Laravel via a custom facade or service provider, bypassing the need for a dedicated bundle.
• Error Tracking vs. Logging: The package dual-purpose design (structured logs + error tracking) aligns with Laravel’s need for both debugging (logs) and production monitoring (errors). However, Laravel’s existing Log facade and Sentry/Monolog integrations may require careful orchestration to avoid redundancy.
• Privacy-First EU Hosting: A strong differentiator for GDPR-compliant applications, though Laravel’s default logging (e.g., to local files) may still be needed for compliance.

Integration Feasibility

• Low Coupling: The SDK’s non-blocking, non-throwing design ensures it won’t disrupt Laravel’s execution flow (e.g., no exceptions in shutdown handlers).
• Automatic Integrations: The default global error/fatal handler can replace or supplement Laravel’s registerShutdownFunctions and handleExceptions, but conflicts may arise with Laravel’s built-in error handling (e.g., App\Exceptions\Handler).
• Delivery Modes: Supports FastCGI, Swoole, RoadRunner, and CLI, which covers Laravel’s common deployment modes (except possibly Laravel Octane’s custom server modes, which may need explicit testing).
• Structured Logging: The PSR-3 logger can coexist with Laravel’s Monolog but may require a custom handler to avoid duplicate logs or merge contexts (e.g., Laravel’s stack vs. AppLogger’s scope).

Technical Risk

• Dependency on External Service: AppLogger’s EU-hosted backend introduces latency and uptime risks. Laravel’s self-hosted logging (e.g., ELK, Loki) may be preferred for air-gapped or high-reliability systems.
• PHP 8.3+ Requirement: Laravel LTS (v10+) supports PHP 8.2+, so backward compatibility with older Laravel versions (e.g., v9) may require polyfills or a separate branch.
• Conflict with Existing Tools:
  • Sentry/Monolog: AppLogger’s error tracking may overlap with Sentry’s. A single source of truth strategy (e.g., route all errors to AppLogger or Sentry) must be defined.
  • Laravel’s tap/when: The SDK’s configureScope/withScope could clash with Laravel’s context managers if not namespaced carefully.
• Testing Overhead: The package’s shutdown/fatal handler and delivery modes require edge-case testing (e.g., OOM kills, FastCGI timeouts) to ensure robustness in Laravel’s deployment environments.

Key Questions

1. Error Handling Strategy:
   • Should AppLogger replace Laravel’s App\Exceptions\Handler or supplement it? How will duplicate error reports be avoided?
2. Logging Strategy:
   • Will AppLogger’s PSR-3 logger replace, extend, or run parallel to Laravel’s Monolog? How will log levels (e.g., debug vs. error) be mapped?
3. Performance Impact:
   • What is the network overhead of shipping logs/errors to AppLogger’s ClickHouse backend? Are there batch/async delivery optimizations?
4. GDPR Compliance:
   • How does AppLogger’s data scrubbing integrate with Laravel’s Log::onlyInProduction or Log::stack for PII masking?
5. Deployment Modes:
   • Has the SDK been tested with Laravel Octane (custom server modes like Swoole, RoadRunner)? Are there worker-specific quirks (e.g., queue workers)?
6. Cost vs. Value:
   • What is the pricing model for AppLogger? How does it compare to self-hosted solutions (e.g., ELK) or competitors (e.g., Sentry, Datadog)?
7. Migration Path:
   • If adopting AppLogger, how will existing log files (e.g., Laravel’s storage/logs) be migrated or archived?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • PHP 8.3+: Laravel 10+ is compatible; older versions may require PHP 8.3 upgrades or polyfills.
  • PSR Standards: Laravel’s Monolog (PSR-3) and GuzzleHttp (PSR-18) are directly compatible with the SDK’s requirements.
  • Service Container: The SDK can be registered as a Laravel service provider, injecting the AppLogger client and PSR-3 logger into the container.
• Existing Integrations:
  • Sentry: If using Sentry, decide whether to route all errors to AppLogger (replacing Sentry) or split by severity (e.g., critical errors to Sentry, others to AppLogger).
  • Monolog Handlers: The SDK’s PSR-3 logger can be added as a Monolog handler or used as a standalone logger for structured data.
• Queue Workers: The SDK’s worker-aware delivery should work with Laravel Queues, but async job failures (e.g., ShouldQueue exceptions) may need explicit handling.

Migration Path

1. Pilot Phase (Low Risk):
   • Add as a Dependency: Install via Composer (applogger/sdk-core).
   • Opt-In Error Tracking: Use AppLogger::captureException() in App\Exceptions\Handler for critical errors only.
   • Structured Logging: Replace Log::info() with AppLogger::logger()->info() for specific use cases (e.g., audit logs).
2. Full Integration:
   • Replace Global Handlers: Disable Laravel’s default error handler and enable AppLogger’s shutdown/fatal handler via default_integrations.
   • Unify Logging: Configure Monolog to forward logs to AppLogger via a custom handler or use AppLogger’s PSR-3 logger exclusively.
   • Context Propagation: Migrate Laravel’s Log::withContext() usage to AppLogger::configureScope().
3. Phased Rollout:
   • Staging First: Test in a non-production environment with real traffic to validate performance and error capture.
   • Feature Flags: Use Laravel’s config or environment variables to toggle AppLogger on/off per environment.

Compatibility

• Laravel-Specific Considerations:
  • Artisan Commands: The SDK’s CLI delivery mode should work, but long-running commands (e.g., queue:work) may need explicit flushing.
  • Middleware: Breadcrumbs (e.g., addBreadcrumb) can be added in Laravel middleware, but ensure they don’t bloat request context.
  • Testing: The SDK’s non-throwing design is ideal for Laravel’s testing (e.g., phpunit), but assertions on error capture may require custom helpers.
• Database/ORM: No direct integration with Laravel’s Eloquent, but query logging (e.g., via DB::listen) can be forwarded to AppLogger via breadcrumbs or structured logs.

Sequencing

1. Pre-Integration:
   • Audit existing error logging (Sentry, Monolog, custom handlers).
   • Define error routing rules (e.g., "All 5xx errors to AppLogger, 4xx to Sentry").
2. Core Setup:
   • Publish the SDK’s config (if any) and bind it to Laravel’s service container.
   • Configure data scrubbing for GDPR compliance (e.g., mask request->input('password')).
3. Error Handling:
   • Replace or extend App\Exceptions\Handler to use AppLogger::captureException().
   • Test fatal errors (e.g., simulate OOM kills) to validate shutdown handlers.
4. Logging:
   • Replace Monolog handlers with AppLogger’s PSR-3 logger for structured logs.
   • Use withScope in critical paths (e.g., API gateways) to attach user/context data.
5. Validation:
   • Verify log/error delivery in AppLogger’s dashboard.
   • Check performance impact (e.g., response times, queue delays).
6. Optimization:
   • Adjust DeliveryMode for high-throughput environments (e.g., RoadRunner workers).
   • Implement rate limiting if AppLogger’s API has usage quotas.

Operational Impact