Barstool Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require saloonphp/barstool
   

   Publish the config file:

   php artisan vendor:publish --provider="Saloon\Barstool\BarstoolServiceProvider"
   

2. Configure Database Ensure your .env has a database connection (e.g., DB_CONNECTION=mysql). Run migrations:

   php artisan migrate
   

   Note: If migrations fail due to incorrect config keys, verify config/barstool.php uses the correct database connection key (e.g., mysql instead of deprecated pgsql if applicable).

3. First Use Case: Logging a Request Extend your Saloon Http class to use Barstool:

   use Saloon\Barstool\Concerns\LogsRequests;
   
   class MyApi extends Http
   {
       use LogsRequests;
   }
   

   Now, every request made via MyApi will be automatically logged to the database.

Where to Look First

• Config File: config/barstool.php – Adjust logging behavior (e.g., enabled/disabled, table names).
• Migrations: database/migrations/ – Inspect barstool_requests and barstool_responses tables. Note: The status column (if present) has been removed in v1.1.1.
• Middleware: app/Http/Middleware/ – Check if Barstool middleware is registered (if using HTTP logging).

Implementation Patterns

Core Workflows

1. Automatic Logging Use the LogsRequests trait in your Saloon Http classes to log all requests/responses:

   class GitHubApi extends Http
   {
       use LogsRequests;
   
       public function resolveEndpoint(): string
       {
           return 'https://api.github.com/user';
       }
   }
   

2. Manual Logging Log specific requests/responses manually:

   $response = $this->send(new MyRequest());
   Barstool::logRequest($this->endpoint(), $this->connector(), $response);
   

3. Querying Logs Use the Barstool facade to fetch logs:

   $logs = Barstool::getRequests(['limit' => 10]); // Returns a collection of logged requests
   

Integration Tips

• API Testing: Use Barstool logs to debug failed API calls during testing.
• Monitoring: Query logs to track API usage patterns or failures:

  $failedLogs = Barstool::getRequests(['status_code' => 500]);
  

• Custom Fields: Extend the barstool_requests table via migrations to store additional metadata (e.g., user_id for tracking which user made the request).

Advanced Patterns

1. Conditional Logging Disable logging for specific endpoints:

   class MyApi extends Http
   {
       use LogsRequests;
   
       protected bool $shouldLogRequests = false; // Disable logging
   }
   

2. Logging HTTP Requests Use the LogsHttpRequests middleware to log HTTP requests (not just Saloon):

   // In AppServiceProvider@boot()
   $this->app->make(\Saloon\Barstool\Http\Middleware\LogsHttpRequests::class)->appendToKernel();
   

3. Exporting Logs Create a custom exporter to dump logs to a file or external service:

   Barstool::exportLogsToFile('path/to/logs.json');
   

Gotchas and Tips

Pitfalls

1. Performance Overhead

   • Logging every request adds database writes. For high-frequency APIs, consider:
     • Disabling logging for non-critical endpoints.
     • Using queue workers to batch log writes:

       Barstool::queueLog($request, $response); // Uses Laravel queues
       

2. Table Bloat

   • The barstool_requests and barstool_responses tables can grow large. Implement a cleanup job:

     php artisan schedule:run
     

     Add to app/Console/Kernel.php:

     protected function schedule(Schedule $schedule)
     {
         $schedule->command('barstool:prune --days=30')->daily();
     }
     

3. Sensitive Data

   • Avoid logging sensitive data (e.g., passwords, tokens). Use shouldLogBody() to filter payloads:

     class MyApi extends Http
     {
         protected function shouldLogBody(): bool
         {
             return !in_array($this->endpoint(), ['/sensitive']);
         }
     }
     

4. Migration Issues

   • If upgrading from an older version, ensure the status column (if present) is removed from your database tables. Run fresh migrations if needed:

     php artisan migrate:fresh --env=testing
     

Debugging Tips

1. Log Not Appearing?

   • Verify the LogsRequests trait is used in your Http class.
   • Check if the barstool config is enabled ('enabled' => true in config/barstool.php).
   • Ensure the database connection is correct in .env and matches the config key (e.g., mysql instead of deprecated keys).

2. Querying Issues

   • Use Barstool::getRequests() with dd() to inspect the returned data structure:

     dd(Barstool::getRequests(['limit' => 1]));
     

   • Check for SQL errors in Laravel logs (storage/logs/laravel.log).

3. Middleware Conflicts

   • If using LogsHttpRequests, ensure it’s registered after Saloon’s middleware in app/Http/Kernel.php.

Extension Points

1. Custom Logging Logic Override the logRequest method in a service provider:

   Barstool::extend(function ($request, $response) {
       // Custom logic (e.g., add tags, enrich data)
       $response->setMetadata(['custom_field' => 'value']);
   });
   

2. Event Listeners Listen to Barstool\Events\RequestLogged to react to logged requests:

   Barstool::listen(function ($request) {
       // Trigger analytics, notifications, etc.
   });
   

3. Testing Mock Barstool in tests to avoid database hits:

   Barstool::shouldReceive('logRequest')->once();