Logger Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require atom/logger-bundle
   

   Ensure kriswallsmith/buzz and manhattan/restful are auto-installed (check composer.lock).

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Atom\LoggerBundle\AtomLoggerBundle::class => ['all' => true],
   ];
   

3. Configure atom_logger.yml Place in config/packages/atom_logger.yaml:

   atom_logger:
       api_key: '%env(ATOM_LOGGER_API_KEY)%'
       project_id: '%env(ATOM_LOGGER_PROJECT_ID)%'
       environment: '%kernel.environment%'
   

   (Define env vars in .env or .env.local.)

4. First Use Case: Logging Exceptions The bundle auto-catches uncaught exceptions via Symfony’s ErrorListener. Verify by throwing an exception:

   throw new \RuntimeException('Test error for AtomLogger');
   

   Check the AtomLogger dashboard for the logged error.

Implementation Patterns

1. Manual Error Logging

Use the AtomLogger service to log errors explicitly:

use Atom\LoggerBundle\Service\AtomLogger;

// In a controller/service:
public function someAction(AtomLogger $atomLogger) {
    try {
        // Risky operation...
    } catch (\Exception $e) {
        $atomLogger->logException($e, [
            'user_id' => 123,
            'context' => 'Checkout flow',
        ]);
    }
}

2. Custom Error Context

Attach metadata to errors for debugging:

# config/packages/atom_logger.yaml
atom_logger:
    default_context:
        app_version: '%kernel.version%'
        request_id: '%env(REQUEST_ID)%'

This context auto-attaches to all logged errors.

3. Async Logging (Advanced)

For performance, offload logging to a queue (e.g., Symfony Messenger):

# config/packages/atom_logger.yaml
atom_logger:
    async: true
    queue: 'atom_logger_queue'

Requires configuring a message handler (e.g., AtomLoggerMessageHandler).

4. Integration with Monolog

Bridge AtomLogger with Monolog for structured logging:

use Monolog\Logger;
use Atom\LoggerBundle\Handler\AtomLoggerHandler;

$monolog = new Logger('app');
$monolog->pushHandler(new AtomLoggerHandler($atomLoggerService));

Log via Monolog as usual:

$monolog->error('Database connection failed', ['query' => 'SELECT * FROM users']);

5. Environment-Specific Logging

Disable logging in dev:

atom_logger:
    environments: ['prod', 'staging']  # Only log in these environments

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never commit .env or hardcode api_key in config. Use environment variables.
   • Validate the key exists in config/packages/atom_logger.yaml:

     atom_logger:
         api_key: '%env(ATOM_LOGGER_API_KEY)%'
         # ...
     

     (Fails silently if missing; add a validator if needed.)

2. Rate Limiting

   • AtomLogger may throttle requests. Handle Buzz\Exception\TimeoutException:

     $atomLogger->logException($e)->catch(
         \Buzz\Exception\TimeoutException::class,
         fn() => $this->retryLater()
     );
     

3. Symfony 5+ Compatibility

   • The bundle targets Symfony 2. Test in Symfony 5/6 by:
     • Updating manhattan/restful to a stable version (avoid dev-master).
     • Overriding the ErrorListener if needed (check src/DependencyInjection/).

4. Context Overrides

   • Custom context in logException() replaces default context. Merge instead:

     $atomLogger->logException($e, array_merge(
         $atomLogger->getDefaultContext(),
         ['custom_key' => 'value']
     ));
     

Debugging

1. Verify API Calls Enable HTTP client logging in config/packages/atom_logger.yaml:

   atom_logger:
       debug: true
   

   Check logs for raw API requests/responses.

2. Test Locally Use a mock HTTP client for development:

   // config/services.yaml
   Atom\LoggerBundle\Service\AtomLogger:
       arguments:
           $client: '@http_client_mock'  # Use a mock client (e.g., `php-http/client-mock`)
   

3. Check Response Codes AtomLogger may return 4xx/5xx. Handle in a custom handler:

   $atomLogger->setResponseHandler(function ($response) {
       if ($response->getStatusCode() >= 400) {
           // Log locally or retry
       }
   });
   

Extension Points

1. Custom Error Formatter Extend Atom\LoggerBundle\Formatter\ErrorFormatter to modify payloads:

   class CustomErrorFormatter extends ErrorFormatter {
       public function format(\Throwable $exception) {
           $data = parent::format($exception);
           $data['custom_field'] = 'value';
           return $data;
       }
   }
   

   Register in services.yaml:

   Atom\LoggerBundle\Service\AtomLogger:
       arguments:
           $formatter: '@custom_error_formatter'
   

2. Webhook Integration Trigger actions on new errors via AtomLogger’s webhooks. Use the AtomLogger service to:

   • Fetch recent errors: $atomLogger->fetchErrors().
   • Filter by context: $atomLogger->fetchErrors(['environment' => 'prod']).

3. Batch Processing For high-volume apps, batch errors before sending:

   $atomLogger->setBatchSize(50); // Send every 50 errors
   $atomLogger->logException($e1);
   $atomLogger->logException($e2);
   // ... (batch sends automatically)