Submission Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require elasticms/submission-bundle
   

   Ensure EMSFormBundle is also installed (core dependency).

2. Configure the Bundle: Add to config/bundles.php:

   return [
       // ...
       ElasticMS\SubmissionBundle\ElasticMSSubmissionBundle::class => ['all' => true],
   ];
   

3. Define a Submission Configuration: Create a YAML/JSON config file (e.g., config/submissions/contact.yaml):

   name: "contact_form"
   handler: "database"  # or "api", "event", etc.
   rules:
       - { field: "email", validator: "required|email" }
   

4. Route a Form Submission: In routes/web.php:

   use ElasticMS\SubmissionBundle\Routing\SubmissionRouter;
   
   Route::post('/submit-contact', [SubmissionRouter::class, 'handle'])
       ->name('ems.submission.handle');
   

5. First Submission Test: Submit a form via EMSFormBundle with the config key (contact_form). Verify the submission appears in the database or triggers the configured handler.

First Use Case: Database Storage

1. Create a Config:

   # config/submissions/newsletter.yaml
   name: "newsletter_signup"
   handler: "database"
   model: "App\Models\NewsletterSubscriber"
   fields:
       email: "email"
       name: "name"
   

2. Submit via Form: Use EMSFormBundle to render a form targeting this config. On submission, the bundle will:

   • Validate fields (e.g., email must be valid).
   • Create a new NewsletterSubscriber record.

3. Debugging: Check Laravel logs (storage/logs/laravel.log) for validation errors or use Tinker to inspect the submitted data:

   php artisan tinker
   >>> \ElasticMS\SubmissionBundle\Submission::findLatest();
   

Where to Look First

• Documentation: Start here for config schemas, handlers, and event references.
• config/submissions/: Default location for submission configs. Override via config/elasticms_submission.yaml.
• src/Handler/: Core handlers (e.g., DatabaseHandler, ApiHandler). Extend these for custom logic.
• Events: Listen for submission.created, submission.validated, or submission.failed in EventServiceProvider.

Implementation Patterns

Workflow: Config-Driven Submission

1. Define the Config:

   # config/submissions/lead_capture.yaml
   name: "lead_form"
   handler: "api"
   api:
       url: "https://api.example.com/leads"
       method: "POST"
       auth: "bearer: {{ env('API_TOKEN') }}"
   validation:
       - { field: "phone", validator: "digits:10" }
   

2. Submit via Form:

   // In a controller or EMSFormBundle config
   $submission = new \ElasticMS\SubmissionBundle\Submission('lead_form');
   $submission->setData($request->all());
   $submission->handle();
   

3. Extend Handlers: Create a custom handler (e.g., SlackHandler) by extending AbstractHandler:

   namespace App\Handlers;
   
   use ElasticMS\SubmissionBundle\Handler\AbstractHandler;
   
   class SlackHandler extends AbstractHandler
   {
       public function handle(array $data)
       {
           // Send to Slack API
           Http::post('https://slack.com/api/chat.postMessage', [
               'text' => "New lead: {$data['email']}",
           ]);
       }
   }
   

   Register it in config/elasticms_submission.yaml:

   handlers:
       slack: App\Handlers\SlackHandler
   

Integration with Laravel Ecosystem

1. Events: Listen for submission events in EventServiceProvider:

   protected $listen = [
       'ElasticMS\SubmissionBundle\Events\SubmissionCreated' => [
           \App\Listeners\LogSubmission::class,
       ],
   ];
   

2. Queues: Dispatch async processing:

   use ElasticMS\SubmissionBundle\Events\SubmissionProcessed;
   
   SubmissionProcessed::dispatch($submission)
       ->onQueue('submissions');
   

3. Validation: Extend validation rules by creating a custom validator:

   namespace App\Rules;
   
   use Illuminate\Contracts\Validation\Rule;
   
   class CustomRule implements Rule
   {
       public function passes($attribute, $value) { /* ... */ }
       public function message() { /* ... */ }
   }
   

   Reference it in config:

   validation:
       - { field: "custom_field", validator: "custom_rule" }
   

Common Patterns

Gotchas and Tips

Pitfalls

1. Symfony-Laravel Container Conflicts:

   • Issue: The bundle uses Symfony’s DependencyInjection, which may clash with Laravel’s container.
   • Fix: Bind Symfony services manually in AppServiceProvider:

     $this->app->bind(
         'elasticms.submission.handler.database',
         \ElasticMS\SubmissionBundle\Handler\DatabaseHandler::class
     );
     

2. Missing EMSFormBundle:

   • Issue: The bundle assumes EMSFormBundle is installed. Without it, form submissions won’t trigger the bundle’s routers.
   • Fix: Manually route submissions via middleware:

     Route::post('/submit', function (Request $request) {
         $submission = new \ElasticMS\SubmissionBundle\Submission('your_config');
         $submission->setData($request->all());
         return $submission->handle();
     });
     

3. Validation Errors:

   • Issue: Custom validators may fail silently or return unclear errors.
   • Fix: Enable debug mode and check logs:

     config(['debug' => true]);
     

     Or extend the validator to throw Laravel-specific exceptions.

4. Handler Order:

   • Issue: Handlers execute in config order, but errors in early handlers may halt the chain.
   • Fix: Use try-catch in handlers or configure fail_on_error: false in the bundle’s YAML.

Debugging Tips

1. Log Submissions: Add a listener to log all submissions:

   // app/Listeners/LogSubmission.php
   public function handle(SubmissionCreated $event)
   {
       \Log::info('Submission created', ['data' => $event->getData()]);
   }
   

2. Validate Configs: Use the validate command to check YAML syntax:

   php artisan elasticms:submission:validate config/submissions/your_config.yaml
   

3. Inspect Handlers: Dump handler execution:

   $handler = $this->container->get('elasticms.submission.handler.database');
   \Log::debug('Handler config:', [$handler->getConfig()]);
   

Extension Points

1. Custom Handlers:

   • Extend AbstractHandler and register in config/elasticms_submission.yaml:

     handlers:
         custom: App\Handlers\CustomHandler
     

2. Dynamic Configs: Load configs from a database or API:

   // Override the config loader in a service provider
   $this->app->bind('elasticms.submission.config_loader', function () {
       return new \App\Services\DynamicConfigLoader();
   });
   

3. Event Overrides: Publish and override bundle events:

   php artisan vendor:publish --tag=elasticms-submission-events
   

   Then extend the published event classes.

Configuration Quirks

1. Environment Variables: Use double curly braces for nested env vars:

   api:
       url: "{{ env('APP_URL') }}/api/{{ env('API_VERSION') }}/leads"
   

2. Default Values: Override defaults in config/elasticms_submission.yaml:

   default