Getting Started

This package (anzutap-bundle) integrates AnzuTap (a data tap/observability tool) into Laravel applications. To start, install via Composer:

composer require anzusystems/anzutap-bundle

Publish the config file (if needed) and register the bundle in config/app.php under providers. The package requires Symfony 6+ (now updated for Symfony 8 compatibility in v0.12.0). Verify your Laravel/Symfony version alignment in composer.json.

First use case: Instrument a controller or service method with AnzuTap’s tap points. Example:

use AnzuTap\Bundle\AnzuTapBundle;

$tap = app(AnzuTapBundle::class)->tap('my.tap.point');
$tap->start();
try {
    // Business logic here
} finally {
    $tap->stop();
}

Implementation Patterns

Core Workflows

Tap Integration:
- Use AnzuTapBundle to create taps for:
  - Database queries (via Eloquent events or query builder hooks).
  - HTTP requests (middleware or Illuminate\Http\Client events).
  - Business logic (service layers).
- Example for Eloquent:
```
use AnzuTap\Bundle\Event\QueryExecuted;

Event::listen(QueryExecuted::class, function ($event) {
    $tap = app(AnzuTapBundle::class)->tap('db.query');
    $tap->addData(['query' => $event->query]);
    $tap->stop();
});
```
Configuration:
- Customize tap names, sampling rates, or metadata via config/anzutap.php (publish with php artisan vendor:publish --provider="AnzuTap\Bundle\AnzuTapBundle").
- Environment-specific settings (e.g., ANZUTAP_ENABLED=false in .env).

Middleware for HTTP Taps:

public function handle($request, Closure $next) {
    $tap = app(AnzuTapBundle::class)->tap('http.request');
    $tap->addData(['url' => $request->url()]);
    return $next($request)->thenReturn(function ($response) use ($tap) {
        $tap->addData(['status' => $response->status()])->stop();
        return $response;
    });
}

Advanced Patterns

Context Propagation: Attach user IDs or request IDs to taps for traceability:

$tap->addContext(['user_id' => auth()->id(), 'request_id' => $request->header('X-Request-ID')]);

Conditional Taps: Disable taps in development:

if (app()->environment('production')) {
    $tap = app(AnzuTapBundle::class)->tap('analytics.event');
    // ...
}

Gotchas and Tips

Breaking Changes & Deprecations

Symfony 8 Compatibility: v0.12.0 resolves deprecations for Symfony 8. If using Symfony 7 or lower, ensure no breaking changes affect your setup (e.g., dependency updates). Test with:
```
composer require symfony/*:^8.0 --dev
vendor/bin/phpunit
```
Laravel 10+: Confirm compatibility if upgrading. The bundle may rely on Symfony components updated in Laravel 10.

Debugging

Tap Not Firing?:
- Verify the bundle is registered in config/app.php.
- Check config/anzutap.php for disabled taps or misconfigured endpoints.
- Use tap('debug.test')->start()->stop() to confirm basic functionality.
Data Loss: Ensure stop() is called in a finally block or using try-catch to avoid incomplete taps.

Performance Tips

Sampling: Use addData() sparingly for high-frequency taps (e.g., database queries). Sample 1 in 100:
```
if (rand(0, 100) < 1) {
    $tap->addData(['sample' => 'data']);
}
```
Async Writes: The bundle buffers taps; flush manually if needed:
```
app(AnzuTapBundle::class)->flush();
```

Extension Points

Custom Tap Types: Extend the bundle by creating a service provider to register new tap handlers:

public function register() {
    $this->app->singleton('custom.tap', function () {
        return new CustomTapHandler();
    });
}

Event Listeners: Hook into AnzuTap\Bundle\Event\TapStarted/TapStopped for cross-cutting concerns.

Configuration Quirks

Endpoint URLs: Ensure config/anzutap.endpoint points to your AnzuTap collector (e.g., https://collector.anzutap.com).
SSL: If using self-signed certs, configure config/anzutap.http_client to bypass SSL verification (not recommended for production).

Logging

Enable debug logs in config/anzutap.php:
```
'debug' => env('APP_DEBUG', false),
```
Check storage/logs/laravel.log for initialization errors or tap failures.

Anzutap Bundle Laravel Package