Download the PHP package twenycode/laravel-blueprint without Composer

Laravel Blueprint

A comprehensive architecture and utilities package for Laravel applications that provides a standardized structure, core components, and common patterns to accelerate development.

Introduction

Laravel Blueprint provides a solid foundation for building Laravel applications with a clean architecture, standardized patterns, and reusable components. It implements the repository pattern, service layer, and includes numerous utilities and base classes to streamline your development process.

Features

• Repository Pattern - Comprehensive data access layer with built-in caching support
• Service Layer - Business logic abstraction with database transaction management
• Resource Controllers - Base controllers with CRUD operations, error handling, and flash messaging
• Model Enhancements - Feature-rich base model with common attributes and methods
• Caching System - Automatic cache management with model observers
• Helper Functions - Extensive utility functions for dates, text, and numbers
• Error Handling - Standardized error handling traits across application components
• ID Obfuscation - HashIds implementation for obscuring database IDs in URLs
• Form Request Validation - Permission-based request validation
• Soft Delete Support - Ready-to-use methods for handling soft deletes
• Flash Messaging - Integrated SweetAlert for beautiful flash messages and notifications
• Custom Validation Rules - Composite key uniqueness validation
• API Support - JSON response handling for API controllers

Requirements

• PHP 8.2+
• Laravel 8.0+

Installation

You can install this package via Composer:

Configuration

Publish the configuration files:

This will publish the following configuration files:

• config/tweny-blueprint.php - Main configuration settings
• config/tweny-hashids.php - HashIds configuration

SweetAlert Integration

This package includes integration with RealRashid/SweetAlert for beautiful flash messages and notifications.

Setup SweetAlert

1. Make sure SweetAlert is installed:

2. Publish SweetAlert assets:

3. Include the SweetAlert view component in your layout:

4. If you encounter JavaScript errors about Swal not being defined, add SweetAlert's CDN in your layout:

Using Flash Messages

The Base Controller and Resource Controllers provide built-in methods for flash messaging:

Usage

Repositories

The BaseRepository provides a comprehensive set of methods for data access:

Basic CRUD Operations

All Available Repository Methods

Model & Utility Methods:

• model() - Get model instance
• decode($id) - Decode hashed ID

Basic CRUD Operations:

• getAll() - Retrieve all records
• create(array $data) - Create new record
• show($id) - Show record by ID (alias for findById)
• findById($id) - Find record by ID
• update($id, array $data) - Update existing record
• delete($id) - Delete record

Relationship Methods:

• getAllWithRelationships() - Get all records with relationships
• getActiveDataWithRelations() - Get active records with relationships
• getInactiveDataWithRelations() - Get inactive records with relationships

Status-Based Methods:

• getActiveData() - Get all active records
• pluckActiveData() - Get active records as name-id pairs
• updateActiveStatus($object, $status = null) - Toggle active status

Soft Delete Methods:

• trashed() - Get soft-deleted records
• findTrashedById($id) - Find soft-deleted record by ID
• restore($id) - Restore soft-deleted record
• forceDelete($id) - Permanently delete record

Query & Search Methods:

• searchByQuery(string $searchTerm) - Search records by query
• liveSearch(string $searchTerm) - Live search for records
• getInformationBy(string $filterTerm) - Get filtered information
• paginateWithRelationships($perPage = 25) - Paginate with relationships

Utility Methods:

• deleteWhere($column, $value) - Delete records based on column value
• orderBy($column, $value) - Get records ordered by column

Caching Methods (via RepositoryCacheTrait):

• setCacheDuration(int $minutes) - Set cache duration
• generateCacheKey(...$args) - Generate cache key
• forgetCache(array $keys) - Forget specific cache keys
• clearCacheKey() - Clear all cache keys for model

Services

Create service classes by extending the base service:

All Available Service Methods

Model & Utility Methods:

• model() - Get model instance

Basic CRUD Operations:

• getAll() - Retrieve all records
• create(array $data) - Create new record
• show($id) - Show record by ID
• findById($id) - Find record by ID
• update($id, array $data) - Update existing record
• delete($id) - Delete record

Relationship Methods:

• getAllWithRelationships() - Get all records with relationships
• getActiveDataWithRelations() - Get active records with relationships
• getInactiveDataWithRelations() - Get inactive records with relationships

Status Methods:

• updateActiveStatus($modelId, $status = null) - Update active status

Soft Delete Methods:

• trashed() - Get soft-deleted records
• restore($id) - Restore soft-deleted record
• forceDelete($id) - Permanently delete record

Query & Search Methods:

• searchByQuery(string $searchTerm) - Search records by query
• liveSearch(string $searchTerm) - Live search for records
• getInformationBy(string $filterTerm) - Get filtered information

Transaction Support:

• transaction(Closure $callback, int $attempts = 1) - Execute within database transaction

Controllers

Web Resource Controllers

Create resource controllers by extending the base resource controller:

Available Controller Methods:

• index() - Display listing of resources
• create() - Show form for creating new resource
• processStore($request) - Store newly created resource
• show($id) - Display specified resource
• edit($id) - Show form for editing resource
• processUpdate($request, $id) - Update specified resource
• destroy($id) - Remove specified resource
• trashed() - Get soft-deleted records
• restore($id) - Restore soft-deleted resource
• forceDelete($id) - Permanently delete resource
• updateActiveStatus($id) - Update active status
• authorizeAction($action, $object = null) - Check permissions

API Resource Controllers

For API endpoints, extend the BaseApiResourceController:

Available API Controller Methods:

• index() - Get all resources (JSON)
• processStore($request) - Create new resource (JSON)
• show($id) - Get specific resource (JSON)
• processUpdate($request, $id) - Update resource (JSON)
• destroy($id) - Delete resource (JSON)
• trashed() - Get soft-deleted resources (JSON)
• restore($id) - Restore soft-deleted resource (JSON)
• forceDelete($id) - Permanently delete resource (JSON)
• updateActiveStatus($id) - Update active status (JSON)

Models

Create models by extending the base model:

Available Model Features:

• ID Hashing: encode(), decode($value), getEncodedIdAttribute()
• Activity Logging: Automatic logging of model changes
• Date Mutators: Automatic date formatting for start_date, end_date, date
• Date Accessors: Formatted date display methods
• Status Methods: activate(), deactivate()
• Scopes: active(), inactive(), ordered(), boolean()
• Utility Methods: returnID($data) for ID lookup by name

Form Requests

Create form requests by extending the base form request:

Available Form Request Methods:

• checkPermission($permission) - Check user permission with super admin bypass

Custom Validation Rules

Composite Key Uniqueness Rule

For validating unique combinations of fields:

Helper Functions

The package provides a wide range of helper functions:

Date Helpers

Number Helpers

Text Helpers

Caching System

Repository Caching

The package includes automatic caching for repository methods:

Event Caching

For event-based caching, use the EventCacheTrait:

Model Cache Observers

Models are automatically observed for cache clearing:

Configuration

Cache Configuration

Configure caching behavior in config/tweny-blueprint.php:

Hash IDs Configuration

Configure ID hashing in config/tweny-hashids.php:

Model Configuration

Configure model behavior in config/tweny-blueprint.php:

Authorization Configuration

Configure authorization settings in config/tweny-blueprint.php:

Error Handling

All components use standardized error handling:

Extending The Package

Custom Repositories

Add specialized queries and methods to your repository classes:

Custom Services

Add complex business logic in your service classes:

Testing

The package is designed to be easily testable:

Performance Considerations

Caching Strategy

• Repository methods are cached by default for 24 hours
• User-specific caching for employee role data
• Automatic cache invalidation on model changes
• Configurable cache duration per operation

Database Optimization

• Eager loading relationships by default
• Pagination support for large datasets
• Selective querying with active/inactive scopes
• Efficient soft delete handling

Memory Management

• Lazy loading of relationships when not needed
• Configurable pagination limits
• Efficient query building with repository pattern

Troubleshooting

Common Issues

1. Cache not clearing: Ensure model observers are registered in config
2. Hash IDs not working: Check HASHIDS_SALT environment variable
3. Permission errors: Verify user roles and permissions setup
4. SweetAlert not displaying: Check JavaScript console for errors

Debug Mode

Enable debug logging by adding to your .env:

Performance Monitoring

Monitor cache hit rates and query performance:

Contributing

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

License

This package is open-sourced software licensed under the MIT license.