Template Parameters Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dmytrof/template-parameters-bundle
   

   Add to config/bundles.php:

   Dmytrof\TemplateParametersBundle\DmytrofTemplateParametersBundle::class => ['all' => true],
   

2. First Use Case: Replace template parameters dynamically in Twig templates. Define parameters in config/packages/dmytrof_template_parameters.yaml:

   dmytrof_template_parameters:
       parameters:
           app_name: "MyApp"
           app_version: "1.0.0"
   

   Use in Twig:

   <title>{{ app_name }} - v{{ app_version }}</title>
   

3. Where to Look First:

   • config/packages/dmytrof_template_parameters.yaml (configuration)
   • src/Controller/ (for dynamic parameter injection)
   • templates/ (Twig usage examples)

Implementation Patterns

Core Workflow

1. Static Parameters: Define in YAML/config:

   dmytrof_template_parameters:
       parameters:
           site_copyright: "© {{ current_year }} MyApp"
   

   Use in Twig:

   <footer>{{ site_copyright }}</footer>
   

2. Dynamic Parameters via Controller: Inject TemplateParameters service:

   use Dmytrof\TemplateParametersBundle\Service\TemplateParameters;
   
   public function index(TemplateParameters $templateParameters)
   {
       $templateParameters->set('user_name', $this->getUser()->getName());
       return $this->render('index.html.twig');
   }
   

   Use in Twig:

   <h1>Welcome, {{ user_name }}!</h1>
   

3. Parameter Inheritance: Extend base parameters in child templates:

   # config/packages/child_template_parameters.yaml
   dmytrof_template_parameters:
       extends: "@dmytrof_template_parameters:parameters.yaml"
       parameters:
           child_param: "Overridden!"
   

4. Environment-Specific Parameters: Use Symfony’s %env% or %kernel.environment%:

   dmytrof_template_parameters:
       parameters:
           debug_mode: "%kernel.debug%"
   

Integration Tips

• Twig Extensions: Combine with custom Twig filters for complex logic.
• Event Listeners: Modify parameters dynamically via kernel.request events.
• Dependency Injection: Pass TemplateParameters to services for reusable logic.

Gotchas and Tips

Pitfalls

1. Caching:

   • Parameters are compiled into Twig templates. Clear cache (php bin/console cache:clear) after changes.
   • Use debug: false in config to disable auto-reload (for production).

2. Namespace Conflicts:

   • Avoid parameter names conflicting with Twig globals (e.g., app, loop).

3. YAML Syntax:

   • Indentation matters! Use spaces (not tabs) in parameters.yaml.
   • Quotes are required for string values with special characters (e.g., "© 2023").

4. Dynamic Overrides:

   • Controller-set parameters override static ones. Use has() to check existence:

     {% if templateParameters.has('dynamic_param') %}
         {{ dynamic_param }}
     {% else %}
         Fallback value
     {% endif %}
     

Debugging

• Check Compiled Templates:

  php bin/console debug:twig
  

• Log Parameters: Add a Twig global to dump all parameters:

  twig:
      globals:
          all_template_params: "@=dmytrof_template_parameters.getAll()"
  

  Use in Twig:

  <pre>{{ dump(all_template_params) }}</pre>
  

Extension Points

1. Custom Parameter Sources: Implement ParameterProviderInterface to fetch parameters from APIs/DB:

   class ApiParameterProvider implements ParameterProviderInterface
   {
       public function getParameters(): array
       {
           return ['api_data' => file_get_contents('https://api.example.com')];
       }
   }
   

   Register in services.yaml:

   Dmytrof\TemplateParametersBundle\Service\TemplateParameters:
       arguments:
           $parameterProviders: ['@api_parameter_provider']
   

2. Twig Runtime Overrides: Extend the TemplateParametersExtension to add custom logic:

   use Dmytrof\TemplateParametersBundle\Twig\TemplateParametersExtension as BaseExtension;
   
   class CustomTemplateParametersExtension extends BaseExtension
   {
       public function getFunctions()
       {
           return [
               new \Twig\TwigFunction('format_param', [$this, 'formatParameter']),
           ];
       }
   
       public function formatParameter($param, $format)
       {
           return strtoupper($param) . " [$format]";
       }
   }
   

   Register as a Twig extension.

3. Parameter Validation: Add validation via Symfony’s validator:

   dmytrof_template_parameters:
       parameters:
           email: "user@example.com"
       validation:
           email: "Symfony\Component\Validator\Constraints\Email"
   

   (Requires custom implementation; see issue #X for updates.)