README

ArtisanPack UI Forms is a comprehensive form builder and management package for Laravel applications. Built on Livewire 3, it provides a drag-and-drop form builder, submission management, email notifications, file uploads, multi-step forms, conditional logic, and webhook integrations.

🚀 Quick Start

Installation

# Install the package
composer require artisanpack-ui/forms

# Publish configuration and assets
php artisan vendor:publish --provider="ArtisanPackUI\Forms\FormsServiceProvider"

# Run migrations
php artisan migrate

Basic Usage

<!-- Display a form by slug -->
<livewire:forms::form-renderer slug="contact" />

<!-- Or by form ID -->
<livewire:forms::form-renderer :form-id="1" />

✨ Key Features

• 🎨 Visual Form Builder: Drag-and-drop interface for creating forms without code
• 📝 20+ Field Types: Text, email, textarea, select, checkbox, radio, file upload, date, time, and more
• 📊 Submission Management: View, export, and manage form submissions with ease
• 📧 Email Notifications: Admin notifications and autoresponders with template support
• 📁 Secure File Uploads: Private file storage with MIME validation and size limits
• 📑 Multi-Step Forms: Create wizard-style forms with step navigation
• 🔀 Conditional Logic: Show/hide fields and steps based on user input
• 🔗 Webhook Integration: Send form data to external services with HMAC signatures
• 🛡️ Spam Protection: Built-in honeypot fields and rate limiting
• 🔒 Authorization: Policy-based access control with ownership support
• 📤 Export Options: Export submissions to CSV format

🧩 Components

Livewire Components

Available Field Types

Basic Fields: Text, Email, URL, Phone, Number, Password, Hidden

Text Fields: Textarea, Rich Text Editor

Selection Fields: Select, Multi-Select, Checkbox, Radio, Toggle

Date/Time Fields: Date, Time, DateTime

File Fields: File Upload, Multiple Files

Layout Fields: Heading, Paragraph, Divider

📖 Documentation

Comprehensive documentation is available in our Documentation Wiki:

• Installation Guide - Detailed setup instructions
• Configuration - All configuration options
• Form Builder - Creating forms
• Form Renderer - Displaying forms
• API Reference - Models, services, and events

⚙️ Configuration

Publish the configuration file:

php artisan vendor:publish --tag=forms-config

Environment Variables

The package supports the following environment variables:

Configuration Options

Key configuration options in config/artisanpack/forms.php:

return [
    // Admin panel settings
    'admin' => [
        'prefix' => 'admin/forms',
        'middleware' => ['web', 'auth'],
    ],

    // File upload settings
    'uploads' => [
        'disk' => 'form-uploads',
        'max_size' => 10240, // 10MB in KB
        'allowed_mimes' => ['image/jpeg', 'image/png', 'application/pdf'],
    ],

    // Submission settings
    'submissions' => [
        'store_submissions' => true,
        'retention_days' => null, // null = keep forever
    ],

    // Spam protection
    'spam_protection' => [
        'honeypot' => ['enabled' => true],
        'rate_limit' => ['enabled' => true, 'max_attempts' => 5],
    ],
];

🔧 Artisan Commands

# Prune old submissions based on retention settings
php artisan forms:prune-submissions

# Prune submissions older than specific days
php artisan forms:prune-submissions --days=90

📦 Requirements

• PHP 8.2 or higher
• Laravel 11, 12, or 13 (Laravel 13 requires PHP 8.3+)
• Livewire 3.6+

🤝 Dependencies

This package integrates with the ArtisanPack UI ecosystem:

• artisanpack-ui/livewire-ui-components - UI components
• artisanpack-ui/security - Input sanitization and security
• artisanpack-ui/accessibility - Accessibility utilities
• artisanpack-ui/hooks - WordPress-style hooks for extensibility

🎯 Events

The package dispatches events for key actions:

use ArtisanPackUI\Forms\Events\FormCreated;
use ArtisanPackUI\Forms\Events\FormSubmitted;
use ArtisanPackUI\Forms\Events\SubmissionDeleted;

// Listen for form submissions
Event::listen(FormSubmitted::class, function ($event) {
    // $event->submission contains the submission
    // $event->form contains the form
});

🤖 AI features

The Forms package ships four opt-in AI agents that plug into the artisanpack-ui/ai feature registry. Install artisanpack-ui/ai (v1.0+) and configure credentials to enable them; each feature no-ops when its toggle is off, so upgrades are non-breaking.

Each agent is invoked the same way — construct it with for() and call run():

use ArtisanPackUI\Forms\Ai\Agents\SpamDetectionAgent;

$result = SpamDetectionAgent::for([
    'fields' => $submission->data_array,
    'meta'   => [
        'ip_country'          => $submission->ip_country,
        'submission_speed_ms' => $submission->submission_speed_ms,
    ],
])->run();
// [ 'spam_score' => int, 'verdict' => 'ham'|'suspicious'|'spam', 'reasons' => string[] ]

Each feature also ships a Livewire trigger component you can drop into the admin surface. Components no-op when the feature toggle is off:

<livewire:forms::ai-spam-check
    :submission-id="$submission->id"
    :fields="$submission->data_array"
    :meta="[ 'ip_country' => $submission->ip_country ]"
/>

<livewire:forms::ai-submission-summary
    form-name="Contact us"
    window="weekly"
    :submissions="$submissions"
/>

<livewire:forms::ai-response-classifier
    :submission-id="$submission->id"
    :fields="$submission->data_array"
    :available-categories="[ 'support-request', 'sales-inquiry', 'feedback', 'bug-report' ]"
/>

<livewire:forms::ai-smart-field-validator
    field-name="address"
    field-label="Address"
    field-kind="address"
    :value="$address"
    :context="[ 'city' => $city, 'state' => $state ]"
/>

See the AI RFC for the shared registry, toggle, and credential story across ArtisanPack UI packages.

🔌 Extensibility

Add custom field types using filter hooks:

use function addFilter;

addFilter('forms.field_types', function (array $types) {
    $types['my-custom-field'] = [
        'label' => 'My Custom Field',
        'view' => 'my-package::fields.custom',
        'settings' => ['option1', 'option2'],
    ];
    return $types;
});

🤝 Contributing

Contributions are welcome! To contribute:

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 Merge Request

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting merge requests.

📄 License

ArtisanPack UI Forms is open-sourced software licensed under the GPL-3.0-or-later license.