Download the PHP package joshghent/loginllama without Composer

LoginLlama PHP Client

Official PHP SDK for LoginLlama - AI-powered login security and fraud detection.

Features

• Automatic Context Detection: Auto-detects IP address and User-Agent from Laravel, Symfony, WordPress, and vanilla PHP
• Multi-Source IP Extraction: Supports X-Forwarded-For, CF-Connecting-IP, X-Real-IP, True-Client-IP with private IP filtering
• Framework Support: Works with Laravel, Symfony, WordPress, and vanilla PHP
• Middleware Integration: Drop-in middleware for Laravel and Symfony
• Webhook Verification: Built-in HMAC signature verification

Installation

Requires PHP 8.3 or higher.

Quick Start

Vanilla PHP

The simplest way to use LoginLlama in vanilla PHP - IP and User-Agent are automatically detected from $_SERVER:

With Request Object

If you have a framework request object, you can pass it explicitly:

Manual Override

Or provide IP and User-Agent manually:

Framework Examples

Laravel

Symfony

WordPress

API Reference

new LoginLlama($apiKey, $baseUrl = null)

Create a new LoginLlama client.

Parameters:

• $apiKey (required): Your API key from LoginLlama dashboard
• $baseUrl (optional): Custom API endpoint for testing

$loginllama->check($identityKey, $options = [])

Check a login attempt for suspicious activity.

Parameters:

• $identityKey (required): User identifier (email, username, user ID, etc.)
• $options (optional array):
  • 'ipAddress': Override auto-detected IP address
  • 'userAgent': Override auto-detected User-Agent
  • 'request': Explicit request object (Laravel, Symfony)
  • 'emailAddress': User's email address for additional verification
  • 'geoCountry': ISO country code (e.g., 'US', 'GB')
  • 'geoCity': City name for additional context
  • 'userTimeOfDay': Time of login attempt
  • 'timestamp': Timestamp of the login attempt (ISO 8601 recommended)
  • 'authenticationOutcome': 'success' (default), 'failed', or 'pending'

Returns: Associative array

Detection Priority:

1. Explicit 'ipAddress' and 'userAgent' in options array
2. Extract from 'request' object if provided
3. Use stored context from middleware (if used)
4. Fallback to $_SERVER superglobal

Examples:

$loginllama->middleware()

Returns middleware callable for Laravel/Symfony that automatically captures request context.

Laravel Middleware:

Symfony Event Subscriber:

LoginLlama::verifyWebhookSignature($payload, $signature, $secret)

Verify webhook signature using constant-time HMAC comparison.

Parameters:

• $payload: Raw webhook body (string)
• $signature: Value from X-LoginLlama-Signature header
• $secret: Webhook secret from LoginLlama dashboard

Returns: bool

Login Status Codes

The SDK provides constants for all possible status codes:

Error Handling

The SDK will throw \Exception if required parameters are missing:

Best Practice: Fail open on errors to avoid blocking legitimate users during API outages:

IP Detection

The SDK automatically detects IP addresses from multiple sources with priority fallback:

1. HTTP_X_FORWARDED_FOR - Parses chain, takes first public IP (filters private IPs)
2. HTTP_CF_CONNECTING_IP - Cloudflare real client IP
3. HTTP_X_REAL_IP - nginx proxy header
4. HTTP_TRUE_CLIENT_IP - Akamai/Cloudflare header
5. REMOTE_ADDR - Direct connection IP

Private IP Filtering: Automatically filters 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.x.x.x, ::1, fc00::/7, fe80::/10

Environment Variables

You can set your API key as an environment variable:

Then initialize without arguments:

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

GNU GPL v3

Support

• Documentation: loginllama.app/docs
• Dashboard: loginllama.app/dashboard
• Issues: GitHub Issues