Userhub API
External user system integration with caching and authentication
Overview
The Userhub package provides integration with an external user management system. It includes HTTP client for API communication, local caching for performance, and optional proxy endpoints for seamless integration with your application.
🔐 Authentication
- Email/Password → Bearer token
- Bearer Token
- Basic Auth / API Key
- Configurable methods
⚡ Performance
- Local caching
- Configurable TTL
- Cache management
- Error handling
🎯 Features
- User lookup (ID/email)
- Profile endpoints
- User search
- Verification
Note: The Userhub package acts as a client to an external API. Configure the external API URL and authentication in
config/userhub.php.
⚙️ Configuration
Configure the external Userhub API connection in config/userhub.php:
'api_url' => env('USERHUB_API_URL', 'https://userhub.example.com/api'),
'auth_method' => env('USERHUB_AUTH_METHOD', 'login'), // login, bearer, basic, api_key
'email' => env('USERHUB_EMAIL'),
'password' => env('USERHUB_PASSWORD'),
'api_key' => env('USERHUB_API_KEY'),
'api_secret' => env('USERHUB_API_SECRET'),
'timeout' => 30,
'cache_enabled' => true,
'cache_ttl' => 3600, // 1 hour
Environment Variables (recommended login flow):
USERHUB_API_URL=https://your-userhub-api.com/api
USERHUB_AUTH_METHOD=login
USERHUB_EMAIL=communicationhub@omgevingshuis.nl
USERHUB_PASSWORD=your_password_here
USERHUB_CACHE_ENABLED=true
USERHUB_CACHE_TTL=3600
For legacy auth, set USERHUB_AUTH_METHOD to bearer, basic, or api_key and provide the corresponding keys.
💻 Using the Userhub Facade
The package provides a Userhub facade for easy access to user data from anywhere in your application:
Get User by ID
use Omgevingshuis\Userhub\Userhub;
$user = Userhub::getUserById(123);
if ($user) {
echo $user['name'];
echo $user['email'];
}
Get User by Email
$user = Userhub::getUserByEmail('user@example.com');
if ($user) {
echo $user['id'];
}
Get User Profile
$profile = Userhub::getUserProfile(123);
if ($profile) {
echo $profile['phone'];
echo $profile['address'];
}
Verify User
$isVerified = Userhub::verifyUser(123);
if ($isVerified) {
// User exists and is active
}
Search Users
$users = Userhub::searchUsers([
'query' => 'John',
'limit' => 10
]);
Get Multiple Users
$users = Userhub::getUsersByIds([123, 456, 789]);
Clear Cache
// Clear specific user cache
Userhub::clearCache(123);
// Clear all cache (use with caution)
Userhub::clearCache();
🌐 API Endpoints (Optional Proxy)
If you enable local routes in config ('enable_local_routes' => true), these endpoints will be available:
GET
/api/userhub/users/{id}
Get user by ID
GET /api/userhub/users/123
Response:
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-12-20T14:22:00Z"
}
GET
/api/userhub/users/email/{email}
Get user by email address
GET /api/userhub/users/email/john@example.com
Response:
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
...
}
GET
/api/userhub/users/{id}/profile
Get user profile with additional details
GET /api/userhub/users/123/profile
Response:
{
"user_id": 123,
"phone": "+31612345678",
"address": "123 Main St",
"city": "Amsterdam",
"country": "Netherlands",
"preferences": {...}
}
GET
/api/userhub/users/{id}/verify
Verify if user exists and is active
GET /api/userhub/users/123/verify
Response:
{
"user_id": 123,
"verified": true
}
GET
/api/userhub/users
Search users with query parameters
GET /api/userhub/users?query=John&limit=10
Response:
{
"data": [
{
"id": 123,
"name": "John Doe",
"email": "john@example.com"
},
...
],
"total": 25,
"per_page": 10,
"current_page": 1
}
🔧 Using in Models
Reference external users in your models using user_id:
Example: Inquiry Model
use Omgevingshuis\Userhub\Userhub;
class Inquiry extends Model
{
protected $fillable = ['user_id', 'inquiry_type_id', 'message', ...];
// Get user data from external API
public function user()
{
return Userhub::getUserById($this->user_id);
}
// Or as an accessor
public function getUserAttribute()
{
return Userhub::getUserById($this->user_id);
}
}
// Usage
$inquiry = Inquiry::find(1);
$user = $inquiry->user();
echo $user['name']; // "John Doe"
Example: Order Model
class Order extends Model
{
public function user()
{
return Userhub::getUserById($this->user_id);
}
}
// Usage
$order = Order::find(5);
$user = $order->user();
echo $user['email']; // "john@example.com"
💾 Caching
The Userhub client automatically caches user data to reduce external API calls and improve performance.
Cache Keys
userhub.user.{id}- User data by IDuserhub.user.email.{md5(email)}- User data by email
Cache Duration
Default: 3600 seconds (1 hour). Configure in config/userhub.php:
'cache_ttl' => 3600, // seconds
Manual Cache Management
// Clear specific user cache
Userhub::clearCache(123);
// Clear all Userhub cache
Userhub::clearCache();
⚠️ Error Handling
The client gracefully handles errors and returns null when users are not found or API errors occur:
$user = Userhub::getUserById(999);
if (!$user) {
// User not found or API error
return response()->json(['error' => 'User not found'], 404);
}
// Use user data
return response()->json($user);
Logging: All API errors are automatically logged to
storage/logs/laravel.log with detailed context.
🔄 Custom Requests
Make custom API requests to the external Userhub:
$result = Userhub::request('POST', '/users/123/notifications', [
'json' => [
'message' => 'Welcome!',
'type' => 'email'
]
]);
if ($result) {
// Request successful
}
📖 Integration Examples
Creating an Inquiry with User
use Omgevingshuis\Inquiries\Models\Inquiry;
use Omgevingshuis\Userhub\Userhub;
// Verify user exists
if (!Userhub::verifyUser($userId)) {
return response()->json(['error' => 'Invalid user'], 400);
}
// Create inquiry
$inquiry = Inquiry::create([
'user_id' => $userId,
'inquiry_type_id' => 1,
'message' => 'Request information about...',
'status' => 'open'
]);
// Get user details for response
$user = Userhub::getUserById($inquiry->user_id);
return response()->json([
'inquiry' => $inquiry,
'user' => $user
]);
Timeline with User Data
use Omgevingshuis\Cases\Http\Controllers\CasesController;
// Get timeline for specific user
$timeline = CasesController::timeline($request->merge(['user_id' => 123]));
// Timeline includes inquiries and orders
foreach ($timeline['data'] as $item) {
$user = Userhub::getUserById($item['user_id']);
echo $user['name'] . ' - ' . $item['type'] . ': ' . $item['title'];
}
🔐 Authentication Methods
Bearer Token
'auth_method' => 'bearer',
'api_key' => 'your_bearer_token',
Sends: Authorization: Bearer your_bearer_token
Basic Authentication
'auth_method' => 'basic',
'api_key' => 'username',
'api_secret' => 'password',
Sends: Authorization: Basic base64(username:password)
API Key Header
'auth_method' => 'api_key',
'api_key' => 'your_api_key',
Sends: X-API-Key: your_api_key
🧪 Testing
When testing, you can mock the Userhub facade:
use Omgevingshuis\Userhub\Userhub;
// Mock in tests
Userhub::shouldReceive('getUserById')
->with(123)
->andReturn([
'id' => 123,
'name' => 'Test User',
'email' => 'test@example.com'
]);
// Your test code here
$inquiry = Inquiry::factory()->create(['user_id' => 123]);
$user = $inquiry->user();
$this->assertEquals('Test User', $user['name']);
🔗 Related Packages
- Inquiries: Customer inquiries reference
user_idfrom Userhub - Orders: Orders reference
user_idfrom Userhub - Cases: Timeline endpoint aggregates user activities across packages
- Notifications: Can send notifications to users from Userhub
- Notes: Notes can track user information with cached user data