mrprotocoll/api-boilerplate-laravel

This Laravel 11 API boilerplate provides a structured foundation for building robust backend applications with Laravel, integrating essential features and tools.

v0.1.0 2024-07-12 13:17 UTC

Requires

• php: ^8.2
• ext-fileinfo: *
• darkaonline/l5-swagger: ^8.6
• laravel/breeze: ^2.1
• laravel/framework: ^11.9
• laravel/sanctum: ^4.0
• laravel/socialite: ^5.15
• laravel/tinker: ^2.9
• larowka/prevent-duplicate-requests: ^1.1

Requires (Dev)

• fakerphp/faker: ^1.23
• laravel/pint: ^1.13
• laravel/sail: ^1.26
• mockery/mockery: ^1.6
• nunomaduro/collision: ^8.0
• nunomaduro/larastan: ^2.9
• pestphp/pest: ^2.0
• pestphp/pest-plugin-laravel: ^2.0

MIT

• framework
• boilerplate
• laravel

Published on Packagist.org on 2024-07-12 13:53 UTC

README

🕹️🕹️ Laravel API Boilerplate🕹️🕹️

📗 Table of Contents

• 📖 About the Project
  • 🛠 Built With
    • Tech Stack
  • 🚀 Links
  • Features
• 💻 Getting Started
  • Setup
  • Prerequisites
  • Usage
• 🤝 Contributing

📖 API Boilerplate

A robust, modular Laravel 11 API boilerplate built using a Domain-Driven Design (DDD) approach. This boilerplate provides a scalable foundation for modern API development with essential features like role-based access, versioning, Google OAuth integration, and more..

Features

• Domain-Driven Architecture: Organized modules and shared resources for scalability.
• Versioning: Supports multiple API versions with structured routing.
• Role-Based Access Control: Integrated roles and permissions with easy extensibility.
• Google OAuth: Simplified OAuth 2.0 authentication setup.
• Modular Components: Independent modules for Auth, User, and more.
• Enums and Helpers: Centralized, reusable enums and helper methods.
• Custom Middlewares: Pre-configured middlewares for JSON responses, caching, logging, and preventing duplicate requests.
• Optimized Exception Handling: Friendly and consistent error responses.
• Custom Base Model: A UUID-enabled base model for consistency across entities.
• Seeders and Factories: Simplified data seeding with predefined roles.
• Rate Limiting: API throttling to prevent abuse.
• Fully Documented: Swagger/OpenAPI support for API documentation.
• AI Agent Infrastructure: Provider adapters, DB-backed chat sessions, tool execution, usage limits, and streaming-ready API endpoints.

Architecture Overview

Domain-Driven Design (DDD)

The project structure is organized to separate concerns:

src/modules: Contains feature-specific modules, e.g., Auth and User. src/shared: Shared resources like helpers, enums, and base classes.

Versioning

Version-specific modules and routes are located in the V1 directory for flexibility.

Tech Stack

• PHP
• Laravel

(back to top)

🚀 Links

To access the documentation goto the below link

• Link to api routes

http://localhost:8000/v1

• Link to documentation

http://localhost:8000/v1/documentation

(back to top)

💻 Getting Started

To get a local copy up and running, follow these steps.

Prerequisites

In order to run this boilerplate, you need:

1. PHP ^8.2
   use the following link to setup PHP if you dont have it already installed on your computer

(install PHP)

1. Composer
   use the following link to Download Composer if you dont have it already installed on your computer

(install Composer)

Install

clone the repository:

git clone [e-mail]:mrprotocoll/api-boilerplate-laravel.git

Install dependencies:

composer install

Setup

Create your database.

create .env file, change using the .env.example file and update the Database, Google Oauth (optional), and Email credentials.

cp .env.example .env

Generate keys, Run the migration and seed roles:

php artisan key:generate 
php artisan migrate --seed

Usage

The following command can be used to run the application.

  php artisan serve

AI Agent Infrastructure

The boilerplate includes a ready-to-ship AI assistant module under src/modules/V1/AI.

Configure a provider in .env:

AI_PROVIDER=openai
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4.1-mini
AI_MAX_TOOL_STEPS=3
AI_TOOL_RESULT_SYNTHESIS=true

Run migrations to create the AI tables:

php artisan migrate

Authenticated API endpoints:

POST   /v1/user/ai/sessions
GET    /v1/user/ai/sessions/latest
GET    /v1/user/ai/sessions
POST   /v1/user/ai/messages
POST   /v1/user/ai/messages/stream
PATCH  /v1/user/ai/messages/{messageId}/flag
GET    /v1/user/ai/sessions/{sessionToken}/messages

Send a message:

{
  "sessionToken": "optional-existing-session-token",
  "sourcePage": "/dashboard",
  "message": "What time is it and where can I edit my profile?"
}

The runtime supports native provider tools where available. It uses AI_MAX_TOOL_STEPS to prevent runaway loops and AI_TOOL_RESULT_SYNTHESIS to convert tool outputs into a final user-facing answer.

Default read-only tools:

• current_time
• authenticated_user
• application_info
• navigate

To add a tool, implement Modules\V1\AI\Contracts\AIToolHandler, return an AIToolDefinition, and register the handler in AIToolRegistry. Keep mutating tools disabled or confirmation-gated by setting mutatesState or requiresConfirmation on the definition and replacing AIToolAuthorizer with your application permission logic.

(back to top)

Contributing

Feel free to fork the repository, make changes, and submit pull requests. Feedback is always welcome!

License

This project is licensed under the MIT License.