Laravel Boilerplate

A robust starter project using Laravel 12 for rapid, modern API development.
Clean structure, best practices, authentication, and a suite of developer tools out of the box.

---

🚀 Quick Start

# 1. Clone the repository
$ git clone <your-repo-url>
$ cd laravel-boilerplate

# 2. Install dependencies
$ composer install
$ npm install && npm run build

# 3. Copy .env and configure
$ cp .env.example .env

# 4. Generate app key
$ php artisan key:generate

# 5. Run migrations and seeders
$ php artisan migrate --seed

# 6. Start the server
$ php artisan serve

---

✨ Features & Packages

• Authentication (Laravel Sanctum)
• Role & Permission Management (Spatie Laravel Permission)
• Media/File Management (Plank Mediable)
• API Documentation (L5-Swagger)
• Request Monitoring (Laravel Telescope)
• Log Management (Log Viewer)
• Queue Monitoring (Laravel Horizon)
• Performance Monitoring (Laravel Pulse)
• Code Style (Laravel Pint)
• Static Analysis (Larastan/PHPStan)
• Universal Developer Panel Protection (Littlegatekeeper)

---

⚙️ Custom Environment Variables

In addition to standard Laravel variables, set these in your .env:

• FRONT_WEBSITE_URL — The URL of your frontend application
• MASTER_PASSWORD — Master password for privileged/admin operations
• MASTER_OTP — Master OTP code for bypassing OTP verification
• DEVELOPER_USERNAME / DEVELOPER_PASSWORD — Credentials for the developer panel
• LOG_DAILY_DAYS — Days to retain log files takes 30 days default
• TELESCOPE_ENABLED — Enable/disable Laravel Telescope
• CDN_ENABLE — Enable/disable CDN usage for media URLs
• CDN_URL — The base URL of your CDN for media assets
• ONESIGNAL_APP_ID / ONESIGNAL_API_KEY — Your OneSignal App ID and API Key for push notifications
• NOTIFICATION_ENABLED — Enable or disable the notification system (true/false)

---

🗂️ Custom Configuration File Structure

• site.php — Site-wide settings (frontend URL, pagination, roles, OTP, user status)
• media.php — Media/file upload settings (tags, directories, CDN, types, MIME mappings)
• aws.php — AWS credentials/settings for S3 and related services

---

🌍 Localization File Structure

Localization files are in resources/lang/en/:

• email.php — Email-related strings
• entity.php — Entity names/messages
• message.php — General messages
• status.php — Status labels/messages
• notification.php — Notification titles and descriptions

Each file returns an array of key-value pairs for use with Laravel's __() and trans() functions.

---

📦 API Overview

Supported Endpoints

• Auth: Register, Login, Logout, Get Profile, Forget Password (OTP), Reset Password
• User: Update Profile, Change Password, Change Status (Admin)
• Country: List countries (with filters)
• Language: List languages
• Master Settings: List and detail endpoints
• Signed URL: Generate signed URLs for file uploads

API documentation is auto-generated and available at /api/documentation via Swagger (L5-Swagger).

API Folder Structure

• app/Http/Controllers/Api/ — API controllers (RESTful, thin, service-driven)
• app/Http/Requests/ — FormRequest classes for validation
• app/Http/Resources/ — API resource and collection transformers
• app/Services/ — Business logic and service classes
• app/Models/ — Eloquent models
• app/Rules/ — Custom validation rules
• app/Libraries/ — Libraries classes

---

🛠️ Custom Functionality

Custom Artisan Commands

• php artisan telescope:clear — Clears all entries/data from Laravel Telescope
• php artisan pulse:clear — Clears all entries/data from Laravel Pulse

Custom Validation Rules & Libraries

• MediaRule: Reusable validation for media/image fields (tags, mime types, nullable/required)
• MediaHelper: File naming, extension detection, media attachment/deletion, aggregate type detection
• Image Optimization: Configured via config/mediable.php for automatic optimization (JPEG, PNG, GIF, WebP, AVIF)

Mail Layout Customization

• All emails use a custom Blade layout: resources/views/emails/layouts/master.blade.php
  • Branded header with logo
  • Localized greetings and sign-off
  • Centralized content section (@yield('content'))
  • Footer with copyright

Notification System

• This boilerplate includes a robust notification system using Laravel's native features.

  • Channels Supported: Database, Email, and optional custom channels (e.g., SMS).
  • How It Works: Notifications are created as classes in app/Notifications/. You can add new notification types by creating additional classes in this directory.
  • API Integration: Endpoints are available for listing, marking as read/unread, and managing user notifications.

See the app/Notifications/ directory and related controllers/services for implementation details.

---

🧑‍💻 Developer Tools

Developer Panel

• /developer/telescope — Laravel Telescope
• /developer/log-viewer — Log Viewer
• /developer/pulse — Laravel Pulse
• /developer/login — Login for developer tools
• Authentication: Protected by DEVELOPER_USERNAME and DEVELOPER_PASSWORD in .env

Pre-commit Checklist & Code Quality

• Lint staged PHP files: npx --no-install lint-staged
• Code style check: ./vendor/bin/pint
• Static analysis: ./vendor/bin/phpstan --memory-limit=2G analyse
• Run tests: ./vendor/bin/phpunit

If you have issues committing, ensure pre-commit hooks are executable:

chmod ug+x .husky/pre-commit

• Pint: Run ./vendor/bin/pint to auto-format code. VS Code users can bind Pint to Ctrl+S for instant formatting.
• Larastan/PHPStan: Run ./vendor/bin/phpstan analyse for static analysis.

---

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

---

📄 License

MIT

---

💬 Support

For questions, suggestions, or support, please open an issue or contact the maintainer.