PHPackages                             mcbanks/mcbankslaravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. mcbanks/mcbankslaravel

ActiveProject[Framework](/categories/framework)

mcbanks/mcbankslaravel
======================

Laravel starter with role-based authentication, social login, user profiles, geographical data, and modern UI. Includes Spatie roles, Livewire components, Kenyan administrative data, comprehensive location information, and social authentication.

1.0.3(2mo ago)55MITPHPPHP ^8.2

Since Jan 29Pushed 1mo agoCompare

[ Source](https://github.com/MCBANKSKE/MCBANKSLARAVEL)[ Packagist](https://packagist.org/packages/mcbanks/mcbankslaravel)[ RSS](/packages/mcbanks-mcbankslaravel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (24)Versions (5)Used By (0)

MCBANKS Laravel
===============

[](#mcbanks-laravel)

A Laravel starter template with role-based authentication, Livewire components, and a modern UI. Perfect for building web applications with user management and permission systems.

---

🚀 Features
----------

[](#-features)

- **Laravel 12** - Latest Laravel framework
- **Livewire 4.1** - Dynamic components without writing JavaScript
- **Spatie Laravel Permission** - Role and permission system
- **Role-Based Authentication** - Admin, Host, Guest roles with permissions
- **Email Verification** - Required for secure account access
- **Multi-Step Registration** - Wizard-style form with validation
- **Modern UI** - Tailwind CSS, Glass Morphism, Gradients
- **Password Strength Indicator**
- **Responsive Design**
- **Geographical Data** - Complete countries, states, cities with currencies
- **Kenyan Administrative Data** - All 47 counties with constituencies and wards
- **User Profiles** - Complete profile management system
- **Avatar Upload** - Image processing with thumbnails and cropping
- **Privacy Settings** - Granular privacy controls
- **Profile Completion** - Progress tracking and indicators
- **Social Authentication** - OAuth login with Google, GitHub
- **Account Linking** - Connect multiple social accounts
- **Account Merging** - Smart conflict resolution

### 🔒 Security Features

[](#-security-features)

- **Two-Factor Authentication** - TOTP support with recovery codes
- **Granular Rate Limiting** - Endpoint-specific rate limiting rules
- **User Activity Audit Logging** - Comprehensive security monitoring
- **IP Blacklisting** - Automatic blocking of suspicious IPs
- **Suspicious Activity Detection** - AI-driven anomaly detection
- **Security Event Tracking** - Real-time security monitoring

### 📚 Documentation

[](#-documentation)

- **Comprehensive API Documentation** - Complete REST API reference
- **Developer Setup Guide** - Step-by-step development instructions
- **Production Deployment Guide** - Multiple deployment strategies
- **Security Best Practices** - Enterprise-grade security guidelines

📦 Installation
--------------

[](#-installation)

### Quick Start

[](#quick-start)

```
composer create-project mcbankske/mcbankslaravel my-project
cd my-project
composer run setup
```

The setup script automatically:

- ✅ Installs all PHP dependencies with optimized autoloader
- ✅ Creates `.env` file from example
- ✅ Generates application key
- ✅ Runs database migrations
- ✅ Seeds database with geographical data, profiles, and sample social accounts
- ✅ Installs Node.js dependencies
- ✅ Builds frontend assets

### Manual Setup

[](#manual-setup)

1. **Clone the repository**

```
git clone https://github.com/MCBANKSKE/MCBANKSLARAVEL.git
cd mcbankslaravel
```

2. **Install dependencies**

```
composer install
npm install
```

3. **Environment setup**

```
cp .env.example .env
php artisan key:generate
```

4. **Configure database**

- Edit `.env` with your database credentials

5. **Run migrations**

```
php artisan migrate
```

6. **Build assets**

```
npm run build
```

7. **Start development server**

```
php artisan serve
```

🎯 Quick Setup Script
--------------------

[](#-quick-setup-script)

Use the built-in composer script for automated setup:

```
composer run setup
```

This script will:

- Install PHP dependencies (`composer install`)
- Copy `.env.example` to `.env` if it doesn't exist
- Generate application key (`php artisan key:generate`)
- Run database migrations (`php artisan migrate --force`)
- Install Node.js dependencies (`npm install`)
- Build frontend assets (`npm run build`)

🔧 Development
-------------

[](#-development)

**Development server with all services:**

```
composer run dev
```

This command runs multiple services concurrently:

- **Laravel development server** (PHP artisan serve)
- **Queue worker** (php artisan queue:listen)
- **Log viewer** (php artisan pail)
- **Vite frontend build** (npm run dev)

**Run tests:**

```
composer run test
# or
php artisan test
```

The test command clears configuration cache before running tests for consistent results.

� Geographical Data Included
----------------------------

[](#-geographical-data-included)

This package comes with comprehensive geographical data that's automatically seeded during installation:

### 🌐 International Data

[](#-international-data)

- **Countries** - 250+ countries with complete information:

    - Name, ISO codes (ISO2, ISO3)
    - Capital cities, currencies, currency symbols
    - Phone codes, top-level domains
    - Regions, subregions, timezones
    - Latitude/longitude coordinates
    - Emoji flags and WikiData IDs
- **States/Provinces** - 5,000+ states and provinces worldwide

    - Linked to countries with proper relationships
    - ISO codes, FIPS codes, coordinates
- **Cities** - 150,000+ cities globally

    - Linked to states and countries
    - Geographic coordinates
    - Country and state codes

### 🇰🇪 Kenyan Administrative Data

[](#-kenyan-administrative-data)

- **Counties** - All 47 Kenyan counties

    - Complete county names and relationships
- **Sub-Counties** - Comprehensive administrative structure:

    - **Constituencies** - 290+ constituencies across all counties
    - **Wards** - 1,450+ wards nationwide
    - Proper relationships between counties, constituencies, and wards

### 💰 Currency Information

[](#-currency-information)

- Integrated currency data for all countries
- Currency symbols and codes included
- Perfect for financial applications

### 📊 Database Schema

[](#-database-schema)

```
countries          # 250+ countries with full details
states             # 5,000+ states/provinces
cities             # 150,000+ cities worldwide
counties           # 47 Kenyan counties
sub_counties       # Kenyan constituencies and wards
```

### 🔧 Usage Examples

[](#-usage-examples)

```
// Get all countries
$countries = Country::all();

// Get states for a specific country
$states = State::where('country_id', 1)->get();

// Get cities in a state
$cities = City::where('state_id', 1)->get();

// Get Kenyan counties
$counties = County::all();

// Get constituencies in a county
$constituencies = SubCounty::getUniqueConstituencies(1);

// Get wards in a constituency
$wards = SubCounty::getWardsByConstituency(1, 'changamwe');

// Get all wards in Kenya (filtered, no duplicates)
$allWards = SubCounty::getAllUniqueWards();
```

��️ Authentication System
-------------------------

[](#️-authentication-system)

### Registration (`RegistrationForm`)

[](#registration-registrationform)

- Multi-step wizard
- Optional role selection (default `member`)
- Conditional validation for profile fields
- Role-specific profile creation:

    - Member → `Member` and optionally `MemberAccount`
    - Customer → `Customer` profile
    - Manager → `Manager` profile
    - Admin → only role assignment
- Email verification for members
- Auto-login on successful registration

**Blade integration:**

```

```

---

### Login (`LoginForm`)

[](#login-loginform)

- Email/password login
- Remember me support
- Role-based redirection:

    - Admin → `/admin`
    - Member → `/member` (must verify email)
    - Customer/Manager → `/` (default)
- Error handling and validation

**Blade integration:**

```

```

---

🛠️ Role Setup (Critical)
------------------------

[](#️-role-setup-critical)

### 1. Create Roles Before Registering Users

[](#1-create-roles-before-registering-users)

Use the provided Artisan command to create roles:

```
# Create default roles
php artisan role:create admin
php artisan role:create host
php artisan role:create guest

# Create custom roles
php artisan role:create moderator
php artisan role:create editor
php artisan role:create subscriber
```

**Command Features:**

- **Duplicate Prevention**: Won't create roles that already exist
- **Case Normalization**: Automatically converts to lowercase
- **Error Handling**: Clear success/error messages
- **Validation**: Ensures role name is valid

This uses the `CreateRole` console command in `app/Console/Commands/CreateRole.php`.

### 2. Super Admin Feature

[](#2-super-admin-feature)

- `is_superadmin` boolean field on `users` table
- Overrides role-based permissions (not a Spatie role)
- Can bypass all role restrictions
- Set this field manually in the database or via seeder

### 3. Assign Roles Manually

[](#3-assign-roles-manually)

```
$user = User::find(1);
$user->assignRole('admin'); // Assign admin role
```

### 4. Adding New Roles

[](#4-adding-new-roles)

- Create role via the Artisan command: `php artisan role:create new_role`
- Update `LoginForm.php` redirection logic to handle the new role:

```
if ($user->hasRole('new_role')) {
    return '/new-dashboard';
}
```

### 5. Role-Based Redirection Logic

[](#5-role-based-redirection-logic)

The login system redirects users based on their roles:

- **Admin** → `/admin`
- **Host** → `/host`
- **Guest** → `/guest`
- **Fallback** → `/`

---

🔒 Two-Factor Authentication
---------------------------

[](#-two-factor-authentication)

### Overview

[](#overview)

Enterprise-grade two-factor authentication system using TOTP (Time-based One-Time Password) with comprehensive recovery options.

### Features

[](#features)

#### TOTP Authentication

[](#totp-authentication)

- **Google Authenticator Support** - Compatible with any TOTP app
- **QR Code Setup** - Easy setup with QR code scanning
- **Manual Key Entry** - Backup option for QR code issues
- **Secure Key Generation** - Cryptographically secure secret keys

#### Recovery System

[](#recovery-system)

- **8 Recovery Codes** - Backup codes for account recovery
- **Single-Use Codes** - Each code can only be used once
- **Code Regeneration** - Generate new recovery codes anytime
- **Downloadable Codes** - Export codes for secure storage

#### Security Features

[](#security-features)

- **Rate Limiting** - 5 attempts per 15 minutes
- **Session Management** - Secure 2FA verification tracking
- **Challenge Middleware** - Automatic 2FA verification for protected routes
- **Email Notifications** - Alerts for 2FA enable/disable and recovery code usage

#### User Interface

[](#user-interface)

- **Livewire Components** - Modern reactive UI components
- **Setup Wizard** - Step-by-step 2FA setup process
- **Status Indicators** - Clear 2FA status display
- **Recovery Management** - Track remaining recovery codes

### Configuration

[](#configuration)

#### Environment Variables

[](#environment-variables)

```
# Two-Factor Authentication (optional, defaults work fine)
GOOGLE2FA_SECRET=
GOOGLE2FA_QRCODE_SIZE=200
```

#### Dependencies

[](#dependencies)

```
composer update
# Required packages:
# - pragmarx/google2fa-laravel
# - simplesoftwareio/simple-qrcode
```

### Usage Examples

[](#usage-examples)

#### Enable Two-Factor Authentication

[](#enable-two-factor-authentication)

```
use App\Services\TwoFactorService;

$user = Auth::user();
$twoFactorService = app(TwoFactorService::class);

// Generate secret key and QR code
$secret = $twoFactorService->generateSecretKey($user);
$qrCode = $twoFactorService->generateQrCode($user, $secret);

// Enable 2FA after user verification
$twoFactorService->enable($user, $verificationCode);
```

#### Verify Two-Factor Authentication

[](#verify-two-factor-authentication)

```
// Check if user has 2FA enabled
if ($user->hasTwoFactorEnabled()) {
    // Verify user code
    if ($user->verifyTwoFactorCode($request->code)) {
        // Authentication successful
        $user->twoFactorAuthentication->updateLastUsed();
    }
}
```

#### Disable Two-Factor Authentication

[](#disable-two-factor-authentication)

```
$user->disableTwoFactor();
```

### Blade Integration

[](#blade-integration)

```

```

### Routes

[](#routes)

```
// Two-Factor Authentication
Route::middleware(['auth', 'throttle:5,1'])->group(function () {
    Route::get('/2fa/challenge', [TwoFactorController::class, 'showChallenge'])->name('2fa.challenge');
    Route::post('/2fa/verify', [TwoFactorController::class, 'verify'])->name('2fa.verify');
    Route::get('/2fa/recovery', [TwoFactorController::class, 'showRecoveryForm'])->name('2fa.recovery');
    Route::post('/2fa/recovery/verify', [TwoFactorController::class, 'verifyRecovery'])->name('2fa.recovery.verify');
    Route::post('/2fa/logout', [TwoFactorController::class, 'logout'])->name('2fa.logout');
});
```

### Security Considerations

[](#security-considerations)

- Store recovery codes securely offline
- Enable 2FA on all admin accounts
- Monitor 2FA failed attempts in audit logs
- Regularly regenerate recovery codes

---

⚡ Rate Limiting System
----------------------

[](#-rate-limiting-system)

### Overview

[](#overview-1)

Advanced rate limiting system with endpoint-specific rules, IP blacklisting, and suspicious activity detection.

### Features

[](#features-1)

#### Granular Rate Limits

[](#granular-rate-limits)

- **Authentication Endpoints** - 5 attempts per 15 minutes
- **Registration** - 3 attempts per hour
- **Password Reset** - 3 attempts per hour
- **Two-Factor** - 5 attempts per 15 minutes
- **API Requests** - 1000/hour (authenticated), 100/hour (anonymous)
- **Profile Updates** - 10 attempts per hour
- **Avatar Uploads** - 5 attempts per hour

#### Security Protection

[](#security-protection)

- **IP Blacklisting** - Automatic blocking of malicious IPs
- **Suspicious Activity Detection** - AI-driven anomaly detection
- **Rate Limit Headers** - Standard HTTP rate limit headers
- **User-Based Limits** - Different limits for authenticated vs anonymous users

#### Monitoring & Statistics

[](#monitoring--statistics)

- **Real-time Statistics** - Rate limiting analytics
- **Most Common Violations** - Track frequent abusers
- **IP Activity Tracking** - Monitor IP patterns
- **Performance Optimized** - Redis-based caching for performance

### Configuration

[](#configuration-1)

#### Middleware Registration

[](#middleware-registration)

```
// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \App\Http\Middleware\LogUserActivity::class,
    ],
    'api' => [
        // ... existing middleware
        \App\Http\Middleware\RateLimitApi::class,
    ],
];

protected $middlewareAliases = [
    'rate.limit.auth' => \App\Http\Middleware\RateLimitAuth::class,
    'rate.limit.profile' => \App\Http\Middleware\RateLimitProfile::class,
];
```

#### Environment Variables

[](#environment-variables-1)

```
# Rate Limiting (optional, defaults work fine)
RATE_LIMIT_CACHE_DRIVER=redis
RATE_LIMIT_CACHE_PREFIX=rate_limit:
```

### Usage Examples

[](#usage-examples-1)

#### Check Rate Limits

[](#check-rate-limits)

```
use App\Services\RateLimitingService;

$rateLimiting = app(RateLimitingService::class);

// Check authentication rate limit
if ($rateLimiting->checkAuthRateLimit($request)) {
    abort(429, 'Too many attempts');
}

// Check API rate limit
if ($rateLimiting->checkApiRateLimit($request)) {
    abort(429, 'API rate limit exceeded');
}
```

#### Get Rate Limit Status

[](#get-rate-limit-status)

```
// Get rate limit information for current user
$status = $rateLimiting->getRateLimitStatus($request, 'auth', 5);

// Output rate limit headers
$headers = $rateLimiting->getRateLimitHeaders($request, 'api', 1000, 60);
foreach ($headers as $key => $value) {
    $response->headers->set($key, $value);
}
```

#### IP Blacklisting

[](#ip-blacklisting)

```
// Blacklist an IP address
$rateLimiting->blacklistIp('192.168.1.100', 60); // 60 minutes

// Check if IP is blacklisted
if ($rateLimiting->isIpBlacklisted($request->ip())) {
    abort(429, 'Your IP has been blocked');
}

// Remove IP from blacklist
$rateLimiting->unblacklistIp('192.168.1.100');
```

#### Log Suspicious Activity

[](#log-suspicious-activity)

```
// Log suspicious activity for monitoring
$rateLimiting->logSuspiciousActivity($request, 'multiple_failed_logins');

// Check for suspicious activity patterns
if ($rateLimiting->checkSuspiciousActivityRateLimit($request)) {
    // Take action against suspicious user
}
```

### Rate Limiting Rules

[](#rate-limiting-rules)

#### Authentication Endpoints

[](#authentication-endpoints)

```
// Login attempts
RateLimitAuth: 5 attempts per 15 minutes

// Registration attempts
RateLimitAuth: 3 attempts per hour

// Password reset requests
RateLimitAuth: 3 attempts per hour
```

#### API Endpoints

[](#api-endpoints)

```
// Authenticated users
RateLimitApi: 1000 requests per hour

// Anonymous users
RateLimitApi: 100 requests per hour

// Specific endpoints
RateLimitApi: Custom limits per endpoint
```

#### Profile Management

[](#profile-management)

```
// Profile updates
RateLimitProfile: 10 attempts per hour

// Avatar uploads
RateLimitProfile: 5 attempts per hour

// Profile views (more lenient)
RateLimitProfile: 200 attempts per hour
```

### Response Headers

[](#response-headers)

All rate limited responses include:

- `X-RateLimit-Limit` - Maximum requests allowed
- `X-RateLimit-Remaining` - Requests remaining
- `X-RateLimit-Reset` - Time when limit resets

### Security Benefits

[](#security-benefits)

- **Prevents Brute Force** - Limits login attempts
- **API Protection** - Prevents API abuse
- **Resource Conservation** - Protects server resources
- **DDoS Mitigation** - Helps mitigate denial of service attacks

---

� User Activity Audit Logging
-----------------------------

[](#-user-activity-audit-logging)

### Overview

[](#overview-2)

Comprehensive audit logging system that tracks all user activities, security events, and system changes for compliance and security monitoring.

### Features

[](#features-2)

#### Comprehensive Logging

[](#comprehensive-logging)

- **Authentication Events** - Login, logout, failed attempts
- **Profile Changes** - Profile updates, avatar uploads
- **Two-Factor Events** - 2FA enable/disable, verification attempts
- **Social Authentication** - Social account connections/disconnections
- **Security Events** - Suspicious activities, rate limiting violations
- **API Access** - API requests, errors, unauthorized access

#### Data Tracking

[](#data-tracking)

- **Before/After Values** - Track data changes
- **Metadata Capture** - IP addresses, user agents, request details
- **Model Relationships** - Track changes to specific models
- **Context Information** - Additional context for events

#### Search & Analysis

[](#search--analysis)

- **Advanced Filtering** - Filter by user, action, date range, level
- **Security Event Tracking** - Special handling for security events
- **Anomaly Detection** - Automatic detection of suspicious patterns
- **Export Capabilities** - CSV export for compliance reporting

### Configuration

[](#configuration-2)

#### Database Migration

[](#database-migration)

```
php artisan migrate
# Creates audit_logs table with optimized indexes
```

#### Middleware Registration

[](#middleware-registration-1)

```
// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \App\Http\Middleware\LogUserActivity::class,
    ],
];
```

### Usage Examples

[](#usage-examples-2)

#### Manual Logging

[](#manual-logging)

```
use App\Services\AuditService;
use App\Models\AuditLog;

$auditService = app(AuditService::class);

// Log authentication event
$auditService->logAuth('login', [
    'user_id' => $user->id,
    'ip_address' => $request->ip(),
    'user_agent' => $request->userAgent(),
]);

// Log profile change
$auditService->logProfileChange('profile_updated', $user, $oldValues, $newValues);

// Log security event
$auditService->logSecurity('suspicious_login', 'Multiple failed logins detected', [
    'ip_address' => $request->ip(),
    'attempts' => 5,
], 'warning');
```

#### Query Audit Logs

[](#query-audit-logs)

```
// Get user's audit logs
$logs = $auditService->getUserLogs($user, 50, [
    'start_date' => now()->subDays(30),
    'end_date' => now(),
    'level' => 'warning'
]);

// Get security events
$securityLogs = $auditService->getSecurityLogs(100);

// Get error logs
$errorLogs = $auditService->getErrorLogs(50);
```

#### Model Logging

[](#model-logging)

```
// Using the AuditLog model directly
AuditLog::log([
    'user_id' => auth()->id(),
    'action' => 'profile_updated',
    'description' => 'User updated their profile',
    'old_values' => ['name' => 'Old Name'],
    'new_values' => ['name' => 'New Name'],
    'model_type' => \App\Models\Profile::class,
    'model_id' => $profile->id,
    'level' => 'info',
]);
```

### Audit Log Events

[](#audit-log-events)

#### Authentication Events

[](#authentication-events)

```
// Successful login
AuditLog::logLogin($user, $ipAddress, $userAgent);

// Failed login attempt
AuditLog::logLoginFailed($email, $ipAddress, $userAgent);

// User logout
AuditLog::logLogout($user, $ipAddress, $userAgent);
```

#### Two-Factor Events

[](#two-factor-events)

```
// 2FA enabled
AuditLog::logTwoFactorEnabled($user);

// 2FA disabled
AuditLog::logTwoFactorDisabled($user);

// 2FA verification failed
AuditLog::logTwoFactorFailed($user, $ipAddress);

// Recovery code used
AuditLog::logRecoveryCodeUsed($user, $ipAddress);
```

#### Profile Events

[](#profile-events)

```
// Profile updated
AuditLog::logProfileUpdate($user, $oldValues, $newValues);

// Password reset requested
AuditLog::logPasswordResetRequest($user, $ipAddress);

// Password reset completed
AuditLog::logPasswordResetCompleted($user, $ipAddress);
```

#### Social Authentication Events

[](#social-authentication-events)

```
// Social account connected
AuditLog::logSocialAccountConnected($user, 'google', $ipAddress);

// Social account disconnected
AuditLog::logSocialAccountDisconnected($user, 'github', $ipAddress);
```

### Database Schema

[](#database-schema)

#### Audit Logs Table

[](#audit-logs-table)

```
- id (primary)
- user_id (foreign key, nullable, set null on delete)
- action (string) - Event type (login, profile_updated, etc.)
- description (text, nullable) - Human-readable description
- ip_address (string, nullable) - Client IP address
- user_agent (text, nullable) - Browser user agent
- old_values (json, nullable) - Before values for changes
- new_values (json, nullable) - After values for changes
- model_type (string, nullable) - Related model type
- model_id (unsigned big integer, nullable) - Related model ID
- level (string, default 'info') - info, warning, error, critical
- metadata (json, nullable) - Additional context
- created_at (timestamp) - Event timestamp
```

### Advanced Features

[](#advanced-features)

#### Statistics & Analytics

[](#statistics--analytics)

```
// Get audit statistics
$stats = $auditService->getStatistics();

// Returns:
// - total_logs, last_24_hours, last_7_days, last_30_days
// - security_events, error_events, unique_users
// - top_actions, top_ips, activity_by_level
```

#### Suspicious Activity Detection

[](#suspicious-activity-detection)

```
// Detect suspicious patterns
$patterns = $auditService->getSuspiciousActivity();

// Returns:
// - multiple_failed_logins (same IP, many attempts)
// - rapid_profile_updates (same user, many changes)
// - unusual_ip_activity (user from many IPs)
```

#### Security Anomaly Detection

[](#security-anomaly-detection)

```
// Check for security anomalies
$anomalies = $auditService->checkSecurityAnomalies();

// Returns:
// - concurrent_logins (same user, different IPs)
// - excessive_password_resets (same IP, many requests)
```

#### Export & Compliance

[](#export--compliance)

```
// Export audit logs to CSV
$csv = $auditService->exportToCSV([
    'start_date' => now()->subDays(30),
    'end_date' => now(),
    'user_id' => $userId,
]);

// Cleanup old logs (automatic retention)
$deleted = $auditService->cleanupOldLogs(90); // Keep 90 days
```

### Performance Considerations

[](#performance-considerations)

#### Database Indexes

[](#database-indexes)

- `user_id, created_at` - User activity queries
- `action, created_at` - Action-based queries
- `model_type, model_id` - Model relationship queries
- `ip_address` - IP-based queries
- `level, created_at` - Security event queries

#### Caching Strategy

[](#caching-strategy)

- Statistics cached for 5 minutes
- Rate limit counters use Redis
- Automatic cache invalidation on new logs

#### Data Retention

[](#data-retention)

- Automatic cleanup of old logs (default 90 days)
- Configurable retention period
- Efficient bulk deletion operations

### Compliance & Security

[](#compliance--security)

#### GDPR Compliance

[](#gdpr-compliance)

- User activity tracking for audit purposes
- Data export capabilities for user requests
- Configurable data retention policies

#### Security Monitoring

[](#security-monitoring)

- Real-time security event tracking
- Automatic anomaly detection
- Integration with rate limiting system
- Alert system for critical events

#### Privacy Protection

[](#privacy-protection)

- Sensitive data filtering in logs
- User consent tracking
- Data minimization principles

---

### Overview

[](#overview-3)

The package includes a complete user profile management system with avatar uploads, privacy controls, and profile completion tracking.

### Features

[](#features-3)

#### Profile Management (`ProfileEditor`)

[](#profile-management-profileeditor)

- **Bio** - Rich text biography (500 chars max)
- **Contact Information** - Phone number and website
- **Location** - Country, state, city, and address using geographical data
- **Privacy Settings** - Granular controls for profile visibility
- **Profile Completion** - Real-time progress tracking

#### Avatar System (`AvatarUpload`)

[](#avatar-system-avatarupload)

- **Image Processing** - Automatic cropping and resizing to squares
- **Multiple Sizes** - 300x300 avatar + 100x100 thumbnail
- **File Validation** - Support for JPG, PNG, GIF, WebP (max 5MB)
- **Storage Management** - Organized file storage with automatic cleanup

#### Privacy Controls

[](#privacy-controls)

- **Profile Visibility** - Public/private profile toggle
- **Field Visibility** - Control which fields appear publicly
- **Message Settings** - Allow/disallow user messages
- **Email Privacy** - Hide/show email address

### Usage Examples

[](#usage-examples-3)

#### Accessing Profile Data

[](#accessing-profile-data)

```
// Get user profile
$user = Auth::user();
$profile = $user->profile ?? $user->getOrCreateProfile();

// Check profile completion
if ($user->hasCompleteProfile()) {
    // User has 80%+ complete profile
}

// Get avatar URL
$avatarUrl = $user->avatar_url;
$thumbnailUrl = $user->thumbnail_url;
```

#### Profile Completion Tracking

[](#profile-completion-tracking)

```
// Calculate completion percentage
$percentage = $profile->calculateCompletionPercentage();

// Update completion percentage
$profile->updateCompletionPercentage();

// Get completion status message
$message = $profile->completion_percentage < 50
    ? 'Profile needs more information'
    : 'Looking good!';
```

#### Privacy Settings

[](#privacy-settings)

```
// Check if user can view another profile
if (auth()->user()->canViewProfile($targetUser)) {
    // Show profile
}

// Get privacy settings
$privacy = $profile->privacy_settings;
$showPhone = $privacy['show_phone'] ?? true;
```

### Blade Integration

[](#blade-integration-1)

#### Profile Editor

[](#profile-editor)

```

```

#### Avatar Upload

[](#avatar-upload)

```

```

#### Display User Avatar

[](#display-user-avatar)

```

```

### Routes

[](#routes-1)

#### Profile Management

[](#profile-management-1)

- `GET /profile` - View own profile
- `GET /profile/edit` - Edit profile form
- `GET /users/{user}` - View public profile (if allowed)

#### API Endpoints

[](#api-endpoints-1)

- `GET /api/profile/states/{country}` - Get states for country
- `GET /api/profile/cities/{state}` - Get cities for state

### Database Schema

[](#database-schema-1)

#### Profiles Table

[](#profiles-table)

```
- id (primary)
- user_id (foreign key, unique)
- bio (text, nullable)
- phone (string, nullable)
- website (string, nullable)
- country_id (foreign key, nullable)
- state_id (foreign key, nullable)
- city_id (foreign key, nullable)
- address (string, nullable)
- privacy_settings (json, nullable)
- completion_percentage (integer, default 0)
- timestamps
```

#### Avatars Table

[](#avatars-table)

```
- id (primary)
- profile_id (foreign key, unique)
- original_name (string)
- file_path (string)
- file_name (string)
- mime_type (string)
- file_size (integer)
- width (integer)
- height (integer)
- disk (string, default 'public')
- timestamps
```

### File Storage

[](#file-storage)

- **Avatars**: `storage/app/public/avatars/`
- **Thumbnails**: `storage/app/public/avatars/thumbnails/`
- **Public URL**: `/storage/avatars/`

### Image Processing

[](#image-processing)

- **Automatic Cropping** - Centers and crops to square format
- **Resizing** - 300x300 for avatars, 100x100 for thumbnails
- **Quality** - JPEG compression at 90% quality
- **Formats** - Converts all uploads to JPEG for consistency

---

� Social Authentication System
------------------------------

[](#-social-authentication-system)

### Overview

[](#overview-4)

The package includes a comprehensive social authentication system using Laravel Socialite, supporting OAuth login with Google, GitHub, and Twitter. Features include account linking, smart conflict resolution, and seamless integration with the existing user profile system.

### Supported Providers

[](#supported-providers)

- **Google** - Google OAuth 2.0 authentication
- **GitHub** - GitHub OAuth authentication
- **Twitter** - Twitter OAuth 2.0 authentication

### Features

[](#features-4)

#### Social Login (`SocialLogin`)

[](#social-login-sociallogin)

- **Multiple Providers** - Support for Google, GitHub, Twitter
- **Account Creation** - Automatic user creation from social data
- **Account Linking** - Link social accounts to existing users
- **Smart Merging** - Intelligent conflict resolution
- **Token Management** - OAuth token storage and refresh

#### Account Management (`SocialAccountManager`)

[](#account-management-socialaccountmanager)

- **Connected Accounts** - View all linked social accounts
- **Account Status** - Token validity and connection status
- **Disconnect Accounts** - Safe removal with validation
- **Security Controls** - Prevent locking out users

#### Account Linking System

[](#account-linking-system)

- **Email Matching** - Automatic linking for matching emails
- **Manual Linking** - Users can manually link accounts
- **Conflict Prevention** - Prevent duplicate account linking
- **Profile Integration** - Sync social data with user profiles

### Configuration

[](#configuration-3)

#### Environment Variables

[](#environment-variables-2)

Add these to your `.env` file:

```
# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI="${APP_URL}/auth/google/callback"

# GitHub OAuth
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URI="${APP_URL}/auth/github/callback"

# Twitter OAuth
TWITTER_CLIENT_ID=your_twitter_client_id
TWITTER_CLIENT_SECRET=your_twitter_client_secret
TWITTER_REDIRECT_URI="${APP_URL}/auth/twitter/callback"
```

#### OAuth App Setup

[](#oauth-app-setup)

**Google:**

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create new project or select existing
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI

**GitHub:**

1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Create new OAuth App
3. Set authorization callback URL
4. Copy Client ID and Secret

**Twitter:**

1. Go to [Twitter Developer Portal](https://developer.twitter.com/)
2. Create new project and app
3. Enable OAuth 2.0
4. Set callback URL
5. Generate Client ID and Secret

### Usage Examples

[](#usage-examples-4)

#### Social Login Button

[](#social-login-button)

```

```

#### Account Management

[](#account-management)

```

```

#### Programmatic Social Login

[](#programmatic-social-login)

```
use App\Services\SocialAuthService;

// Handle social login
$socialUser = Socialite::driver('google')->user();
$user = $socialAuthService->handleSocialLogin('google', $socialUser);

// Check user social accounts
if ($user->hasSocialAccount('google')) {
    $googleAccount = $user->getSocialAccount('google');
}

// Disconnect social account
$socialAuthService->disconnectSocialAccount($user, 'google');
```

#### Social Account Data

[](#social-account-data)

```
// Get connected providers
$providers = $user->connected_providers; // ['google', 'github']

// Check token validity
$socialAccount = $user->getSocialAccount('google');
if ($socialAccount->hasValidToken()) {
    // Token is valid
}

// Get provider-specific data
$avatar = $socialAccount->avatar_url;
$nickname = $socialAccount->nickname;
```

### Routes

[](#routes-2)

#### Authentication Routes

[](#authentication-routes)

- `GET /auth/{provider}` - Redirect to OAuth provider
- `GET /auth/{provider}/callback` - Handle OAuth callback
- `POST /auth/{provider}/disconnect` - Disconnect social account
- `GET /auth/{provider}/link` - Link social account to existing user
- `GET /auth/{provider}/link/callback` - Handle linking callback
- `GET /api/social/providers` - Get available providers

### Database Schema

[](#database-schema-2)

#### Social Accounts Table

[](#social-accounts-table)

```
- id (primary)
- user_id (foreign key, cascade delete)
- provider (string) - google, github, twitter
- provider_id (string, unique) - Provider's user ID
- provider_token (string, nullable) - OAuth access token
- provider_refresh_token (string, nullable) - OAuth refresh token
- provider_expires_in (integer, nullable) - Token expiration timestamp
- provider_data (json, nullable) - Raw provider data
- nickname (string, nullable) - Provider username
- name (string, nullable) - Full name from provider
- email (string, nullable) - Email from provider
- avatar (string, nullable) - Avatar URL from provider
- timestamps
```

### Security Features

[](#security-features-1)

#### Token Management

[](#token-management)

- **Secure Storage** - Tokens encrypted in database
- **Expiration Handling** - Automatic token refresh
- **Revocation** - Safe token invalidation
- **Scope Limitation** - Minimal required permissions

#### Account Protection

[](#account-protection)

- **Conflict Resolution** - Smart email matching
- **Duplicate Prevention** - Multiple account safeguards
- **Disconnect Validation** - Prevent account lockout
- **Privacy Controls** - Granular data sharing settings

#### Session Security

[](#session-security)

- **State Verification** - CSRF protection
- **Redirect Validation** - Safe URL redirection
- **Session Binding** - Secure session handling
- **Rate Limiting** - Prevent abuse

### Integration with User Profiles

[](#integration-with-user-profiles)

#### Profile Sync

[](#profile-sync)

- **Avatar Import** - Import social avatars
- **Name Sync** - Sync display names
- **Bio Updates** - Update profile bio with social data
- **Location Data** - Import location information

#### Privacy Integration

[](#privacy-integration)

- **Field Visibility** - Respect privacy settings
- **Public Profiles** - Social account display options
- **Data Control** - User control over shared data

### Error Handling

[](#error-handling)

#### Common Scenarios

[](#common-scenarios)

- **Provider Errors** - Graceful OAuth failure handling
- **Network Issues** - Retry mechanisms
- **Invalid Tokens** - Automatic token refresh
- **Account Conflicts** - User-friendly resolution

#### User Feedback

[](#user-feedback)

- **Clear Messages** - Informative error messages
- **Recovery Options** - Alternative login methods
- **Status Indicators** - Connection status display
- **Help Links** - Support documentation

---

� Available Commands
--------------------

[](#-available-commands)

### Composer Scripts

[](#composer-scripts)

- `composer run setup` - Complete project setup with optimized dependencies and database seeding
- `composer run dev` - Development server with all services
- `composer run test` - Run test suite

### Artisan Commands

[](#artisan-commands)

- `php artisan role:create {name}` - Create a new role with validation and duplicate prevention
- `php artisan serve` - Start development server
- `php artisan migrate` - Run database migrations
- `php artisan db:seed` - Seed database with sample data
- `php artisan queue:work` - Start queue worker
- `php artisan pail` - View real-time logs

#### Role Creation Examples

[](#role-creation-examples)

```
# Create standard roles
php artisan role:create admin
php artisan role:create member
php artisan role:create customer
php artisan role:create manager

# Create custom roles
php artisan role:create moderator
php artisan role:create editor
php artisan role:create subscriber
```

### Database Seeding

[](#database-seeding)

The project includes comprehensive data seeders:

- **Geographical Data**:
    - `CountriesTableSeeder` - 250+ countries
    - `StatesTableSeeder` - 5,000+ states/provinces
    - `CitiesTableChunk*Seeder` - 150,000+ cities (split into 5 chunks)
    - `CountySeeder` - Kenyan counties
    - `SubCountySeeder` - Kenyan constituencies and wards
- **User Data**:
    - `ProfileSeeder` - Creates profiles for existing users with sample data
    - `SocialAccountSeeder` - Adds sample social accounts for testing OAuth functionality

Run individual seeders:

```
php artisan db:seed --class=ProfileSeeder
php artisan db:seed --class=SocialAccountSeeder
```

---

🎨 UI Components
---------------

[](#-ui-components)

### Auth Layout

[](#auth-layout)

- Modern gradient background
- Glass morphism effects
- Smooth animations (GSAP)
- Password strength indicator
- Focus states and transitions
- Loading states

### Form Features

[](#form-features)

- Real-time validation
- Password toggle visibility
- Strength indicator
- Animated transitions
- Mobile responsive

📁 Project Structure
-------------------

[](#-project-structure)

```
app/
├── Console/Commands/         # CreateRole.php - Role creation command
├── Http/
│   ├── Controllers/
│   │   ├── Auth/           # Login, Register, Password controllers
│   │   ├── SocialAuthController.php # Social authentication
│   │   └── Controller.php  # Base controller
│   ├── Kernel.php          # HTTP middleware
│   └── Middleware/         # Custom middleware
├── Livewire/
│   ├── Auth/               # RegistrationForm.php, LoginForm.php
│   │   ├── SocialLogin.php      # Social login component
│   │   └── SocialAccountManager.php # Account management
│   └── Profile/            # ProfileEditor.php, AvatarUpload.php
├── Models/
│   ├── User.php            # User model with roles and social relationships
│   ├── Country.php         # Country model
│   ├── State.php           # State/Province model
│   ├── City.php            # City model
│   ├── County.php          # Kenyan county model
│   ├── SubCounty.php       # Kenyan sub-county model
│   ├── Profile.php         # User profile model
│   ├── Avatar.php          # Avatar model with image processing
│   └── SocialAccount.php   # Social account model
├── Notifications/          # Email notifications
├── Providers/              # Service providers
└── Services/
    ├── EmailService.php    # Email handling service
    ├── AvatarUploadService.php # Image processing and upload service
    └── SocialAuthService.php # OAuth authentication service
database/
├── factories/              # Model factories
├── migrations/             # Database migrations
└── seeders/               # Data seeders (geographical data + ProfileSeeder + SocialAccountSeeder)
resources/
├── views/
│   ├── layouts/
│   │   ├── auth.blade.php
│   │   └── app.blade.php   # Profile layout
│   ├── livewire/
│   │   ├── auth/
│   │   │   ├── social-login.blade.php
│   │   │   └── social-account-manager.blade.php
│   │   └── profile/        # Profile component views
│   ├── profile/            # Profile pages (show, edit, public)
│   ├── auth/
│   ├── components/
│   ├── emails/
│   └── welcome.blade.php
├── css/                   # Tailwind CSS
└── js/                    # JavaScript assets
public/
├── images/                # Default avatar and other assets
└── storage/               # Public file storage (avatars)
routes/
├── web.php                # Web routes (includes profile and social routes)
├── api.php                # API routes
└── console.php            # Console routes
composer.json
package.json
vite.config.js

```

�️ Security
-----------

[](#️-security)

- Email verification for members
- Password strength validation
- Role-based access
- CSRF protection
- Bcrypt password hashing

📚 Customization
---------------

[](#-customization)

### Registration Fields

[](#registration-fields)

- Modify `RegistrationForm.php` to add/remove fields:

```
// Add new field
public $new_field = '';
// Add validation
protected $rules['new_field'] = ['required', 'string'];
// Handle field in registration
$user->update(['new_field' => $validated['new_field']]);
```

### Login Redirects

[](#login-redirects)

- Update `LoginForm.php` for new roles:

```
if ($user->hasRole('new_role')) {
    return '/new-route';
}
```

### UI Styling

[](#ui-styling)

Update `resources/views/layouts/auth.blade.php`:

```
.gradient-bg {
    background: linear-gradient(135deg, #color1 0%, #color2 100%);
}
```

🔄 Available Routes
------------------

[](#-available-routes)

### Authentication Routes

[](#authentication-routes-1)

**Guest Routes (middleware: guest)**

- `GET /register` → registration form
- `POST /register` → registration submission
- `GET /login` → login form
- `POST /login` → login submission
- `GET /forgot-password` → password reset request form
- `POST /forgot-password` → send password reset link
- `GET /reset-password/{token}` → password reset form
- `POST /reset-password` → password reset submission

**Authenticated Routes**

- `POST /logout` → logout

### Email Verification Routes (middleware: auth)

[](#email-verification-routes-middleware-auth)

- `GET /email/verify` → verification notice page
- `GET /email/verify/{id}/{hash}` → verify email (signed)
- `POST /email/verification-notification` → resend verification link (throttled)

### General Routes

[](#general-routes)

- `GET /` → welcome page

### Route Implementation Details

[](#route-implementation-details)

- Uses controller-based routing with `Route::controller()`
- Email verification includes welcome email functionality
- Password reset uses Laravel's built-in functionality
- All auth routes are properly grouped by middleware

🛠️ Dependencies
---------------

[](#️-dependencies)

- **PHP &gt;= 8.2** - Core requirement
- **Laravel ^12.0** - Framework
- **Livewire ^4.1** - Dynamic components
- **Spatie Laravel Permission ^6.24** - Role/permission system
- **Laravel Socialite ^5.24** - OAuth authentication
- **Tailwind CSS ^4.0** - Styling framework
- **Vite ^7.0.7** - Asset bundling
- **Node.js &amp; NPM** - Frontend build tools
- **Intervention Image ^3.8** - Image processing for avatars

### Security &amp; Authentication Dependencies

[](#security--authentication-dependencies)

- **PragmaRX Google2FA ^2.0** - Two-factor authentication
- **Simple QrCode ^4.2** - QR code generation for 2FA

### Development Dependencies

[](#development-dependencies)

- **Laravel Pint ^1.24** - Code style
- **Laravel Sail ^1.41** - Docker environment
- **PHPUnit ^11.5.3** - Testing framework
- **Faker ^1.23** - Test data generation
- **Concurrently ^9.0.1** - Parallel process running

📝 Environment Variables
-----------------------

[](#-environment-variables)

Key environment variables in `.env`:

```
APP_NAME="MCBANKS LARAVEL"
APP_URL=http://localhost

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mcbankslaravel
DB_USERNAME=root
DB_PASSWORD=

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
_USERNAME=null
MAIL_PASSWORD=null
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"

# Queue Configuration
QUEUE_CONNECTION=database

# Cache Configuration
CACHE_DRIVER=file
```

### Email Configuration

[](#email-configuration)

The project includes an `EmailService` for handling welcome emails and notifications. Configure your mail settings in the `.env` file for email verification to work properly.

🚀 Deployment
------------

[](#-deployment)

1. Copy environment:

```
cp .env.example .env
php artisan key:generate
php artisan config:cache
```

2. Migrate database:

```
php artisan migrate --force
```

3. Optimize assets:

```
npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

4. Start queue (if needed):

```
php artisan queue:work
```

🤝 Contributing
--------------

[](#-contributing)

1. Fork the repository
2. Create a feature branch
3. Commit changes
4. Push
5. Open PR

📄 License
---------

[](#-license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

🆘 Support
---------

[](#-support)

If you encounter any issues:

1. Check the [documentation](https://laravel.com/docs)
2. Search existing [issues](https://github.com/MCBANKSKE/MCBANKSLARAVEL/issues)
3. Create a new issue with detailed information

🔄 Version History
-----------------

[](#-version-history)

- **v1.3.0** - **SECURITY &amp; DOCUMENTATION UPDATE** - Added comprehensive security features including Two-Factor Authentication, Granular Rate Limiting, User Activity Audit Logging, complete API documentation, developer setup guide, and production deployment guide
- **v1.2.0** - Added comprehensive Social Authentication system with OAuth login, account linking, and smart conflict resolution
- **v1.1.0** - Added comprehensive User Profiles system with avatar uploads, privacy settings, and profile completion tracking
- **v1.0.2** - Added comprehensive geographical data and enhanced SubCounty model with advanced query methods
- **v1.0.1** - Updated documentation and GitHub repository links
- **v1.0.0** - Initial release with Laravel 12, Livewire 4.1, Spatie Permission

📊 Project Statistics
--------------------

[](#-project-statistics)

- **Models**: 11 (User, Profile, Avatar, SocialAccount, TwoFactorAuthentication, AuditLog, Country, State, City, County, SubCounty)
- **Livewire Components**: 7 (RegistrationForm, LoginForm, ProfileEditor, AvatarUpload, SocialLogin, SocialAccountManager, TwoFactorAuthentication)
- **Console Commands**: 1 (CreateRole)
- **Services**: 6 (EmailService, AvatarUploadService, SocialAuthService, TwoFactorService, RateLimitingService, AuditService)
- **Controllers**: Multiple auth controllers including SocialAuthController, TwoFactorController
- **Database Seeders**: 11 (including 5 chunks for cities data + ProfileSeeder + SocialAccountSeeder)
- **Migration Files**: 14 (including profiles, avatars, social accounts, two-factor auth, audit logs tables)
- **Middleware**: 6 (LogUserActivity, RateLimitAuth, RateLimitApi, RateLimitProfile, TwoFactorChallenge)
- **Notifications**: 3 (TwoFactorEnabled, TwoFactorDisabled, RecoveryCodeUsed)

📚 Documentation Files
---------------------

[](#-documentation-files)

- `docs/API.md` - Complete REST API documentation with endpoints, examples, and SDK implementations
- `docs/DEVELOPER.md` - Comprehensive developer setup guide with IDE configuration and best practices
- `docs/DEPLOYMENT.md` - Production deployment guide with multiple strategies and security hardening
- `docs/IMPROVEMENTS.md` - Summary of all security enhancements and new features

🔍 Key Features Deep Dive
------------------------

[](#-key-features-deep-dive)

### Social Authentication System

[](#social-authentication-system)

The social authentication system provides complete OAuth integration:

- **Multi-Provider Support** - Google, GitHub, Twitter OAuth login
- **Account Linking** - Connect multiple social accounts to one user
- **Smart Conflict Resolution** - Automatic email matching and duplicate prevention
- **Token Management** - Secure OAuth token storage and refresh
- **Security Controls** - CSRF protection, rate limiting, and safe disconnection

### User Profiles System

[](#user-profiles-system)

The profiles system provides a complete user experience with:

- **Profile Management** - Edit bio, contact info, location with geographical data integration
- **Avatar System** - Upload, crop, resize images with automatic thumbnail generation
- **Privacy Controls** - Granular settings for profile visibility and data sharing
- **Completion Tracking** - Real-time progress indicator to encourage profile completion

### SubCounty Model Advanced Features

[](#subcounty-model-advanced-features)

The `SubCounty` model includes specialized query methods for Kenyan administrative data:

- `getUniqueConstituencies($countyId)` - Get constituencies for a specific county
- `getUniqueWards($countyId)` - Get all wards in a county
- `getWardsByConstituency($countyId, $constituencyName)` - Get wards in a specific constituency
- `getAllUniqueConstituencies()` - Get all constituencies nationwide
- `getAllUniqueWards()` - Get all wards nationwide
- `getByCounty($countyId)` - Get sub-counties with county relationship

### Email Service Integration

[](#email-service-integration)

The project includes a dedicated `EmailService` that handles:

- Welcome emails after successful email verification
- Email notification dispatching
- Centralized email template management

### Avatar Upload Service

[](#avatar-upload-service)

The `AvatarUploadService` provides:

- Image processing with Intervention Image
- Automatic square cropping and resizing
- Multiple size generation (avatar + thumbnail)
- File validation and storage management
- Cleanup and organization of uploaded files

### Social Auth Service

[](#social-auth-service)

The `SocialAuthService` handles:

- OAuth authentication flow management
- Account creation and linking
- Token storage and refresh
- Conflict resolution and error handling
- Provider configuration validation

### Security Features

[](#security-features-2)

- Role-based access control using Spatie Laravel Permission
- Super admin override capability
- Email verification for secure account access
- Password strength validation
- CSRF protection
- Bcrypt password hashing
- Profile privacy controls
- File upload validation and processing
- OAuth token security and management
- Social account conflict prevention
- Session security and rate limiting
- **Two-Factor Authentication** - TOTP support with recovery codes
- **Granular Rate Limiting** - Endpoint-specific rate limiting with IP blacklisting
- **User Activity Audit Logging** - Comprehensive security monitoring and compliance
- **Suspicious Activity Detection** - AI-driven anomaly detection and alerting
- **Security Event Tracking** - Real-time monitoring of security events
- **IP Blacklisting** - Automatic blocking of malicious IP addresses
- **Advanced Threat Protection** - Multi-layered security architecture

### Enterprise Security Features

[](#enterprise-security-features)

- **Multi-Factor Authentication** - TOTP with QR code setup and recovery codes
- **Advanced Rate Limiting** - Configurable limits per endpoint with Redis caching
- **Comprehensive Audit Trails** - Complete user activity logging for compliance
- **Anomaly Detection** - Automatic detection of suspicious patterns and behaviors
- **Security Analytics** - Real-time statistics and security monitoring
- **Compliance Support** - GDPR-compliant data handling and export capabilities
- **Performance Optimized** - Efficient caching and database indexing for security systems

---

🚀 Quick Security Setup
----------------------

[](#-quick-security-setup)

### Enable Two-Factor Authentication

[](#enable-two-factor-authentication-1)

```
# Install required packages
composer update

# Run migrations
php artisan migrate

# Add middleware to app/Http/Kernel.php
'2fa.challenge' => \App\Http\Middleware\TwoFactorChallenge::class,
```

### Configure Rate Limiting

[](#configure-rate-limiting)

```
# Add rate limiting middleware
'rate.limit.auth' => \App\Http\Middleware\RateLimitAuth::class,
'rate.limit.api' => \App\Http\Middleware\RateLimitApi::class,
'rate.limit.profile' => \App\Http\Middleware\RateLimitProfile::class,
```

### Enable Audit Logging

[](#enable-audit-logging)

```
# Add activity logging middleware
\App\Http\Middleware\LogUserActivity::class,
```

### Security Best Practices

[](#security-best-practices)

1. **Enable 2FA** on all admin accounts
2. **Monitor audit logs** regularly for suspicious activity
3. **Configure rate limits** appropriately for your use case
4. **Set up alerts** for security events
5. **Regular cleanup** of old audit logs (90 days default)
6. **Review security statistics** and analytics weekly

---

**Built with ❤️ using [Laravel](https://laravel.com)**

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance89

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Total

4

Last Release

66d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ea7dacc975a176e4ac4cca9af3d21a703c7a7511b8fd4b18110d8c4098f5880c?d=identicon)[mcbankske](/maintainers/mcbankske)

---

Top Contributors

[![MCBANKSKE](https://avatars.githubusercontent.com/u/154880732?v=4)](https://github.com/MCBANKSKE "MCBANKSKE (23 commits)")

---

Tags

frameworklaravelAuthenticationscaffoldcountriesoauthlivewirerolespermissionssocialprofilesgeographicalstatesstarterkenyacities

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/mcbanks-mcbankslaravel/health.svg)

```
[![Health](https://phpackages.com/badges/mcbanks-mcbankslaravel/health.svg)](https://phpackages.com/packages/mcbanks-mcbankslaravel)
```

###  Alternatives

[bagisto/bagisto

Bagisto Laravel E-Commerce

26.2k161.6k7](/packages/bagisto-bagisto)[nasirkhan/laravel-starter

A CMS like modular Laravel starter project.

1.4k2.7k](/packages/nasirkhan-laravel-starter)[unopim/unopim

UnoPim Laravel PIM

9.4k1.8k](/packages/unopim-unopim)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)