| Install | |
|---|---|
composer require mcbanks/mcbankslaravel |
|
| Latest Version: | 1.0.3 |
| PHP: | ^8.2 |
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.
composer create-project mcbankske/mcbankslaravel my-project
cd my-project
composer run setup
The setup script automatically:
.env file from examplegit clone https://github.com/MCBANKSKE/MCBANKSLARAVEL.git
cd mcbankslaravel
composer install
npm install
cp .env.example .env
php artisan key:generate
.env with your database credentialsphp artisan migrate
npm run build
php artisan serve
Use the built-in composer script for automated setup:
composer run setup
This script will:
composer install).env.example to .env if it doesn't existphp artisan key:generate)php artisan migrate --force)npm install)npm run build)Development server with all services:
composer run dev
This command runs multiple services concurrently:
Run tests:
composer run test
# or
php artisan test
The test command clears configuration cache before running tests for consistent results.
This package comes with comprehensive geographical data that's automatically seeded during installation:
Countries - 250+ countries with complete information:
States/Provinces - 5,000+ states and provinces worldwide
Cities - 150,000+ cities globally
Counties - All 47 Kenyan counties
Sub-Counties - Comprehensive administrative structure:
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
// 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();
RegistrationForm)Multi-step wizard
Optional role selection (default member)
Conditional validation for profile fields
Role-specific profile creation:
Member and optionally MemberAccountCustomer profileManager profileEmail verification for members
Auto-login on successful registration
Blade integration:
<livewire:auth.registration-form />
LoginForm)Email/password login
Remember me support
Role-based redirection:
/admin/member (must verify email)/ (default)Error handling and validation
Blade integration:
<livewire:auth.login-form />
Use the provided Artisan command to create roles:
# Create default 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
Command Features:
This uses the CreateRole console command in app/Console/Commands/CreateRole.php.
is_superadmin boolean field on users table$user = User::find(1);
$user->assignRole('admin'); // Assign admin role
php artisan role:create new_roleLoginForm.php redirection logic to handle the new role:if ($user->hasRole('new_role')) {
return '/new-dashboard';
}
The login system redirects users based on their roles:
/admin/member (requires verified email)///The package includes a complete user profile management system with avatar uploads, privacy controls, and profile completion tracking.
ProfileEditor)AvatarUpload)// 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;
// 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!';
// 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;
<livewire:profile.profile-editor />
<livewire:profile.avatar-upload />
<img src="{{ $user->thumbnail_url }}" alt="{{ $user->display_name }}" />
GET /profile - View own profileGET /profile/edit - Edit profile formGET /users/{user} - View public profile (if allowed)GET /api/profile/states/{country} - Get states for countryGET /api/profile/cities/{state} - Get cities for state- 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
- 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
storage/app/public/avatars/storage/app/public/avatars/thumbnails//storage/avatars/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.
SocialLogin)SocialAccountManager)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"
Google:
GitHub:
Twitter:
<!-- In login form -->
<livewire:auth.social-login :show-divider="true" />
<!-- Compact version -->
<livewire:auth.social-login :show-compact="true" />
<!-- Icons only -->
<livewire:auth.social-login :show-icons-only="true" />
<!-- In profile edit page -->
<livewire:auth.social-account-manager />
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');
// 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;
GET /auth/{provider} - Redirect to OAuth providerGET /auth/{provider}/callback - Handle OAuth callbackPOST /auth/{provider}/disconnect - Disconnect social accountGET /auth/{provider}/link - Link social account to existing userGET /auth/{provider}/link/callback - Handle linking callbackGET /api/social/providers - Get available providers- 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
composer run setup - Complete project setup with optimized dependencies and database seedingcomposer run dev - Development server with all servicescomposer run test - Run test suitephp artisan role:create {name} - Create a new role with validation and duplicate preventionphp artisan serve - Start development serverphp artisan migrate - Run database migrationsphp artisan db:seed - Seed database with sample dataphp artisan queue:work - Start queue workerphp artisan pail - View real-time logs# 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
The project includes comprehensive data seeders:
CountriesTableSeeder - 250+ countriesStatesTableSeeder - 5,000+ states/provincesCitiesTableChunk*Seeder - 150,000+ cities (split into 5 chunks)CountySeeder - Kenyan countiesSubCountySeeder - Kenyan constituencies and wardsProfileSeeder - Creates profiles for existing users with sample dataSocialAccountSeeder - Adds sample social accounts for testing OAuth functionalityRun individual seeders:
php artisan db:seed --class=ProfileSeeder
php artisan db:seed --class=SocialAccountSeeder
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
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']]);
LoginForm.php for new roles:if ($user->hasRole('new_role')) {
return '/new-route';
}
Update resources/views/layouts/auth.blade.php:
.gradient-bg {
background: linear-gradient(135deg, #color1 0%, #color2 100%);
}
Guest Routes (middleware: guest)
GET /register → registration formPOST /register → registration submissionGET /login → login formPOST /login → login submissionGET /forgot-password → password reset request formPOST /forgot-password → send password reset linkGET /reset-password/{token} → password reset formPOST /reset-password → password reset submissionAuthenticated Routes
POST /logout → logoutGET /email/verify → verification notice pageGET /email/verify/{id}/{hash} → verify email (signed)POST /email/verification-notification → resend verification link (throttled)GET / → welcome pageRoute::controller()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
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.
cp .env.example .env
php artisan key:generate
php artisan config:cache
php artisan migrate --force
npm run build
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan queue:work
This project is licensed under the MIT License - see the LICENSE file for details.
If you encounter any issues:
The social authentication system provides complete OAuth integration:
The profiles system provides a complete user experience with:
The SubCounty model includes specialized query methods for Kenyan administrative data:
getUniqueConstituencies($countyId) - Get constituencies for a specific countygetUniqueWards($countyId) - Get all wards in a countygetWardsByConstituency($countyId, $constituencyName) - Get wards in a specific constituencygetAllUniqueConstituencies() - Get all constituencies nationwidegetAllUniqueWards() - Get all wards nationwidegetByCounty($countyId) - Get sub-counties with county relationshipThe project includes a dedicated EmailService that handles:
The AvatarUploadService provides:
The SocialAuthService handles:
Built with ❤️ using Laravel