Smartform Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dobryprogramator/smartform-bundle
   

   For non-Flex projects, manually add the bundle to config/bundles.php:

   DobryProgramator\SmartformBundle\DobryProgramatorSmartformBundle::class => ['all' => true],
   

2. Configuration: Add to .env:

   SMARTFORM_CLIENT_ID=your_client_id_here
   

   Create config/packages/dobry_programator_smartform.yaml:

   dobry_programator_smartform:
       client_id: '%env(SMARTFORM_CLIENT_ID)%'
   

3. First Use Case: Inject the SmartformClient service into a controller/service:

   use DobryProgramator\SmartformBundle\Service\SmartformClient;
   
   public function __construct(private SmartformClient $smartform)
   {
   }
   
   public function submitForm(Request $request)
   {
       $response = $this->smartform->submitForm($request->request->all());
       return new JsonResponse($response);
   }
   

Implementation Patterns

Common Workflows

1. Form Submission: Use the SmartformClient to submit data to Smartform:

   $formData = [
       'field1' => 'value1',
       'field2' => 'value2',
   ];
   $result = $this->smartform->submitForm($formData);
   

2. Handling Responses: Process Smartform’s JSON response (e.g., redirect, store data):

   if ($result['success']) {
       $this->addFlash('success', 'Form submitted!');
       return $this->redirectToRoute('thank_you');
   }
   

3. Dynamic Form Fields: Fetch form metadata (if supported) via SmartformClient::getFormMetadata($formId).

4. Validation: Validate submitted data against Smartform’s schema before submission:

   $validator = $this->validator;
   $errors = $validator->validate($formData, $constraints);
   

Integration Tips

• Twig Integration: Embed Smartform forms in Twig templates using {{ form(doctrine.form) }} (if the bundle provides helpers).
• Event Listeners: Subscribe to SmartformEvents (if the bundle emits them) for post-submission logic:

  $dispatcher->addListener(SmartformEvents::POST_SUBMIT, function ($event) {
      $this->logger->info('Form submitted', ['data' => $event->getData()]);
  });
  

• API Calls: Use SmartformClient for non-form submissions (e.g., webhooks):

  $this->smartform->sendWebhook($payload);
  

Gotchas and Tips

Pitfalls

1. Deprecated/Unmaintained:

   • Last release in 2021; verify API compatibility with Smartform.cz’s current endpoints.
   • Check for breaking changes in Smartform’s API (e.g., authentication, field names).

2. Configuration Overrides:

   • Ensure client_id is correctly set in both .env and YAML. Priority is given to YAML.
   • Avoid hardcoding secrets; use %env() for security.

3. Error Handling:

   • Smartform may return non-JSON responses (e.g., HTML for errors). Validate responses:

     $response = json_decode($this->smartform->submitForm($data), true);
     if (json_last_error() !== JSON_ERROR_NONE) {
         throw new \RuntimeException('Invalid Smartform response');
     }
     

4. Rate Limiting:

   • Smartform may throttle requests. Implement retries with exponential backoff:

     use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
     use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;
     
     try {
         $response = $this->smartform->submitForm($data);
     } catch (TransportExceptionInterface | ClientExceptionInterface $e) {
         // Retry logic
     }
     

Debugging Tips

• Logging: Enable debug mode in config/packages/monolog.yaml to log Smartform requests/responses:

  handlers:
      smartform:
          type: stream
          path: "%kernel.logs_dir%/smartform.log"
          level: debug
  

  Wrap SmartformClient calls in a try-catch to log errors:

  try {
      $result = $this->smartform->submitForm($data);
  } catch (\Exception $e) {
      $this->logger->error('Smartform error', ['exception' => $e->getMessage()]);
  }
  

• Testing: Mock SmartformClient in PHPUnit:

  $mock = $this->createMock(SmartformClient::class);
  $mock->method('submitForm')->willReturn(['success' => true]);
  $this->controller->setSmartform($mock);
  

Extension Points

1. Custom Clients: Extend SmartformClient to add features (e.g., batch submissions):

   class CustomSmartformClient extends SmartformClient
   {
       public function submitBatch(array $forms): array
       {
           $results = [];
           foreach ($forms as $form) {
               $results[] = $this->submitForm($form);
           }
           return $results;
       }
   }
   

   Register as a service:

   services:
       App\Service\CustomSmartformClient:
           decorates: 'dobry_programator.smartform.client'
   

2. Event Dispatching: If the bundle lacks events, create a decorator to dispatch custom events:

   $decorated->submitForm($data);
   $dispatcher->dispatch(new SmartformEvent($data, $response));
   

3. Field Mapping: Override field names dynamically (e.g., for localization):

   $mappedData = array_map(function ($value, $key) {
       return [$this->mapField($key) => $value];
   }, $data, array_keys($data));