Skip to content

README.md

Latest commit

 

History

History
226 lines (154 loc) · 8.07 KB

README.md

File metadata and controls

226 lines (154 loc) · 8.07 KB

Laravel Boilerplate Logo

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.

Laravel License Code Style

🚀 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. Configure Git hooks (Husky)
$ git config core.hooksPath .husky

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

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

# 7. Start the server
$ php artisan serve

✨ Features & Packages

⚙️ 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

🛠️ Generate Custom Swagger Documentation with Minimal Code in Controllers

Your custom Swagger setup lives in the app/Swagger/ directory.

📁 Folder Structure

  • app/Swagger/Processors/ Contains custom processors used to dynamically generate Swagger documentation (e.g., auto-generating request bodies, responses, etc.).

⚙️ Setup Instructions

  • To enable your custom processors, add the following entry inside the processors array in the l5-swagger.php configuration file (located in config/):

  • new \App\Swagger\Processors\SuccessResponsesProcessor(),

🚀 What This Provides

  • Automatically generates Swagger documentation based on Form Request rules.
  • Allows you to write minimal or no OpenAPI annotations in controllers.
  • Supports customizing, extending, or skipping auto-generation when needed.

🛠️ 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.