Email Template Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ccc/email-template-bundle:dev-master
   

   Register the bundle in app/Kernel.php:

   new CCC\EmailTemplateBundle\EmailTemplateBundle(),
   

2. Database Setup: Run migrations to create the email_template table:

   php bin/console doctrine:schema:update --force
   

3. Routing: Add to config/routes.yaml:

   ccc_email_template:
       resource: "@CCCEmailTemplateBundle/Resources/config/routing.yaml"
       prefix: /admin
   

4. First Use Case: Use the form type in a Symfony form:

   $builder->add('email_template', EmailTemplateType::class, [
       'required' => false,
       'label' => 'Select Email Template',
   ]);
   

Implementation Patterns

Workflow: Managing Templates

1. CRUD Operations: Access the admin panel at /admin/email-template to manage templates via the built-in UI (list, create, edit, delete).

2. Form Integration: Embed the template selector in any Symfony form:

   $builder->add('template', EmailTemplateType::class, [
       'attr' => ['class' => 'email-template-selector'],
   ]);
   

   • Uses AJAX to populate a <textarea> with the template content when selected.

3. Dynamic Template Rendering: Fetch and render a template in a controller:

   $template = $this->getDoctrine()
       ->getRepository(EmailTemplate::class)
       ->findOneBy(['slug' => 'welcome_email']);
   
   $content = $this->renderView('CCCEmailTemplateBundle:EmailTemplate:template.html.twig', [
       'template' => $template,
       'variables' => ['user' => $user],
   ]);
   

4. Twig Integration: Extend Twig with template variables:

   {% extends 'base.html.twig' %}
   {% block body %}
       {{ render_template('welcome_email', {user: user}) }}
   {% endblock %}
   

   (Requires registering the Twig extension; see Gotchas.)

Integration Tips

• Custom Fields: Extend the EmailTemplate entity to add fields like subject, priority, or category.
• Validation: Add validation rules to the EmailTemplateType form class for client-side validation.
• Permissions: Secure the admin routes with Symfony’s security component:

  # config/access_control.yaml
  - { path: ^/admin/email-template, roles: ROLE_ADMIN }
  

• Asset Pipeline: Ensure jQuery is loaded for the AJAX functionality (check CCCEmailTemplateBundle:EmailTemplate:select.html.twig).

Gotchas and Tips

Pitfalls

1. Twig Extension Missing: The bundle provides a Twig extension (render_template) but does not auto-register it. Manually register it in config/packages/twig.yaml:

   twig:
       extensions:
           - CCC\EmailTemplateBundle\Twig\EmailTemplateExtension
   

2. Database Schema: The dev-master branch may have breaking schema changes. Backup your database before updates.

3. jQuery Dependency: The AJAX selector relies on jQuery. If missing, the template dropdown will fail silently. Include it in your layout:

   {{ encore_entry_link_tags('app') }}  {# or #}
   <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
   

4. Form Type Namespace: The form type is email_template_select (not EmailTemplateType). Use:

   $builder->add('template', 'email_template_select', [...]);
   

5. Translations: Default labels (e.g., "Add Template") require the translator component. If missing, they’ll appear as keys (e.g., Add template).

Debugging

• AJAX Fails: Check the browser’s Network tab for 404s on /ajax/template-content. Ensure the route is loaded and the FOSJsRoutingBundle is configured.

• Template Not Found: Verify the slug or id exists in the email_template table. Use:

  php bin/console doctrine:query:sql "SELECT * FROM email_template"
  

• Twig Errors: Clear the cache after adding the Twig extension:

  php bin/console cache:clear
  

Extension Points

1. Custom Template Storage: Override the EmailTemplate entity to store templates in a file system or API instead of the database.

2. Template Editor: Replace the default textarea with a WYSIWYG editor (e.g., TinyMCE) by extending the select.html.twig template.

3. Event Listeners: Add logic before/after template updates via Symfony events:

   // src/EventListener/EmailTemplateListener.php
   public function onPreUpdate(PreUpdateEventArgs $args) {
       $template = $args->getObject();
       // Sanitize or log changes
   }
   

   Register in services.yaml:

   services:
       App\EventListener\EmailTemplateListener:
           tags:
               - { name: doctrine.event_listener, event: preUpdate }
   

4. API Endpoint: Expose templates via API by creating a custom controller:

   #[Route('/api/templates', name: 'api_templates', methods: ['GET'])]
   public function getTemplates(): JsonResponse {
       $templates = $this->getDoctrine()
           ->getRepository(EmailTemplate::class)
           ->findAll();
       return $this->json($templates);
   }