Magicpro Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require dixipro/magicpro
   php artisan vendor:publish --provider="Dixipro\Magicpro\MagicproServiceProvider" --tag="magicpro-config"
   

2. Define a Form Schema Create a config file at config/magicpro/forms/your_form.php:

   return [
       'title' => 'Contact Us',
       'fields' => [
           'name' => [
               'type' => 'text',
               'label' => 'Your Name',
               'rules' => 'required|string|max:255',
           ],
           'email' => [
               'type' => 'email',
               'label' => 'Email',
               'rules' => 'required|email',
           ],
       ],
       'submit_button' => 'Send Message',
   ];
   

3. First Use Case: Render a Form In a Blade template:

   @php
       $form = \Dixipro\Magicpro\Facades\Magicpro::form('your_form');
   @endphp
   {!! $form->render() !!}
   

4. Handle Submissions In your controller:

   use Dixipro\Magicpro\Facades\Magicpro;
   
   public function store(Request $request)
   {
       $form = Magicpro::form('your_form');
       $validated = $form->validate($request->all());
   
       if ($form->fails()) {
           return back()->withErrors($form->errors());
       }
   
       // Process data (e.g., save to DB)
       $form->save();
   
       return redirect()->route('thank-you');
   }
   

5. Route the Form In routes/web.php:

   Route::get('/contact', [ContactController::class, 'create']);
   Route::post('/contact', [ContactController::class, 'store']);
   

Where to Look First

• Configuration: config/magicpro.php (default settings, field types, storage)
• Facades: \Dixipro\Magicpro\Facades\Magicpro (core methods like form(), validate(), save())
• Field Types: Supported types in config/magicpro/field_types.php (extendable)
• Events: FormSubmitted, FormValidated (for custom logic)

Implementation Patterns

Core Workflows

1. Schema-Driven Development

• Pattern: Define forms entirely in config files (YAML/JSON/PHP) to separate UI from logic.
• Example:

  // config/magicpro/forms/user_profile.php
  return [
      'fields' => [
          'bio' => [
              'type' => 'textarea',
              'label' => 'About You',
              'rules' => 'nullable|max:500',
              'hint' => 'Tell us about yourself',
          ],
          'avatar' => [
              'type' => 'file',
              'label' => 'Profile Picture',
              'rules' => 'nullable|image|mimes:jpeg,png|max:2048',
          ],
      ],
      'conditional' => [
          'avatar' => ['show' => ['bio' => '!=', '']], // Show if bio is not empty
      ],
  ];
  

• Integration Tip: Use Laravel’s config() helper to load schemas dynamically:

  $schema = config("magicpro.forms.{$formName}");
  $form = Magicpro::form($formName)->setSchema($schema);
  

2. Dynamic Field Handling

• Pattern: Access form fields dynamically to build flexible UIs.
• Example:

  // In Blade: Loop through fields dynamically
  @foreach($form->fields() as $name => $field)
      <div class="form-group">
          <label for="{{ $name }}">{{ $field['label'] }}</label>
          {!! $form->field($name)->render() !!}
          @if($errors->has($name))
              <span class="text-red-500">{{ $errors->first($name) }}</span>
          @endif
      </div>
  @endforeach
  

• Workflow:
  1. Define fields in schema.
  2. Use $form->field($name) to render individual fields.
  3. Access metadata via $form->getField($name)['rules'].

3. Validation and Error Handling

• Pattern: Leverage Laravel’s validation with MagicPro’s wrapper.
• Example:

  public function update(Request $request, $id)
  {
      $form = Magicpro::form('user_profile');
      $validated = $form->validate($request->all());
  
      if ($form->fails()) {
          return back()
              ->withInput()
              ->withErrors($form->errors());
      }
  
      // Proceed with update
      $user->update($validated);
  }
  

• Integration Tip: Extend validation with custom rules:

  $form->addRule('custom_field', 'custom_rule');
  

4. Conditional Logic

• Pattern: Show/hide fields based on user input.
• Example:

  // In schema
  'conditional' => [
      'address' => ['show' => ['country' => '!=', 'US']],
      'tax_id' => ['show' => ['business_type' => '=', 'llc']],
  ],
  

• Dynamic Evaluation:

  if ($form->shouldShow('address')) {
      $form->field('address')->render();
  }
  

5. Storage and Retrieval

• Pattern: Save form data to Eloquent models or custom storage.
• Example:

  // Save to a model
  $form->save(new User());
  
  // Or use a custom storage handler
  $form->setStorageHandler(function ($data) {
      // Custom logic (e.g., API call, database insert)
  });
  

• Integration Tip: Use events to hook into storage:

  event(new FormSubmitted($form));
  

6. API-Driven Forms

• Pattern: Expose forms as REST/GraphQL endpoints.
• Example:

  // Controller
  public function getFormSchema($formName)
  {
      return response()->json(Magicpro::form($formName)->getSchema());
  }
  
  public function submitForm(Request $request)
  {
      $form = Magicpro::form($request->form_name);
      $validated = $form->validate($request->all());
  
      if ($form->fails()) {
          return response()->json(['errors' => $form->errors()], 422);
      }
  
      $form->save();
      return response()->json(['success' => true]);
  }
  

• Frontend Integration: Use fetch() to load schemas dynamically:

  async function loadForm(formName) {
      const response = await fetch(`/api/forms/${formName}/schema`);
      const schema = await response.json();
      renderForm(schema);
  }
  

7. Multi-Step Forms

• Pattern: Split forms into logical steps with session persistence.
• Example:

  // Step 1: Personal Info
  $form = Magicpro::form('multi_step')->step('personal');
  $form->render();
  
  // Step 2: Address (next request)
  $form = Magicpro::form('multi_step')->step('address');
  $form->validate($request->all());
  

• Integration Tip: Use Laravel’s session() to store step progress:

  session()->put('form_progress', ['step' => 'address']);
  

8. Webhook Integrations

• Pattern: Trigger actions on form submission (e.g., Slack alerts, CRM updates).
• Example:

  // In a service provider
  Magicpro::extend(function ($form) {
      $form->onSubmit(function ($data) {
          // Send to Slack
          Http::post('https://slack.com/api/chat.postMessage', [
              'text' => "New form submission: " . json_encode($data),
          ]);
      });
  });
  

Integration Tips

Laravel Ecosystem

• Validation: Use Laravel’s built-in rules (e.g., unique:users|email) in schemas.
• Authorization: Gate form access:

  if (!Gate::allows('view-form', $formName)) {
      abort(403);
  }
  

• Localization: Translate field labels:

  'label' => __('forms.contact.name'),
  

• Testing: Use Laravel’s testing helpers:

  $response = $this->post('/contact', ['name' => 'Test']);
  $response->assertSessionHasNoErrors();
  

Frontend Integration

• Blade: Use @include('magicpro::form') for default rendering.
• Livewire/Alpine: Combine with frontend frameworks for dynamic UX:

  <div x-data="{ open: false }">
      <button @click