README

A comprehensive Laravel 12 starter kit with Livewire, UUID-based models, authentication, monitoring, and development tools.

🚀 Features

Frontend

Livewire - Server-side components with single-file components
Pre-installed and ready to use

Backend Infrastructure

Models & Database

UUID-based Models - Automatic UUID generation for all models via HasUuid trait
Base Model Classes - BaseModel and BaseUserModel with built-in UUID support
All models use UUIDs as route keys for better security

Authentication & Security

Laravel Fortify - Headless authentication backend
Two-Factor Authentication - QR codes and recovery codes
Email Verification - Built-in email verification flow
Password Reset - Secure password reset functionality
Password Confirmation - Protected routes with password confirmation
Spatie Permission - Role and permission management with UUID support

Monitoring & Queue Management

Laravel Telescope - Debugging and monitoring tool (path: admin/system/debug/monitoring)
Laravel Horizon - Redis-based queue monitoring (path: admin/system/queue-monitor)
Log Viewer - Fast and beautiful log viewer (path: admin/system/log-viewer)
Secure access gates for production environments

Real-time Support

Laravel Reverb - WebSocket server for real-time features
Broadcasting support with Laravel Echo

Development Tools

Laravel Boost - MCP server for enhanced development experience
Laravel Pint - Code formatter (PSR-12)
Pest - Modern testing framework (v4)
Laravel Sail - Docker development environment
Laravel Pail - Real-time log viewer

Configuration

Environment Helpers - Helper functions for environment detection (appEnv(), isProduction(), isDevelopment(), etc.)
Stable Configurations - Environment-aware Redis client selection (Predis for development, PhpRedis for production)
Secure Paths - Protected monitoring tool paths

📦 Installation

Prerequisites

PHP 8.2 or higher
Composer
Node.js and npm
Database (MySQL, PostgreSQL, SQLite, etc.)

Quick Start

Create a new project:

Option A: Using Git (Recommended)
```
git clone https://github.com/aabidbyte/laravel-basic-setup.git my-app
cd my-app
composer install
```
Option B: Using Composer (if published to Packagist)
```
composer create-project aabidbyte/laravel-basic-setup my-app
cd my-app
```
Note: If the package is not yet on Packagist, use Option A (Git clone) instead.
Install dependencies (if using Git clone, composer install was already run):
```
composer install
npm install
```
Set up application (includes database):
```
php artisan setup:application
```
This interactive command will:
- Configure your database connection
- Run fresh migrations (drops all tables and re-runs migrations by default)
⚠️ Warning: By default, migrations run fresh, which will drop all existing tables and delete all data in the database. You will be prompted to confirm before proceeding.

Note: To keep existing data, use the --no-fresh option:
```
php artisan setup:application --no-fresh
```

Configure your database in .env (if not done via setup:application):

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run migrations (if not done via setup:application):
```
php artisan migrate
```

Build frontend assets:

npm run build
# or for development
npm run dev

Start the development server:
```
php artisan serve
```

Publishing to Packagist (Optional)

If you want to publish this starter to Packagist so users can install it via composer create-project:

Create an account on Packagist.org
Submit your repository: https://github.com/aabidbyte/laravel-basic-setup
Packagist will automatically detect updates when you push tags
Users can then install with: composer create-project aabidbyte/laravel-basic-setup my-app

Creating Release Tags

Use the built-in Artisan command to automatically create and push release tags:

# Auto-increment minor version (e.g., 1.0.0 -> 1.1.0)
php artisan release:tag

# Auto-increment and push to remote
php artisan release:tag --push

# Specify a custom version
php artisan release:tag --tag-version=2.0.0

# Custom version with custom message
php artisan release:tag --tag-version=2.0.0 --message="Major release with new features"

# Dry run (see what would be done)
php artisan release:tag --dry-run

# Skip uncommitted changes check (useful for CI/CD)
php artisan release:tag --push --force

Features:

Automatically increments minor version by default (e.g., v1.0.0 → v1.1.0)
If no tags exist, starts with v1.0.0
Validates semantic versioning format
Optionally pushes to remote with --push flag
Supports custom version and message

🔄 Upgrading from the Starter Template

If you've created a project from this starter template and want to pull in the latest updates:

php artisan starter:upgrade

This command will:

Check for the upstream remote (adds it if missing)
Fetch the latest changes from the starter repository
Show you what has changed
Allow you to merge updates into your project

Upgrade Options

# Dry run (see what would change without making changes)
php artisan starter:upgrade --dry-run

# Specify a different upstream repository
php artisan starter:upgrade --upstream=https://github.com/user/repo.git

# Upgrade from a specific branch
php artisan starter:upgrade --branch=develop

Manual Upgrade

If you prefer to upgrade manually:

# Add upstream remote (if not already added)
git remote add upstream https://github.com/aabidbyte/laravel-basic-setup.git

# Fetch latest changes
git fetch upstream

# View changes
git log HEAD..upstream/main

# Merge changes
git merge upstream/main

# Resolve any conflicts, then:
git add .
git commit

Note: Always test your application after upgrading and review any conflicts carefully.

🎯 About Livewire

This starter uses Livewire as its frontend framework, providing:

Server-side rendering with minimal JavaScript
Interactive components without writing JavaScript
Volt single-file components for simplicity
Tailwind CSS for beautiful, responsive interfaces
Real-time updates and reactive data binding

Perfect for:

Admin panels
Dashboards
Forms and data entry
Traditional and modern web applications

🛠️ Technology Stack

Core

PHP: 8.2+
Laravel: 12.0
Database: MySQL, PostgreSQL, SQLite, SQL Server

Frontend

Livewire: 4.x with single-file components

Styling

Tailwind CSS: 4.x
DaisyUI: Component library for Tailwind CSS with theme-aware classes
Vite: 7.x (asset bundling)

Authentication

Laravel Fortify: 1.30
Laravel Sanctum: 4.0 (API authentication)
Spatie Permission: 6.23 (role and permission management)

Monitoring

Laravel Telescope: 5.16
Laravel Horizon: 5.40

Real-time

Laravel Reverb: 1.0

Development

Laravel Boost: 1.8
Laravel Pint: 1.26
Pest: 4.1
Laravel Sail: 1.41
Laravel Pail: 1.2.2

📚 Quick Start Guides

Livewire Stack

After installing the Livewire stack:

Create a Volt component:
```
php artisan make:volt MyComponent
```

Use DaisyUI components with theme-aware classes:

<button wire:click="save" class="btn btn-primary">Save</button>

Create routes:

use Livewire\Volt\Volt;

Volt::route('my-page', 'my-page')->name('my.page');

🔧 Configuration

Environment Variables

Key environment variables to configure:

APP_NAME="Your App Name"
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Redis (for queues, cache, sessions)
REDIS_CLIENT=predis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Broadcasting (Reverb)
BROADCAST_DRIVER=reverb
REVERB_APP_ID=your-app-id
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST=localhost
REVERB_PORT=8080
REVERB_SCHEME=http

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

Redis Client Selection

The starter kit automatically selects the appropriate Redis client:

Development: Uses Predis (pure PHP, no extension required)
Production: Uses PhpRedis (faster, requires extension)

This is configured in config/database.php and config/cache.php.

🧪 Testing

Run tests using Pest:

# Run all tests
php artisan test

# Run specific test file
php artisan test tests/Feature/ExampleTest.php

# Run with filter
php artisan test --filter=testName

🎨 Code Formatting

Format code using Laravel Pint:

# Format all files
vendor/bin/pint

# Format only changed files
vendor/bin/pint --dirty

🚢 Development Workflow

Using Composer Scripts

# Run all development services (server, queue, logs, vite, reverb)
composer run dev

# Run tests
composer run test

Manual Development

# Start Laravel server
php artisan serve

# Start queue worker
php artisan horizon

# Start Reverb server
php artisan reverb:start

# Watch for frontend changes
npm run dev

# View logs
php artisan pail

📖 Key Concepts

UUID Models

All models automatically generate UUIDs:

use App\Models\Base\BaseModel;

class Product extends BaseModel
{
    // UUID is automatically generated and used as route key
}

Base Model Classes

BaseModel - For regular models (includes HasUuid trait)
BaseUserModel - For authenticatable models (includes HasUuid, HasFactory, Notifiable)

Always extend these base classes instead of Eloquent base classes.

Environment Helpers

Use helper functions for environment detection:

if (isProduction()) {
    // Production code
}

if (isDevelopment()) {
    // Development code
}

if (inEnvironment('staging', 'production')) {
    // Staging or production
}

🔒 Security

Monitoring Tools Access

Telescope, Horizon, and Log Viewer are protected by gates. Update the gates in:

app/Providers/TelescopeServiceProvider.php
app/Providers/HorizonServiceProvider.php
app/Providers/LogViewerServiceProvider.php

Add authorized email addresses to the gate definitions.

Authentication

All authentication features are configured via Laravel Fortify. Customize in:

config/fortify.php - Feature configuration
app/Providers/FortifyServiceProvider.php - View and action configuration
app/Actions/Fortify/ - Business logic customization

Authorization & Permissions

Role and permission management is handled by Spatie Permission. The package is configured to work with UUID-based User models.

Configuration:

Config file: config/permission.php
Migration: Modified to use model_uuid instead of model_id for UUID support
User model: App\Models\User includes the HasRoles trait

Basic Usage:

// Assign a role to a user
$user->assignRole('admin');

// Check if user has a role
if ($user->hasRole('admin')) {
    // User is an admin
}

// Give permission to a user
$user->givePermissionTo('edit posts');

// Check if user has permission
if ($user->can('edit posts')) {
    // User can edit posts
}

// Create a role with permissions
$role = Role::create(['name' => 'writer']);
$role->givePermissionTo('edit posts');

Teams Permissions:

Teams permissions are enabled by default, allowing flexible control for multi-tenant scenarios. The middleware TeamsPermission automatically sets the team ID from the session.

Configuration:

Teams enabled: config/permission.php → 'teams' => true
Custom team foreign key: Set 'team_foreign_key' => 'custom_team_id' in config if needed
Middleware: app/Http/Middleware/TeamsPermission.php (sets team ID from session)

Usage with Teams:

// Set team ID in session (typically on login)
session(['team_id' => $team->id]);

// Create roles with team_id
Role::create(['name' => 'writer', 'team_id' => null]); // Global role
Role::create(['name' => 'reader', 'team_id' => 1]); // Team-specific role

// Switch active team
setPermissionsTeamId($new_team_id);
$user->unsetRelation('roles')->unsetRelation('permissions');

// Now check roles/permissions for the new team
$user->hasRole('admin');
$user->can('edit posts');

Important Notes:

The User model must NOT have role, roles, permission, or permissions properties/methods/relations
The package uses UUIDs for the User model relationships (configured in config/permission.php)
Teams middleware must run before SubstituteBindings (configured in AppServiceProvider)
When switching teams, always unset cached relations before querying
See Spatie Permission Documentation for more details

📝 License

This starter kit is open-sourced software licensed under the MIT license.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📞 Support

For issues and questions, please open an issue on the GitHub repository.

Built with ❤️ using Laravel 12

aabidbyte / laravel-basic-setup

Maintainers

Details

README

🚀 Features

Frontend

Backend Infrastructure

Models & Database

Authentication & Security

Monitoring & Queue Management

Real-time Support

Development Tools

Configuration

📦 Installation

Prerequisites

Quick Start

Publishing to Packagist (Optional)

Creating Release Tags

🔄 Upgrading from the Starter Template

Upgrade Options

Manual Upgrade

🎯 About Livewire

🛠️ Technology Stack

Core

Frontend

Styling

Authentication

Monitoring

Real-time

Development

📚 Quick Start Guides

Livewire Stack

🔧 Configuration

Environment Variables

Redis Client Selection

🧪 Testing

🎨 Code Formatting

🚢 Development Workflow

Using Composer Scripts

Manual Development

📖 Key Concepts

UUID Models

Base Model Classes

Environment Helpers

🔒 Security

Monitoring Tools Access

Authentication

Authorization & Permissions

📝 License

🤝 Contributing

📞 Support