Field Pack Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/field-pack
   

   Ensure your project meets the PHP 8.4+ requirement and has baks-dev/core (≥7.4) installed.

2. First Use Case Register the package in your Laravel service provider (e.g., AppServiceProvider):

   use BaksDev\FieldPack\FieldPackServiceProvider;
   
   public function register()
   {
       if ($this->app->environment('local')) {
           $this->app->register(FieldPackServiceProvider::class);
       }
   }
   

3. Basic Field Usage Access fields via the FieldPack facade or service container:

   use BaksDev\FieldPack\Facades\FieldPack;
   
   $textField = FieldPack::make('text')
       ->label('Username')
       ->required()
       ->value(old('username'));
   

4. Blade Integration Render fields in a Blade view:

   {!! $textField->render() !!}
   

Implementation Patterns

Core Workflows

1. Dynamic Field Generation Use the fluent interface to chain methods for field configuration:

   $field = FieldPack::make('select')
       ->name('status')
       ->options([
           'active' => 'Active',
           'inactive' => 'Inactive',
       ])
       ->selected(old('status', 'active'));
   

2. Form Integration Combine fields into a form structure:

   $form = FieldPack::form()
       ->add($textField)
       ->add($selectField)
       ->method('POST')
       ->action(route('profile.update'));
   

3. Validation Rules Attach Laravel validation rules:

   $emailField = FieldPack::make('email')
       ->rules('required|email:rfc,dns')
       ->errorMessage('The :attribute must be a valid email address.');
   

4. Conditional Fields Use JavaScript-based dependencies (via data-* attributes):

   $checkbox = FieldPack::make('checkbox')
       ->name('subscribe')
       ->label('Subscribe to newsletter');
   
   $emailField->dependsOn($checkbox->getName());
   

5. Custom Field Types Extend existing fields or create new ones:

   FieldPack::extend('custom_field', function () {
       return new CustomField();
   });
   

Integration Tips

1. Laravel Collective Compatibility Mimic Collective’s Form facade patterns for familiarity:

   // Instead of:
   Form::text('username')
   // Use:
   FieldPack::make('text')->name('username')
   

2. Livewire/Alpine Integration Attach Alpine.js events or Livewire model binding:

   $field->wireModel('user.username')
        ->alpine('x-data', '{}')
        ->alpineEvent('change', 'updateProfile');
   

3. Localization Use Laravel’s localization system for labels/placeholders:

   $field->label(__('field.username'))
        ->placeholder(__('field.username_placeholder'));
   

4. Asset Management Register field-specific assets (CSS/JS) via service provider:

   public function boot()
   {
       FieldPack::asset('css', asset('vendor/field-pack/styles.css'));
   }
   

Gotchas and Tips

Pitfalls

1. Field Pack Initialization

   • Issue: Fields may not render if FieldPackServiceProvider isn’t registered.
   • Fix: Ensure the provider is loaded in config/app.php or a service provider.

2. PHP 8.4+ Requirements

   • Issue: Older PHP versions will fail silently or throw errors.
   • Fix: Verify php -v and update your server if needed.

3. Missing baks-dev/core

   • Issue: The package relies on baks-dev/core for core functionality.
   • Fix: Install the dependency explicitly:

     composer require baks-dev/core:^7.4
     

4. Blade Escaping

   • Issue: Fields rendered with {{ }} may break HTML attributes.
   • Fix: Always use {{!! !!}} for field rendering:

     {!! $field->render() !!}
     

5. Validation Error Handling

   • Issue: Custom error messages may not display if validation fails silently.
   • Fix: Ensure withErrors() is called in your controller:

     return back()->withErrors($validator)->withInput();
     

Debugging

1. Field Dumping Inspect field configuration before rendering:

   dd($field->toArray());
   

2. View Debugging Enable Blade debugging in config/view.php:

   'debug' => env('APP_DEBUG', true),
   

3. JavaScript Console Check for errors in browser console when using dynamic fields (e.g., dependencies).

Extension Points

1. Custom Field Attributes Add arbitrary HTML attributes:

   $field->attr('data-custom', 'value')
        ->attr(['class' => 'form-control', 'data-toggle' => 'tooltip']);
   

2. Field Modifiers Extend field behavior via modifiers:

   FieldPack::modify('text', function ($field) {
       $field->attr('autocomplete', 'off');
   });
   

3. Event Listeners Hook into field events (e.g., rendering, rendered):

   FieldPack::listen('rendering', function ($field) {
       if ($field->getName() === 'password') {
           $field->attr('autocomplete', 'new-password');
       }
   });
   

4. Asset Overrides Override default assets in your service provider:

   FieldPack::asset('css', asset('custom/field-pack.css'));
   

Configuration Quirks

1. Default Values

   • Use value() for static values or default() for fallback values:

     $field->value('default_value')->default('fallback_value');
     

2. Disabled/Readonly States

   • Set via methods:

     $field->disabled()->readonly();
     

   • Or directly:

     $field->attr('disabled', true);
     

3. Field Groups Nest fields in containers:

   $group = FieldPack::group()
       ->add($textField)
       ->add($selectField)
       ->legend('User Details');
   

4. Localization Fallback Ensure __() or trans() is available in your views for labels/placeholders.

Performance Tips

1. Cache Field Configurations For reusable forms, cache field instances:

   $cachedField = cache()->remember('user_profile_field', now()->addHours(1), function () {
       return FieldPack::make('text')->name('username');
   });
   

2. Minimize Dynamic Fields Avoid generating fields dynamically in loops if possible; pre-configure them.

3. Asset Bundling Combine field-specific CSS/JS into a single file for production.