artflow-studio/snippets

A Laravel package for performing basic operations.

v1.9 2025-06-21 20:26 UTC

This package is auto-updated.

Last update: 2025-06-21 20:31:48 UTC


README

🚀 AF Web Snippets

A powerful collection of Laravel web snippets to supercharge your development workflow

PHP Version Laravel Version Livewire License Version

📋 Table of Contents

✨ Features

  • 🎯 Dynamic Dropdown - Livewire-powered searchable dropdowns with real-time filtering
  • 🆔 Unique ID Generator - Multiple ID generation strategies (6-digit & Base36)
  • 📱 Data Formatters - Format Pakistani phone numbers and CNIC
  • 📱 Responsive Design - Bootstrap-compatible components
  • Performance Optimized - Efficient database queries with debouncing
  • 🛠️ Highly Customizable - Extensive configuration options
  • 🔒 Secure - Built-in validation and error handling

🔧 Installation

Install the package via Composer:

composer require artflow-studio/snippets

Service Provider Registration

The package uses Laravel's auto-discovery feature. If you're using Laravel 5.5+, the service provider will be automatically registered.

Publish Assets (Optional)

php artisan vendor:publish --provider="ArtFlowStudio\Snippets\SnippetsServiceProvider"

🚀 Quick Start

Add the following line at the end of your <body> tag in your Blade layout:

@stack('scripts')

That's it! You're ready to use AF Web Snippets in your Laravel application.

📚 Components

🎯 Dynamic Dropdown (AFDropdown)

A powerful Livewire component for searchable dropdowns with real-time filtering, minimum search length, and elegant UI.

Basic Usage

<livewire:afdropdown 
    :model="App\Models\User::class" 
    column="name" 
    placeholder="Search users..." 
/>

Advanced Configuration

<livewire:a-f-dropdown 
    :model="App\Models\User::class" 
    column="name" 
    classes="form-control form-control-lg" 
    placeholder="Search users..."
    :min-search-length="2"
/>

Listening to Selection Events

document.addEventListener('livewire:init', function () {
    Livewire.on('afdropdown-selected', (data) => {
        console.log('Selected:', data.id, data.label, data.class);
        // Handle the selection
    });
});

AFDropdown Features

  • Real-time Search - Debounced search with 300ms delay
  • Minimum Search Length - Configurable minimum characters (default: 3)
  • Loading States - Visual feedback during search
  • Clear Button - Easy reset functionality
  • Keyboard Navigation - Accessible dropdown interaction
  • Bootstrap Compatible - Seamless integration with Bootstrap styling

Configuration Options

Option Type Default Description
model string required Eloquent model class
column string required Database column to search and display
classes string 'form-control' CSS classes for input
placeholder string 'Search...' Input placeholder text
min-search-length int 3 Minimum characters before search

🆔 Unique ID Generator

Generate unique identifiers for your models with multiple strategies and collision detection.

Basic Usage

// Generate unique ID for a model
$uniqueId = generateUniqueID(User::class, 'user_id');

// Generate 6-digit unique ID
$id = unique6digitID(); // Returns: "123456"

// Generate Base36 unique ID
$id = generateUniqueBase36ID(); // Returns: "AB12CD"

Advanced Usage

// In your model
class User extends Model
{
    protected static function boot()
    {
        parent::boot();
        
        static::creating(function ($model) {
            $model->user_id = generateUniqueID(self::class, 'user_id');
        });
    }
}

ID Generation Methods

  1. unique6digitID() - Generates 6-digit numeric IDs (100000-999999)
  2. generateUniqueBase36ID() - Generates Base36 IDs with timestamp encoding
  3. generateUniqueID($model, $column) - Generates unique IDs with collision checking

📱 Data Formatters

Format common data types for Pakistani users with intelligent detection and formatting.

Pakistani Phone Number Formatter

// Format Pakistani phone numbers
echo formatContactPK('03001234567');    // +923001234567
echo formatContactPK('00923001234567'); // +923001234567
echo formatContactPK('+923001234567');  // +923001234567
echo formatContactPK('923001234567');   // +923001234567

// International numbers pass through
echo formatContactPK('+12345678901');   // +12345678901

Pakistani CNIC Formatter

// Format Pakistani CNIC numbers
echo formatCnicPK('1234567890123');     // 12345-6789012-3
echo formatCnicPK('12345-6789012-3');   // 12345-6789012-3

// Handle special cases
echo formatCnicPK('PASSPORT123');       // PASSPORT123 (unchanged)

Usage in Models

class User extends Model
{
    // Automatically format phone on save
    public function setPhoneAttribute($value)
    {
        $this->attributes['phone'] = formatContactPK($value);
    }
    
    // Automatically format CNIC on save  
    public function setCnicAttribute($value)
    {
        $this->attributes['cnic'] = formatCnicPK($value);
    }
}

🎨 Customization

Styling AFDropdown

/* Custom dropdown styles */
.afdropdown-wrapper .dropdown-menu {
    border-radius: 8px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

.afdropdown-wrapper .dropdown-item:hover {
    background-color: #f8f9fa;
}

🔍 Examples

Dropdown with Event Handling

<livewire:a-f-dropdown 
    :model="App\Models\Category::class" 
    column="name" 
    placeholder="Select category..."
    wire:key="category-dropdown"
/>

<script>
document.addEventListener('livewire:init', function () {
    Livewire.on('afdropdown-selected', (data) => {
        // Update related dropdowns
        @this.set('selected_category_id', data.id);
        
        // Show success message
        toastr.success(`Selected: ${data.label}`);
    });
});
</script>

🛠️ Requirements

  • PHP >= 8.0
  • Laravel >= 9.0
  • Livewire >= 3.0
  • Bootstrap >= 5.0 (for styling)

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

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

📄 License

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

👥 Authors

🙏 Acknowledgments

  • Laravel community for the amazing framework
  • Livewire team for the reactive components
  • Bootstrap team for the UI framework
  • All contributors who help improve this package

Made with ❤️ for the Laravel community

⭐ Star us on GitHub | 🐛 Report Bug | 💡 Request Feature