Getting Started

Minimal Setup

Installation
```
composer require boxalino/rtux-api-php
```
Add the package to your composer.json and run composer update.
First Configuration Locate the package's config file (published via php artisan vendor:publish --provider="Boxalino\RtuxApi\RtuxServiceProvider"). Set your API credentials in config/rtux.php:
```
'api_key' => env('RTUX_API_KEY'),
'base_uri' => env('RTUX_API_BASE_URI', 'https://api.boxalino.com/rtux/v1'),
```

First API Call Use the facade or service container to send a basic event:

use Boxalino\RtuxApi\Facades\Rtux;

Rtux::event('user_viewed_page', [
    'user_id' => 123,
    'page_url' => '/dashboard',
    'metadata' => ['referrer' => '/login']
]);

Environment Variables Add to .env:

RTUX_API_KEY=your_api_key_here
RTUX_API_BASE_URI=https://your-custom-endpoint.com/rtux/v1

First Use Case: Tracking Page Views

// In your controller or middleware
use Boxalino\RtuxApi\Facades\Rtux;

public function showDashboard()
{
    Rtux::event('page_view', [
        'user_id' => auth()->id(),
        'page_url' => request()->url(),
        'page_title' => 'Dashboard',
        'timestamp' => now()->toIso8601String()
    ]);

    return view('dashboard');
}

Implementation Patterns

Common Workflows

1. Event Tracking

Standard Events

Rtux::event('user_action', [
    'user_id' => $user->id,
    'action' => 'purchase',
    'amount' => 99.99,
    'currency' => 'USD'
]);

Custom Events Define custom events in config/rtux.php:

'custom_events' => [
    'checkout_started' => ['user_id', 'cart_id', 'items_count'],
    'checkout_abandoned' => ['user_id', 'step']
],

Then use:

Rtux::event('checkout_started', ['user_id' => 123, 'cart_id' => 'abc123', 'items_count' => 5]);

2. User Identification

Anonymous Users

Rtux::identify('anonymous_' . Str::uuid());

Authenticated Users
```
Rtux::identify(auth()->user()->id);
```

3. Batch Processing

Use the batch() method for bulk events (e.g., during cron jobs):

Rtux::batch([
    ['event' => 'user_viewed_product', 'data' => ['user_id' => 1, 'product_id' => 101]],
    ['event' => 'user_added_to_cart', 'data' => ['user_id' => 1, 'product_id' => 102]],
]);

4. Middleware Integration

Track events automatically in middleware:

namespace App\Http\Middleware;

use Boxalino\RtuxApi\Facades\Rtux;
use Closure;

class TrackPageViews
{
    public function handle($request, Closure $next)
    {
        Rtux::event('page_view', [
            'user_id' => auth()->id(),
            'page_url' => $request->url(),
            'http_method' => $request->method(),
        ]);

        return $next($request);
    }
}

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

5. Error Handling

Wrap API calls in try-catch:

try {
    Rtux::event('critical_error', ['user_id' => 123, 'error' => 'Database connection failed']);
} catch (\Boxalino\RtuxApi\Exceptions\RtuxException $e) {
    Log::error('RTUX API Error: ' . $e->getMessage());
}

Integration Tips

Laravel Services

Inject the Rtux facade or service into your services:

use Boxalino\RtuxApi\Facades\Rtux;

class AnalyticsService
{
    public function __construct(protected Rtux $rtux) {}

    public function trackUserActivity($userId, $activity)
    {
        $this->rtux->event('user_activity', [
            'user_id' => $userId,
            'activity' => $activity,
        ]);
    }
}

Queueing Events

Offload RTUX events to a queue to avoid blocking requests:

use Boxalino\RtuxApi\Facades\Rtux;
use Illuminate\Support\Facades\Queue;

Queue::push(function () {
    Rtux::event('queued_event', ['user_id' => 123, 'data' => 'Processed later']);
});

Testing

Mock the RTUX client in tests:

$mock = Mockery::mock('Boxalino\RtuxApi\RtuxClient');
$mock->shouldReceive('sendEvent')->once();
$this->app->instance('Boxalino\RtuxApi\RtuxClient', $mock);

Gotchas and Tips

Pitfalls

API Key Exposure
- Risk: Hardcoding API keys in config files or version control.
- Fix: Use Laravel's .env and restrict file permissions.
```
chmod 600 .env
```

Rate Limiting

Issue: The API may throttle requests if too many events are sent in a short time.

Solution: Implement exponential backoff or queue events.

// Example: Retry with delay
$attempts = 0;
while ($attempts < 3) {
    try {
        Rtux::event('rate_limited_event', [...]);
        break;
    } catch (\Boxalino\RtuxApi\Exceptions\RateLimitExceededException $e) {
        $attempts++;
        sleep(2 ** $attempts); // Exponential backoff
    }
}

Data Validation

Gotcha: The package may silently drop malformed events.

Tip: Validate data before sending:

$data = [
    'user_id' => $user->id,
    'page_url' => filter_var(request()->url(), FILTER_VALIDATE_URL),
];
if ($data['page_url'] === false) {
    $data['page_url'] = '/invalid-url';
}
Rtux::event('page_view', $data);

Deprecated Methods

Warning: The package was last updated in 2020. Check for breaking changes if the API evolves.

Workaround: Extend the client class to add compatibility:

namespace App\Services;

use Boxalino\RtuxApi\RtuxClient;

class ExtendedRtuxClient extends RtuxClient
{
    public function sendEventWithRetry($event, $data, $retries = 3)
    {
        // Custom retry logic
    }
}

Debugging

Enable Logging Configure Monolog in config/logging.php to log RTUX requests:

'channels' => [
    'rtux' => [
        'driver' => 'single',
        'path' => storage_path('logs/rtux.log'),
        'level' => 'debug',
    ],
],

Then enable logging in config/rtux.php:

'debug' => env('RTUX_DEBUG', false),

HTTP Client Debugging Use Laravel's HTTP client to inspect requests:

$client = app('Boxalino\RtuxApi\RtuxClient');
$client->getHttpClient()->debug();

Common Errors
- 401 Unauthorized: Invalid API key. Verify .env and config.
- 429 Too Many Requests: Hit rate limits. Implement retries or queue events.
- 500 Internal Server Error: API-side issue. Check their status page or logs.

Extension Points

Custom HTTP Client Override the default Guzzle client:

// In a service provider
$this->app->singleton('Boxalino\RtuxApi\RtuxClient', function ($app) {
    $client

Rtux Api Php Laravel Package