Contact Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Add the bundle to your Symfony 2 project via Composer:

   composer require culabs/contact-bundle
   

   Register the bundle in app/AppKernel.php:

   new CULabs\ContactBundle\CULabsContactBundle(),
   

2. Database Setup Run migrations (if provided) or manually create tables based on the bundle’s schema (check Resources/doc/ for details). Example table structure:

   CREATE TABLE contacts (
       id INT AUTO_INCREMENT PRIMARY KEY,
       name VARCHAR(255),
       email VARCHAR(255),
       phone VARCHAR(50),
       created_at DATETIME DEFAULT CURRENT_TIMESTAMP
   );
   

3. Basic CRUD via Controller Inject the bundle’s service (e.g., contact.manager) and use its methods:

   use CULabs\ContactBundle\Manager\ContactManager;
   
   class ContactController extends Controller {
       public function index(ContactManager $manager) {
           $contacts = $manager->findAll();
           return $this->render('contact/index.html.twig', ['contacts' => $contacts]);
       }
   }
   

4. First Form Use the bundle’s form type (if available) in a Twig template:

   {{ form_start(form) }}
       {{ form_widget(form.name) }}
       {{ form_widget(form.email) }}
       {{ form_widget(form.phone) }}
   {{ form_end(form) }}
   

Implementation Patterns

Common Workflows

1. Contact Management

   • Create: Use contact.manager->create($data).
   • Update: Fetch via find($id) and update fields, then save().
   • Delete: contact.manager->delete($id).
   • Search: Implement custom queries via Doctrine or bundle’s repository.

2. Integration with Forms

   • Extend the bundle’s form type (if provided) or create a custom one:

     use CULabs\ContactBundle\Form\Type\ContactType;
     
     $form = $this->createForm(ContactType::class, $contact);
     

   • Validate with Symfony’s validators or add custom constraints.

3. API Endpoints (RESTful)

   • Use Symfony’s JsonResponse or FOSRestBundle to expose CRUD:

     public function getContact(ContactManager $manager, $id) {
         return new JsonResponse($manager->find($id));
     }
     

4. Event Listeners

   • Subscribe to bundle events (e.g., contact.pre_save) for pre-processing:

     services:
         app.contact_listener:
             class: AppBundle\EventListener\ContactListener
             tags:
                 - { name: kernel.event_listener, event: contact.pre_save, method: onPreSave }
     

5. Batch Operations

   • Use Doctrine’s EntityManager or bundle methods for bulk actions:

     $manager->deleteByEmail('old@example.com');
     

Gotchas and Tips

Pitfalls

1. Lack of Documentation

   • The bundle has no stars or dependents, implying minimal adoption. Assume undocumented features or edge cases.
   • Workaround: Inspect Manager/, Resources/config/, and Entity/ directories for clues.

2. Doctrine Integration Assumptions

   • The bundle likely assumes Doctrine ORM. If using Doctrine ODM or another DBAL, expect conflicts.
   • Fix: Override the entity mapping or create a custom repository.

3. Form Type Coupling

   • If the bundle’s ContactType is tightly coupled to its entity, extending it may require overriding methods.
   • Tip: Create a custom form type that extends the bundle’s:

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

4. Translation Strings

   • Hardcoded strings in forms/views may not support i18n. Override templates or use Symfony’s translation system:

     {{ 'contact.name'|trans }}
     

5. No Built-in API

   • If you need API endpoints, build them manually or integrate with API Platform/FOSRestBundle.

Debugging Tips

• Enable Doctrine Debugging:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
  

• Check Event Dispatching: Use Symfony’s profiler to verify events are fired:

  $eventDispatcher->addListener('contact.pre_save', function($event) {
      dump($event->getContact());
  });
  

Extension Points

1. Custom Fields Add fields to the entity and update the form type:

   // src/Entity/Contact.php
   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $customField;
   

2. Validation Groups Use Symfony’s validation groups for partial updates:

   $contact->setEmail('new@example.com');
   $validator->validate($contact, ['PATCH']);
   

3. Custom Repositories Extend the bundle’s repository for complex queries:

   class CustomContactRepository extends ServiceEntityRepository {
       public function findByActive() {
           return $this->createQueryBuilder('c')
               ->where('c.is_active = :active')
               ->setParameter('active', true)
               ->getQuery()
               ->getResult();
       }
   }
   

4. Override Templates Copy bundle templates from vendor/culabs/contact-bundle/Resources/views/ to templates/bundles/culabscontact/ to customize without modifying the original.

5. Configuration Overrides Override bundle parameters in config/packages/culabs_contact.yaml:

   culabs_contact:
       default_per_page: 20
       allowed_fields: ['name', 'email', 'phone', 'custom_field']