Sulu Contact Account Extra Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require alengo/sulu-contact-account-extra-bundle
   

   Register the bundle in config/bundles.php and import routes in config/routes/sulu_admin.yaml.

2. Database Migration:

   bin/adminconsole doctrine:migrations:diff
   bin/adminconsole doctrine:migrations:migrate
   

3. Create Form: Define a form in config/forms/contact_additional_data.xml (or account_additional_data.xml) with your desired fields.

4. Verify:

   • Navigate to Contacts or Accounts in Sulu Admin.
   • Check for the "Additional Data" tab (default title: sulu_admin.app.additional_data).

First Use Case

Add a custom field (e.g., externalId) to the Additional Data tab for Contacts:

<!-- config/forms/contact_additional_data.xml -->
<form xmlns="...">
    <key>contact_additional_data</key>
    <properties>
        <property name="externalId" type="text_line" mandatory="false">
            <meta>
                <title lang="en">External ID</title>
            </meta>
        </property>
    </properties>
</form>

Now, when editing a contact, the field appears under the Additional Data tab.

Implementation Patterns

Workflows

1. Field Management:

   • Use the provided form XML to define fields dynamically.
   • Example: Add a dropdown for customerTier:

     <property name="customerTier" type="select">
         <meta>
             <title lang="en">Customer Tier</title>
         </meta>
         <options>
             <option value="bronze">Bronze</option>
             <option value="silver">Silver</option>
             <option value="gold">Gold</option>
         </options>
     </property>
     

2. API Integration:

   • Fetch or update additional data via the provided endpoints:

     GET /admin/api/contact-additional-data/123
     PUT /admin/api/contact-additional-data/123 {"externalId": "ABC123"}
     

   • Useful for syncing with external systems (e.g., CRM).

3. Custom Entities:

   • Extend the bundle’s entities if you need project-specific logic:

     alengo_contact_account_extra:
         contact:
             entity_class: App\Entity\CustomContact
     

   • Ensure CustomContact extends Alengo\SuluContactAccountExtraBundle\Entity\Contact.

4. Localization:

   • Translate form field titles in the XML <meta> tags:

     <meta>
         <title lang="en">External ID</title>
         <title lang="de">Externe ID</title>
     </meta>
     

Integration Tips

• Validation: Add validation rules in the form XML (e.g., mandatory="true" or regex patterns).
• Permissions: Leverage Sulu’s existing permission system to restrict access to the Additional Data tab.
• Frontend: Use the API endpoints to fetch additional data in your frontend (e.g., Vue.js/Symfony UX):

  // Fetch contact additional data
  await fetch(`/admin/api/contact-additional-data/${contactId}`)
    .then(res => res.json())
    .then(data => console.log(data));
  

• Migrations: If extending the additionalData column later, use Doctrine migrations:

  bin/adminconsole make:migration
  

Gotchas and Tips

Pitfalls

1. Form Key Mismatch:

   • Ensure the key in your form XML matches the form_key in the bundle config (default: contact_additional_data).
   • Example error: Form not appearing if key="wrong_key" but config uses contact_additional_data.

2. Database Schema:

   • The additionalData column is added as a JSON type. Ensure your database supports it (e.g., PostgreSQL, MySQL 5.7+).
   • If using SQLite, verify compatibility or switch to a supported DB.

3. Caching:

   • Sulu’s admin API may cache responses. Clear cache after changes:

     bin/adminconsole cache:clear
     

4. Entity Overrides:

   • If extending entity_class, ensure the new entity:
     • Uses the same table name (co_contacts/co_accounts).
     • Includes the additionalData property as a JsonType column.

5. API Endpoints:

   • The endpoints return the entire JSON blob. Avoid large payloads in production.
   • Example: Return only specific fields in your frontend:

     const { externalId, customerTier } = await res.json();
     

Debugging

• Missing Tab:

  • Check if the bundle is enabled in bundles.php.
  • Verify the form XML exists in config/forms/ and has the correct key.
  • Look for errors in var/log/dev.log.

• API 404 Errors:

  • Ensure routes are imported in sulu_admin.yaml.
  • Confirm the entity ID exists in the database.

• JSON Serialization:

  • If additionalData appears as null or malformed, check:
    • The form submission is valid (no JS errors).
    • The PUT request sends a valid JSON payload.

Extension Points

1. Custom Data Processing:

   • Override the bundle’s services to modify how additionalData is handled:

     # config/services.yaml
     Alengo\SuluContactAccountExtraBundle\Service\AdditionalDataHandler:
         arguments:
             $customLogic: '@app.custom.additional_data_handler'
     

2. Dynamic Forms:

   • Use Symfony’s form builder to generate the form XML dynamically (e.g., based on user roles):

     // src/EventListener/FormBuilderListener.php
     public function onKernelRequest(GetResponseEvent $event) {
         if ($event->isMasterRequest()) {
             $form = $this->createFormBuilder()
                 ->add('dynamicField', TextType::class, ['required' => false])
                 ->getForm();
             // Save to XML or render dynamically.
         }
     }
     

3. Webhook Triggers:

   • Listen for pre_update/post_update events on Contact/Account to trigger actions when additionalData changes:

     // src/EventSubscriber/AdditionalDataSubscriber.php
     public function onPreUpdate(PreUpdateEventArgs $args) {
         $entity = $args->getEntity();
         if ($entity instanceof Contact && $args->hasChangedField('additionalData')) {
             // Dispatch event or call external API.
         }
     }
     

4. Localization:

   • Extend translations in translations/messages.en.xlf or de.xlf:

     <trans-unit id="sulu_admin.app.additional_data">
         <source>Additional Data</source>
         <target>Zusätzliche Daten</target>
     </trans-unit>