Laravel Boilerplate Project

A Laravel API boilerplate with Firebase Storage integration designed to accelerate your application development with pre-configured authentication, file storage, and API structure.

📋 Table of Contents

• Features
• Requirements
• Installation
• Configuration
  • Database Setup
  • Gmail Setup
  • Firebase Setup
  • Start Server
• Deployment
  • Deploy to Vercel
  • Deploy MySQL to Clever Cloud
• API Documentation
• Troubleshooting
  • Firebase Storage Issues
  • Email Sending Issues
  • Deployment Issues
• License

✨ Features

• RESTful API Architecture - Well-structured API endpoints with consistent response formats
• Advanced Rate Limiting - Customizable rate limiting for different API actions (read, write, delete)
• Firebase Storage Integration - Secure file uploads for user profiles and post attachments
• Authentication System - Secure token-based authentication with Laravel Sanctum
• Role-Based Access Control - Built-in roles (client, admin, freelancer) with permissions
• Email Notifications - Integrated email system using Gmail SMTP
• Comprehensive Error Handling - Standardized error responses with appropriate HTTP status codes
• Database Transactions - Ensures data integrity for all operations
• Well-Documented Code - Extensive PHPDoc comments throughout

🔧 Requirements

• PHP 8.1 or higher
• Composer
• MySQL 5.7+ or PostgreSQL 9.6+
• Node.js and NPM (for frontend assets and Vercel deployment)
• Firebase account
• Gmail account (for sending emails)

🚀 Installation

Step 1: Clone the Repository

git clone https://github.com/codebykenth/laravel-boilerplate.git
cd laravel-boilerplate

Step 2: Install Dependencies

composer install

Step 3: Set Up Environment Variables

cp .env.example .env

Step 4: Generate Application Key

php artisan key:generate

Step 5: Run Database Migrations

php artisan migrate:fresh

Step 6: Install Firebase SDK

composer require kreait/laravel-firebase
php artisan vendor:publish --provider="Kreait\Laravel\Firebase\ServiceProvider" 

Start the Local Server

php artisan serve

⚙️ Configuration

Database Setup

Update your .env file with your database credentials:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306 DB_DATABASE=your_database_name
DB_USERNAME=your_database_username
DB_PASSWORD=your_database_password

Gmail Setup

To use Gmail for sending emails from your application:

1. Go to your Google Account Security Settings
2. Enable 2-Step Verification if not already enabled
3. Under Signing in to Google, click App Passwords
4. Select "Mail" as the app and your device type
5. Click Generate

Create your app password here

6. Copy the 16-character password provided
7. Configure your .env file:
   MAIL_MAILER=smtp
   MAIL_HOST=smtp.gmail.com
   MAIL_PORT=587 MAIL_USERNAME=your_gmail@gmail.com
   MAIL_PASSWORD=your_16_character_app_password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS="your_gmail@gmail.com"
   MAIL_FROM_NAME="${APP_NAME}"

Firebase Setup

This boilerplate uses Firebase Storage for handling file uploads:

1. Go to the Firebase Console
2. Create a new project or select an existing one
3. Navigate to Project Settings > Service Accounts
4. Click Generate new private key and download the JSON file
5. Create a directory for your credentials:

mkdir -p storage/app/private

6. Move the downloaded JSON file to storage/app/private directory
7. Update your .env file:
   FIREBASE_CREDENTIALS=storage/app/private/your-firebase-credentials.json
   FIREBASE_PROJECT_ID=your_project_id
   FIREBASE_API_KEY=your_api_key
   FIREBASE_STORAGE_BUCKET=your-firebase_project-id.firebasestorage.app
8. Enable Firebase Storage in your Firebase Console:

• Go to Build > Storage in your Firebase project
• Click Get Started and follow the setup wizard
• Set appropriate security rules for your storage bucket

⚙️ Deployment

Deploy to Vercel (Optional)

1. Install the Vercel CLI:

npm install -g vercel

2. Create a vercel.json file in your project root:

{  
    "version": 2,  
      "framework": null,  
    "functions": {  
        "api/index.php": { "runtime": "vercel-php@0.7.3" }  
    },  
    "routes": [{  
        "src": "/(.*)",  
        "dest": "/api/index.php"  
    }],  
    "env": {  
        "APP_ENV": "production",  
        "APP_DEBUG": "true",  
        "APP_URL": "https://(your-project-name)-(username)-(username)-projects.vercel.app/api",  
    
        "APP_CONFIG_CACHE": "/tmp/config.php",  
        "APP_EVENTS_CACHE": "/tmp/events.php",  
        "APP_PACKAGES_CACHE": "/tmp/packages.php",  
        "APP_ROUTES_CACHE": "/tmp/routes.php",  
        "APP_SERVICES_CACHE": "/tmp/services.php",  
        "VIEW_COMPILED_PATH": "/tmp",  
   
        "CACHE_DRIVER": "array",  
        "LOG_CHANNEL": "stderr",  
        "SESSION_DRIVER": "cookie"  
    }
}

3. Create api folder then create index.php then copy and paste this code

<?php  
// require __DIR__."/../public/index.php";  
// Load the Laravel application  
require __DIR__ . '/../vendor/autoload.php';  
$app = require_once __DIR__ . '/../bootstrap/app.php';  
  
// Run the application  
$kernel = $app->make(Illuminate\Contracts\Http\Kernel::class);  
$response = $kernel->handle(  
    $request = Illuminate\Http\Request::capture()  
);  
$response->send();  
$kernel->terminate($request, $response);  

4. Create empty dist folder

5. Modify .htaccess located at /public folder. Copy and paste this code

<IfModule mod_rewrite.c>  
    <IfModule mod_negotiation.c>  
        Options -MultiViews -Indexes  
    </IfModule>  
 
    RewriteEngine On  
 
    # Handle Authorization Header  
    RewriteCond %{HTTP:Authorization} .  
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]  
 
    # Redirect Trailing Slashes If Not A Folder...  
    RewriteCond %{REQUEST_FILENAME} !-d  
    RewriteCond %{REQUEST_URI} (.+)/$  
    RewriteRule ^ %1 [L,R=301]  
 
    # Send Requests To Front Controller...  
    RewriteCond %{REQUEST_URI} !^/api  
    RewriteCond %{REQUEST_FILENAME} !-d  
    RewriteCond %{REQUEST_FILENAME} !-f  
    RewriteRule ^ index.php [L]  
   
    # Send Requests To API Front Controller...  
    RewriteRule ^api/.*$ /api/index.php [L]  
</IfModule>  

6. Create .vercelignore file then paste this /vendor

7. Run this on terminal.

vercel .

8. If there is an error, go to Vercel Dashboard->Settings

• Override the output directory and change it to public

9. Disable vercel authentication to access endpoint

10. Copy and paste .env from project

11. Redeploy project

vercel .

For more details, see the official tutorials:
LARAVEL DEPLOY TO VERCEL IN 5 MINUTES
[Deployment] Deploy Laravel to Vercel

Deploy to MySql to Clever Cloud for Free (Optional)

Go to Clever Cloud Dashboard

1. Go to Personal space
2. Create an add-on
3. Select MySQL
4. Choose DEV plan
5. Name and choose a location for your database
6. Copy the database information and paste it to .env

---

📚 API Documentation

Authentication

Method	Endpoint	Description	Authentication
POST	/api/register/{userType}	Register a new user (userType: client, admin, freelancer)	None
POST	/api/login	Login an existing user	None
POST	/api/logout	Logout the current user	Required

Posts Management

Method	Endpoint	Description	Authentication
GET	/api/posts	List all posts	Required
GET	/api/posts/{id}	View a specific post	Required
POST	/api/posts	Create a new post	Required
POST	/api/posts/{id}	Update a specific post	Required
DELETE	/api/posts/{id}	Delete a specific post	Required

Profile Management

Method	Endpoint	Description	Authentication
GET	/api/profiles	List all profiles	Required
GET	/api/profiles/me	View profile of authenticated user	Required
GET	/api/profiles/{id}	View a specific profile	Required
POST	/api/profiles	Update the authenticated user's profile	Required
DELETE	/api/profiles	Delete the authenticated user's account	Required

🔧 API Rate Limiting

This API implements the following rate limits to prevent abuse:

Limiter Type	Endpoints	Limits
auth	Login, Register	5 requests per minute, 100 requests per day
api	All authenticated endpoints	60 requests per minute, 1000 requests per day

⚙️ Troubleshooting

Firebase Storage Issues

• Ensure the Firebase credentials JSON file path is correctly set in .env
• Check that your Firebase Storage security rules allow read/write operations
• Verify that the Firebase Storage bucket name matches your .env configuration

Email Sending Issues

• Confirm your Gmail app password is correctly set in .env
• Ensure 2FA is enabled on your Google account
• Make sure "Less secure app access" is enabled for your Google account
• Check your firewall settings to ensure SMTP traffic is allowed

Deployment Issues

• For Vercel deployment issues, ensure your vercel.json is properly configured
• Set all environment variables in the Vercel dashboard
• Check that your PHP version is compatible (Vercel supports PHP 8.0+)
• Verify your database is accessible from Vercel's servers

License

The Laravel framework is open-sourced software licensed under the MIT license.