Contact Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aropixel/contact-bundle
   

   Ensure aropixel/admin-bundle is also installed (required dependency).

2. Database Migration: Run migrations to create the aropixel_contact table:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. Route Integration: Include the bundle’s routes in your config/routes.yaml:

   aropixel_contact:
       resource: "@AropixelContactBundle/Resources/config/routes.yaml"
       prefix: /admin
   

4. First Use Case:

   • Submit a contact form from your frontend (e.g., Twig template) to POST /contact/submit.
   • Admin can view submissions at /admin/contact.

Implementation Patterns

Core Workflow

1. Form Submission:

   • Extend the bundle’s ContactType or create a custom form class inheriting from Aropixel\ContactBundle\Form\ContactType.
   • Example:

     use Aropixel\ContactBundle\Form\ContactType;
     
     class CustomContactType extends ContactType {
         public function buildForm(FormBuilderInterface $builder, array $options) {
             parent::buildForm($builder, $options);
             $builder->add('custom_field', TextType::class);
         }
     }
     

   • Configure the form in your controller:

     $form = $this->createForm(CustomContactType::class, $contact);
     

2. Email Handling:

   • Customize email templates by overriding the bundle’s Twig templates (located in templates/AropixelContactBundle/).
   • Configure email settings in config/packages/aropixel_contact.yaml:

     aropixel_contact:
         from_email: 'contact@example.com'
         to_emails: ['admin@example.com']
         bcc_emails: ['backup@example.com']
     

3. Admin Integration:

   • Use the built-in CRUD interface for managing contacts via AropixelAdminBundle.
   • Customize the admin list view by extending the bundle’s ContactAdmin class:

     use Aropixel\ContactBundle\Admin\ContactAdmin;
     
     class CustomContactAdmin extends ContactAdmin {
         protected function configureListFields(ListMapper $listMapper) {
             parent::configureListFields($listMapper);
             $listMapper->add('custom_field');
         }
     }
     

4. Attachments:

   • Handle file uploads by extending the form type:

     $builder->add('attachment', FileType::class, [
         'multiple' => true,
         'mapped' => false,
     ]);
     

   • Process attachments in the controller:

     $contact->setAttachments($request->files->get('attachment'));
     

Gotchas and Tips

Common Pitfalls

1. Missing Admin Bundle:

   • The contact-bundle requires aropixel/admin-bundle. Install both:

     composer require aropixel/admin-bundle aropixel/contact-bundle
     

2. Migration Issues:

   • If migrations fail, manually check the aropixel_contact table structure. The bundle prefixes tables with aropixel_.
   • Run php bin/console doctrine:schema:update --force if needed.

3. Email Configuration:

   • Ensure symfony/mailer is configured in .env (e.g., MAILER_DSN=smtp://user:pass@smtp.example.com).
   • BCC addresses may not work if the to_emails array is empty (validate in config/packages/aropixel_contact.yaml).

4. Twig Template Overrides:

   • Override templates in templates/AropixelContactBundle/ to avoid updates overwriting changes.
   • Example override path:

     templates/AropixelContactBundle/Email/contact.html.twig
     

5. Date Sorting:

   • Contacts are sorted by createdAt by default. Override the ContactRepository to customize sorting:

     use Doctrine\ORM\EntityRepository;
     
     class CustomContactRepository extends EntityRepository {
         public function findAllSorted() {
             return $this->createQueryBuilder('c')
                 ->orderBy('c.updatedAt', 'DESC')
                 ->getQuery()
                 ->getResult();
         }
     }
     

Debugging Tips

1. Form Validation:

   • Enable debug mode (APP_DEBUG=1) to see form errors in the Symfony profiler.
   • Validate CSRF tokens if forms fail silently:

     {{ form_start(form, { attr: { 'data-csrf-token': app.request.csrfToken } }) }}
     

2. Email Debugging:

   • Use Symfony’s Swiftmailer profiler to inspect sent emails:

     php bin/console debug:container swiftmailer.mailer
     

   • Check logs for email failures:

     tail -f var/log/dev.log | grep "Swift_Transport"
     

3. Attachment Handling:

   • Ensure uploaded files are moved to a writable directory (e.g., public/uploads/).
   • Validate file types/sizes in the form type:

     $builder->add('attachment', FileType::class, [
         'constraints' => [
             new File(['maxSize' => '1024k', 'mimeTypes' => ['image/jpeg']])
         ],
     ]);
     

Extension Points

1. Custom Fields:

   • Add fields to the Contact entity by extending it:

     use Aropixel\ContactBundle\Entity\Contact;
     
     class ExtendedContact extends Contact {
         /**
          * @ORM\Column(type="string", nullable=true)
          */
         private $customField;
     }
     

   • Update the form type and migrations accordingly.

2. Event Listeners:

   • Subscribe to the contact.pre_send event to modify messages before sending:

     use Aropixel\ContactBundle\Event\ContactEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class ContactSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return ['contact.pre_send' => 'onContactSend'];
         }
     
         public function onContactSend(ContactEvent $event) {
             $contact = $event->getContact();
             $contact->setSubject('[Modified] ' . $contact->getSubject());
         }
     }
     

3. API Integration:

   • Expose contacts via API using Symfony’s Serializer:

     use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;
     
     $normalizer = new ObjectNormalizer();
     $contactData = $normalizer->normalize($contact);
     

   • Secure endpoints with is_granted('ROLE_ADMIN').