Workflow Reviser Laravel Package

Getting Started

This package extends Laravel's form handling capabilities by providing reusable, type-specific form components. To get started, install via Composer:

composer require vendor/package-name

Publish the package's assets (if applicable) and configuration:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"

The package now supports checkboxes, date inputs, datetime inputs, and countable fields (e.g., for numeric ranges or counters). For a first use case, try rendering a date picker:

use Vendor\PackageName\Components\DateInput;

DateInput::make('published_at')
    ->label('Publication Date')
    ->required()
    ->render();

Implementation Patterns

1. Component Composition

Leverage the package's components as building blocks for complex forms. For example, combine DateInput with Checkbox for conditional date logic:

$form = Form::open();
$form->add(
    Checkbox::make('is_published')
        ->label('Publish immediately?')
        ->onChange("this.checked ? $('#published_at').prop('disabled', false) : $('#published_at').prop('disabled', true)")
);
$form->add(
    DateInput::make('published_at')
        ->disabled()
        ->label('Scheduled Date')
);
$form->submit('Save');

2. Validation Integration

Use the package's components with Laravel's validation rules. For DateTime inputs, pair with date_format:

$request->validate([
    'event_date' => 'required|date_format:Y-m-d\TH:i:s',
]);

For Countable fields (e.g., quantity), use integer|min:1:

$request->validate([
    'quantity' => 'integer|min:1|max:100',
]);

3. Dynamic Field Generation

Generate fields dynamically based on user roles or data:

if (auth()->user()->can('manage_dates')) {
    $form->add(DateTimeInput::make('scheduled_at')->label('Scheduled Time'));
} else {
    $form->add(DateInput::make('scheduled_date')->label('Scheduled Date'));
}

4. Blade Integration

Embed components in Blade views for reusable templates:

@component('vendor.package-name::components.date-input', [
    'name' => 'event_date',
    'label' => 'Event Date',
    'required' => true,
])
@endcomponent

5. API/JSON Responses

For API responses, serialize components to JSON for frontend hydration:

return response()->json([
    'fields' => [
        [
            'name' => 'user_count',
            'type' => 'countable',
            'label' => 'User Count',
            'min' => 0,
            'max' => 1000,
        ],
    ],
]);

Gotchas and Tips

1. Date/Datetime Formatting

• Timezone Awareness: Ensure DateTime inputs respect the user's timezone or explicitly set one:

  DateTimeInput::make('event_time')
      ->timezone('America/New_York')
      ->render();
  

• Database Storage: Store dates as DATE (MySQL) or date (PostgreSQL) and datetimes as DATETIME/TIMESTAMP to avoid precision issues.

2. Countable Fields

• Numeric Validation: Always validate Countable fields on the backend, as frontend values can be tampered with:

  $request->validate([
      'item_count' => 'required|integer|between:0,9999',
  ]);
  

• UI Feedback: Use CSS classes (e.g., input-error) to highlight invalid counts:

  CountableInput::make('quantity')
      ->min(1)
      ->max(10)
      ->class('form-control {{ $errors->has('quantity') ? 'is-invalid' : '' }}')
      ->render();
  

3. Checkbox Quirks

• Boolean Conversion: Checkboxes default to 1/0 in Laravel. Explicitly cast to boolean if needed:

  $isActive = $request->boolean('is_active'); // Converts "1"/"0" to true/false
  

• Multiple Checkboxes: For multi-select checkboxes, use CheckboxGroup (if available) or manually handle arrays:

  $request->validate([
      'tags' => 'sometimes|array',
      'tags.*' => 'string|max:255',
  ]);
  

4. Asset Dependencies

• JavaScript/CSS: If the package includes date pickers (e.g., Flatpickr), ensure dependencies are loaded:

  @vite(['resources/js/app.js', 'vendor/package-name/flatpickr.css'])
  

• Localization: For date inputs, include locale scripts:

  <script src="//cdn.jsdelivr.net/npm/flatpickr"></script>
  <script src="//cdn.jsdelivr.net/npm/flatpickr/dist/l10n/{{ app()->getLocale() }}.js"></script>
  

5. Extension Points

• Custom Components: Extend the package by creating child classes:

  class CustomDateInput extends DateInput {
      public function withCustomAttribute($value) {
          $this->attributes['data-custom'] = $value;
          return $this;
      }
  }
  

• Event Hooks: Listen for component events (if the package supports them) to modify behavior:

  \Vendor\PackageName\Events\DateInputRendering::listen(function ($event) {
      $event->component->addClass('custom-date-class');
  });
  

6. Debugging

• Inspect Rendered HTML: Use browser dev tools to verify attributes/classes are applied correctly.
• Log Component Data: Temporarily log component data to debug:

  \Log::debug('Component data:', [
      'name' => $component->name,
      'attributes' => $component->attributes,
  ]);
  

• Check for Conflicts: Disable other packages (e.g., Laravel Collective) to isolate issues if components render incorrectly.

7. Performance

• Lazy Loading: For large forms, lazy-load components or use AJAX to fetch dynamic fields.
• Caching: Cache repeated component configurations if used across multiple views:

  $cachedComponent = cache()->remember("form.component.{$userId}", now()->addHours(1), function () use ($userId) {
      return DateInput::make("user_{$userId}_date")->label('Custom Date');
  });