mkamelmasoud/starter-core-kit

A reusable Laravel starter kit for custom exception handling, middleware, and shared utilities.

1.4.0 2025-10-29 19:34 UTC

Requires

• php: ^8.1
• illuminate/support: ^8.0 || ^9.0 || ^10.0 || ^11.0 || ^12.0

Requires (Dev)

• laravel/framework: ^8.0 || ^9.0 || ^10.0 || ^11.0 || ^12.0
• laravel/pint: ^1.24
• nunomaduro/larastan: ^3.7
• orchestra/testbench: ^8.0 || ^9.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^10.5

Suggests

• tucker-eric/eloquentfilter: Use for advanced model filtering support

MIT

• Mostafa Kamel

• package
• middleware
• laravel
• utilities
• exception-handler
• starter-kit
• core-kit

README

A comprehensive, production-ready Laravel starter package that provides essential utilities, middleware, exception handling, AI integration, and repository patterns for modern Laravel applications.

✨ Features

🛡️ Exception Handling & Middleware

• Custom Global Exception Handler - Centralized exception handling with JSON responses
• API Header Validation Middleware - Ensures proper API request headers
• Dynamic Locale Middleware - Automatic locale detection from headers
• Multi-language Exception Messages - Localized error messages (English/Arabic)
• Comprehensive Exception Mapping - Pre-configured responses for common Laravel exceptions

🤖 AI Integration

• Multi-Provider AI Support - OpenAI and Router.ai integration
• Simple Factory Pattern - Clean provider instantiation
• AI Client Service - Easy-to-use interface for AI interactions
• Built-in Caching - Automatic response caching with TTL
• Comprehensive Logging - Detailed request/response logging

🏗️ Repository & Service Patterns

• Base Repository Pattern - Eloquent-based repository implementation
• Base Service Layer - Service layer with caching and transaction support
• CRUD Operations - Complete Create, Read, Update, Delete functionality
• Advanced Query Building - Flexible filtering and data fetching
• Caching Support - Built-in caching with TTL configuration

🔧 Utilities & Helpers

• API Response Traits - Standardized JSON response formatting
• File Upload Handling - Secure file upload utilities
• Cache Management - Advanced caching with automatic invalidation
• Helper Functions - Utility functions for common operations
• Validation Rules - Custom validation rules (e.g., NoHtmlRule)

📊 Data Management

• Pagination Support - Built-in pagination for large datasets
• Search Functionality - Advanced search capabilities
• Random Data Fetching - Random record selection
• Relationship Loading - Eager loading with relationship support
• Soft Delete Support - Soft delete functionality

📁 Project Structure

starter-core-kit/
+---src
|   PackageServiceProvider.php
|
+---Contracts
|   |   AiProviderContract.php
|   |   MiddlewareContract.php
|   |   ServiceContract.php
|   |   SortableContract.php
|   |
|   \---Repositories
|           BaseRepositoryContract.php
|           DeletableRepositoryContract.php
|           ReadableRepositoryContract.php
|           WritableRepositoryContract.php
|
+---Core
|   |   BaseDto.php
|   |   BaseEntity.php
|   |   BaseService.php
|   |
|   +---Ai
|   |   |   BaseAIProvider.php
|   |   |
|   |   \---Traits
|   |           BuildRequestTrait.php
|   |           HandlesValidationTrait.php
|   |           ManageStateTrait.php
|   |
|   +---Repositories
|   |   |   BaseEloquentRepository.php
|   |   |
|   |   \---Traits
|   |           BuildQueryTrait.php
|   |
|   \---Services
|       \---Traits
|               DeletableServiceTrait.php
|               ReadableServiceTrait.php
|               WritableServiceTrait.php
|
+---Exceptions
|       AiConfigNotFoundException.php
|       AiProviderNotFoundException.php
|       Handler.php
|
+---lang
|   +---ar
|   |       exceptions.php
|   |
|   \---en
|           exceptions.php
|
+---Middleware
|       ApiCheckHeadersMiddleware.php
|       ClearLoggerMiddleware.php
|       SetLocaleFromHeaderMiddleware.php
|
+---Providers
|       ConfigServiceProvider.php
|       ExceptionServiceProvider.php
|       MacroServiceProvider.php
|       MiddlewareServiceProvider.php
|       RepositoryServiceProvider.php
|       ResourceServiceProvider.php
|       SupportServiceProvider.php
|
+---Rules
|   \---Validation
|           NoHtmlRule.php
|
+---Services
|   \---Ai
|       |   AiClientService.php
|       |
|       +---AiProviders
|       |       OpenAiProviderService.php
|       |       RouterAiProviderService.php
|       |
|       \---Providers
+---Support
|   +---Factories
|   |       AiClientFactory.php
|   |
|   \---helpers
|           functions.php
|
\---Traits
    +---Api
    |       ApiResponsesTrait.php
    |
    +---File
    |       HandleFileUploadTrait.php
    |
    +---Service
    |       ServiceSupportTrait.php
    |
    \---Support
            SupportCacheTrait.php
            SupportSortableTrait.php

📦 Installation

Install the package via Composer:

composer require mkamelmasoud/starter-core-kit

The package will automatically register its service provider.

⚙️ Configuration

Publish the configuration files:

php artisan vendor:publish --tag=starter-core-kit

This will publish:

• config/starter-core-kit.php - Main configuration
• config/repositories.php - Repository configuration
• lang/vendor/starter-core-kit/ - Language files

🚀 Quick Start

1. Basic AI Usage

use MkamelMasoud\StarterCoreKit\Services\Ai\AiClientService;

// AI Integration - Simple usage
$aiClient = app('ai-client');
$response = $aiClient->ask('Hello, how are you?');

// With system prompt
$aiClient->setPrompt('system', 'You are a helpful assistant');
$response = $aiClient->ask('Write a poem about coding');

// Using specific provider
$aiClient = new AiClientService('openai');
$response = $aiClient->ask('Explain Laravel');

2. Repository Pattern

use MkamelMasoud\StarterCoreKit\Core\Repositories\BaseEloquentRepository;

class UserRepository extends BaseEloquentRepository
{
    protected function entity(): string
    {
        return User::class;
    }
}

3. Service Layer

use MkamelMasoud\StarterCoreKit\Core\BaseService;

class UserService extends BaseService
{
    protected function getDtoClass(): string
    {
        return UserDto::class;
    }

    protected function getRepoClass(): string
    {
        return UserRepository::class;
    }
}

4. API Responses

use MkamelMasoud\StarterCoreKit\Traits\Api\ApiResponsesTrait;

class UserController extends Controller
{
    use ApiResponsesTrait;

    public function index()
    {
        $users = User::all();
        return $this->success('Users retrieved successfully', $users);
    }
}

🔧 Configuration Options

Main Configuration (config/starter-core-kit.php)

return [
    'version' => '1.0.0',
    'supported_locales' => ['en', 'ar'],
    
    'middlewares' => [
        'set_locale' => env('SET_LOCALE', true),
        'clear_logger' => env('CLEAR_LOGGER', false),
        'api_check_headers' => env('API_CHECK_HEADERS', true),
    ],
    
    'cache_results' => [
        'enabled' => env('APP_CACHE_RESULTS_ENABLED', false),
        'ttl' => env('APP_CACHE_RESULTS_TTL', 1),
    ],
    
    'ai' => [
        'enabled' => env('AI_ENABLED', true),
        'default' => env('AI_PROVIDER', 'openai'),
        'fallback' => env('AI_PROVIDER_FALLBACK', 'router'),
        
        'cache' => [
            'enabled' => env('AI_CACHE_ENABLED', true),
            'ttl' => env('AI_CACHE_TTL', 600),
        ],
        
        'timeout' => env('AI_PROVIDER_TIMEOUT', 20),
        'retry' => [
            'attempts' => env('AI_PROVIDER_RETRY_ATTEMPTS', 2),
            'delay' => env('AI_PROVIDER_RETRY_DELAY_MS', 500),
        ],
        
        'logging' => [
            'enabled' => env('AI_PROVIDER_LOGGING_ENABLED', true),
        ],
        
        'providers' => [
            'openai' => [
                'api_key' => env('OPENAI_API_KEY'),
                'base_url' => env('OPENAI_BASEURL', 'https://api.openai.com'),
                'version' => env('OPENAI_VERSION', 'v1'),
                'end_point' => env('OPENAI_ENDPOINT', 'chat/completions'),
                'model' => env('OPENAI_MODEL', 'gpt-4o-mini'),
            ],
            'router' => [
                'api_key' => env('ROUTER_API_KEY'),
                'base_url' => env('ROUTER_BASEURL', 'https://openrouter.ai/api'),
                'version' => env('ROUTER_VERSION', 'v1'),
                'end_point' => env('ROUTER_ENDPOINT', 'chat/completions'),
                'model' => env('ROUTER_MODEL', 'gpt-4o-mini'),
            ],
        ],
    ],
];

Environment Variables

# AI Configuration
AI_ENABLED=true
AI_PROVIDER=openai
AI_PROVIDER_FALLBACK=router

# OpenAI Configuration
OPENAI_API_KEY=your_openai_key
OPENAI_BASEURL=https://api.openai.com
OPENAI_VERSION=v1
OPENAI_ENDPOINT=chat/completions
OPENAI_MODEL=gpt-4o-mini

# Router Configuration
ROUTER_API_KEY=your_router_key
ROUTER_BASEURL=https://openrouter.ai/api
ROUTER_VERSION=v1
ROUTER_ENDPOINT=chat/completions
ROUTER_MODEL=gpt-4o-mini

# AI Cache Configuration
AI_CACHE_ENABLED=true
AI_CACHE_TTL=600

# AI Request Configuration
AI_PROVIDER_TIMEOUT=20
AI_PROVIDER_RETRY_ATTEMPTS=2
AI_PROVIDER_RETRY_DELAY_MS=500
AI_PROVIDER_LOGGING_ENABLED=true

# Middleware Configuration
SET_LOCALE=true
CLEAR_LOGGER=false
API_CHECK_HEADERS=true

# Cache Configuration
APP_CACHE_RESULTS_ENABLED=false
APP_CACHE_RESULTS_TTL=1

🛠️ Advanced Usage

Custom Exception Handling

The package provides comprehensive exception handling for common Laravel exceptions:

• ModelNotFoundException → 404 Not Found
• NotFoundHttpException → 404 Not Found
• MethodNotAllowedHttpException → 405 Method Not Allowed
• ValidationException → 422 Unprocessable Entity
• AuthorizationException → 401 Unauthorized
• AuthenticationException → 403 Forbidden
• ThrottleRequestsException → 429 Too Many Requests
• And many more...

Middleware Usage

// In your routes/web.php or routes/api.php
Route::middleware(['api', 'starter-core-kit.api-headers'])->group(function () {
    // Your API routes
});

Route::middleware(['starter-core-kit.locale'])->group(function () {
    // Routes that need locale detection
});

Repository Advanced Features

// Advanced query building
$users = $userRepository
    ->where('status', '=', 'active')
    ->where('age', '>', 18)
    ->with(['profile', 'posts'])
    ->fetchData(['status' => 'active'], 'paginate', 20);

// Search functionality
$results = $userService->search(['name' => ['John', 'Jane']]);

// Random records
$randomUsers = $userService->inRandomOrder(5);

Caching Features

// Automatic caching with TTL
$users = $userService->fetchData(
    filters: ['status' => 'active'],
    cachePrefix: 'active_users'
);

// Manual cache management
$userService->clearCache('users');

🌍 Internationalization

The package supports multiple languages out of the box:

• English (en) - Default
• Arabic (ar) - RTL support

Add more languages by extending the language files in lang/vendor/starter-core-kit/.

🧪 Testing

Run the test suite:

composer test

Run code quality checks:

composer phpstan
composer pint

📚 API Documentation

AI Client Service

// Basic usage
$response = app('ai-client')->ask('Your prompt here');

// With system prompt
$aiClient = app('ai-client');
$aiClient->setPrompt('system', 'You are a helpful assistant');
$response = $aiClient->ask('Your prompt');

// Using specific provider
$aiClient = new AiClientService('openai');
$response = $aiClient->ask('Your prompt');

// Advanced usage with configuration
$aiClient = new AiClientService('router');
$aiClient->setPrompt('system', 'You are a coding expert');
$response = $aiClient->ask('Explain Laravel middleware');

Repository Methods

// Fetch data with filters
$data = $repository->fetchData(
    filters: ['status' => 'active'],
    dataTypeReturn: 'paginate', // 'get', 'builder', 'paginate'
    limit: 20,
    random: false
);

// Find single record
$user = $repository->find(1);

// Find multiple records
$users = $repository->findMany([1, 2, 3]);

// CRUD operations
$user = $repository->store($data);
$user = $repository->update(1, $data);
$repository->delete(1);

Service Layer Methods

// Data fetching with caching
$users = $userService->fetchData(['status' => 'active']);

// Search functionality
$results = $userService->search(['name' => ['John']]);

// Random records
$randomUsers = $userService->inRandomOrder(5);

// CRUD with DTOs
$user = $userService->store($userDto);
$user = $userService->update(1, $userDto);
$userService->delete(1, 'soft'); // or 'force'

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Laravel Framework
• OpenAI API
• OpenRouter API
• The Laravel community

📞 Support

• Issues: GitHub Issues
• Documentation: GitHub Repository
• Email: [e-mail]

Made with ❤️ by Mostafa Kamel