Financial Twig Extension Bundle Laravel Package

Getting Started

1. Install the bundle:

   composer require hostnet/financial-twig-extension-bundle
   

2. Register it in config/bundles.php if Symfony Flex did not do it automatically:

   Hostnet\FinancialTwigExtensionBundle\HostnetFinancialTwigExtensionBundle::class => ['all' => true],
   

3. Look first at the README and src/Twig/ in the package. The bundle exposes Twig filters/functions for displaying financial values. Typical filters are money, currency, percentage, or vat, but confirm the exact names in the source.

4. First use case: format a Money value object in a template.

   {{ order.total|money }}
   {{ product.price|currency('EUR') }}
   

   Pass Money objects (e.g., from hostnet/financial or MoneyPHP) from your controller or service. Avoid passing raw floats to financial filters.

Implementation Patterns

• Keep calculations in PHP, formatting in Twig. Use the bundle’s filters only for display. Calculate totals, VAT, discounts, and taxes in services using Money value objects, then render them with Twig filters.
• Standardize on Money objects. Use one money library throughout the application (likely hostnet/financial or MoneyPHP). This ensures the Twig filters receive the expected object type.
• Create reusable Twig partials for prices, totals, and VAT breakdowns so formatting is consistent across order pages, invoices, emails, and PDFs.
• Configure defaults if the bundle supports it. Check for bundle configuration for default currency, locale, or formatting style. If available, set it per environment or application.
• Use debug:twig to discover filters. Run php bin/console debug:twig to list available filters and functions, especially when upgrading or onboarding.
• Integrate with Symfony Intl. Ensure the PHP intl extension is installed so currency and number formatting respects locale rules.

Gotchas and Tips

• Low adoption means verify compatibility. With very few stars/dependents, check the bundle’s PHP, Symfony, and Twig version constraints before installing. Pin the version in composer.json and test upgrades.
• Filter names may not be obvious. If a filter is missing, inspect src/Twig/ and clear the Symfony cache. Bundle registration and cache clearing fix most “unknown filter” errors.
• Do not do financial math in Twig. Rounding, VAT, and currency conversion in templates are hard to test and easy to get wrong. Keep all calculations in PHP.
• Check locale and currency defaults. The bundle may rely on Intl defaults. Explicitly pass currency codes or configure defaults so output does not change unexpectedly between environments.
• Watch rounding and formatting edge cases. Financial display often rounds for presentation; make sure the displayed value matches your business rules (e.g., VAT breakdowns, negative amounts, zero decimals).
• Extension point: If the bundle lacks a required format, create a small custom Twig extension that decorates or reuses its services rather than forking the bundle.