Relay Formalize Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require dbp/relay-formalize-bundle
   

   Ensure your config/bundles.php includes:

   return [
       // ...
       DigitalBlueprint\Relay\FormalizeBundle\FormalizeBundle::class => ['all' => true],
   ];
   

2. Configure the Bundle Publish the default config:

   php bin/console dbp:relay-formalize:install
   

   Update config/packages/dbp_relay_formalize.yaml with your database and authorization settings.

3. First Use Case: Basic Form Define a form schema in YAML (e.g., config/forms/event_registration.yaml):

   name: event_registration
   title: "Event Registration"
   fields:
     - { name: "name", type: "text", label: "Your Name" }
     - { name: "email", type: "email", label: "Email" }
   

   Register the form in a controller:

   use DigitalBlueprint\Relay\FormalizeBundle\Form\FormManager;
   
   public function showForm(FormManager $formManager)
   {
       $form = $formManager->getForm('event_registration');
       return $this->render('form/show.html.twig', ['form' => $form]);
   }
   

Implementation Patterns

Core Workflows

1. Form Definition & Validation

   • Use YAML/JSON/XML schemas for declarative form definitions (stored in config/forms/).
   • Leverage built-in validators (e.g., required, email, regex) or extend with custom rules via ValidationExtension.
   • Example:

     fields:
       - { name: "age", type: "integer", validators: ["min:18"] }
     

2. Submission Lifecycle

   • Drafts: Enable drafts in schema (allow_drafts: true) and use the SubmissionManager to save drafts:

     $submission = $submissionManager->createDraft('event_registration', $user);
     $submission->setData(['name' => 'John']);
     $submissionManager->saveDraft($submission);
     

   • Submission Events: Listen to events (e.g., submission.created) via Symfony’s event dispatcher:

     $eventDispatcher->addListener(SubmissionEvents::SUBMISSION_CREATED, function (SubmissionEvent $event) {
         // Send confirmation email
     });
     

3. Authorization

   • Integrate with DbpRelayAuthorizationBundle to restrict form access:

     # config/packages/dbp_relay_authorization.yaml
     access_control:
       - { path: ^/form/event_registration, roles: ROLE_USER }
     

   • Use AuthorizationChecker in controllers:

     if (!$authorizationChecker->isGranted('ROLE_ADMIN')) {
         throw $this->createAccessDeniedException();
     }
     

4. File Uploads

   • Define file fields in schema:

     fields:
       - { name: "document", type: "file", upload_dir: "uploads/event_registrations" }
     

   • Access uploaded files via Submission entity:

     $filePath = $submission->getFilePath('document');
     

5. Exports

   • Export submissions to PDF/Excel using the Exporter service:

     $exporter = $this->container->get('dbp_relay_formalize.exporter');
     $pdf = $exporter->exportToPdf($submissions, 'event_registration');
     

Integration Tips

• API Integration: Use the Relay API Server to expose forms/submissions as REST endpoints. Configure routes in config/routes.yaml:

  dbp_relay_formalize:
      resource: "@DbpRelayFormalizeBundle/Resources/config/routes.yaml"
  

• Frontend: Pair with the Formalize App for a React-based UI. Use Symfony’s Webpack Encore for asset compilation.
• Testing: Mock FormManager and SubmissionManager in PHPUnit:

  $formManager = $this->createMock(FormManager::class);
  $formManager->method('getForm')->willReturn($form);
  $this->container->set(FormManager::class, $formManager);
  

Gotchas and Tips

Pitfalls

1. Schema Caching

   • Forms are cached after installation. Clear the cache when updating schemas:

     php bin/console cache:clear
     

   • Override cache behavior in config/packages/dbp_relay_formalize.yaml:

     cache:
         enabled: false
     

2. File Uploads

   • Ensure upload_dir in the schema is writable by the web server (e.g., chmod -R 775 uploads/).
   • Handle large files by configuring PHP’s upload_max_filesize and post_max_size in php.ini.

3. Authorization Conflicts

   • If using both FormalizeBundle and AuthorizationBundle, ensure roles are consistent across bundles. Debug with:

     $this->container->get('debug.authorization_checker')->isGranted('ROLE_ADMIN');
     

4. Submission Events

   • Events may fire asynchronously. Use SubmissionEvent::getSubmission() to access data in listeners.

Debugging

• Form Validation Errors: Check Symfony’s profiler (/_profiler) for validation messages.
• Database Issues: Enable SQL logging in config/packages/dev/dbp_relay_formalize.yaml:

  database:
      logging: true
  

• Frontend Errors: Clear the frontend app’s cache (npm run build) if styles/scripts fail to load.

Extension Points

1. Custom Validators

   • Create a validator class and register it in services.yaml:

     services:
         App\Validator\Constraints\CustomValidator:
             tags: [validator.constraint_validator]
     

   • Reference in schema:

     fields:
       - { name: "custom_field", type: "text", validators: ["@App\Validator\Constraints\CustomValidator"] }
     

2. Submission Exporters

   • Extend the Exporter service by overriding the exportToPdf/exportToExcel methods in a custom service:

     class CustomExporter extends Exporter
     {
         public function exportToPdf(array $submissions, string $formName): string
         {
             // Custom logic
             return parent::exportToPdf($submissions, $formName);
         }
     }
     

   • Register the service in services.yaml and set it as the default exporter in config.

3. Dynamic Forms

   • Use the FormBuilder service to create forms programmatically:

     $form = $formBuilder->buildForm('dynamic_form', [
         'fields' => [
             ['name' => 'dynamic_field', 'type' => 'text', 'label' => 'Dynamic Label']
         ]
     ]);
     

4. Multi-Stage Workflows

   • Implement state machines for submissions by extending the Submission entity and using Symfony’s StateMachine component:

     $submission->getStateMachine()->apply('submit');
     

   • Listen to state transitions:

     $eventDispatcher->addListener(SubmissionEvents::SUBMISSION_STATE_CHANGED, function (StateEvent $event) {
         // Handle state change (e.g., send approval email)
     });
     

Configuration Quirks

• Default Form Storage: Submissions are stored in the submissions table by default. Customize the table name in config:

  database:
      submission_table: custom_submissions
  

• File Storage: Override the default file storage adapter (e.g., for S3) by implementing FileStorageInterface and configuring in services.yaml:

  services:
      dbp_relay_formalize.file_storage:
          class: App\Service\S3FileStorage