Epaybg Bundle Laravel Package

Getting Started

• Install the package (composer require vendor/package) and let Laravel auto-discovery register the service provider.
• Publish the new YAML config: php artisan vendor:publish --tag=currency-config. You will get config/currency.yaml instead of the old config/currency.php.
• Confirm the package's YAML parser is available. Laravel does not ship symfony/yaml by default; if the package does not require it, add composer require symfony/yaml.
• Set the default currency. v2.0.0 defaults to EUR; override it in config/currency.yaml (default: EUR) or via the package's env variable (commonly CURRENCY_DEFAULT) if supported by the service provider.
• First use case: format an amount with the default currency, e.g. Currency::format(1234.56) → €1,234.56 depending on locale. Check the facade/service class in the package README for the exact entry point.
• Look first at: config/currency.yaml, the package service provider (to see how YAML is loaded and env overrides are applied), and the v2 upgrade guide.

Implementation Patterns

• Facade or injection: Use the package facade for quick calls in controllers/views, or inject the underlying service into constructors for testability.
• Blade usage: Format values in views with the package's Blade directive or helper (e.g. @currency($amount)). Keep raw monetary values as integers/minor units where possible.
• Validation: Use the package's currency validation rule for request fields storing ISO codes. Pair it with an in: rule only if you maintain a custom allow-list.
• Per-user currency: Store a currency column on users/accounts, then set the active currency per request via middleware or a model accessor. Do not rely on the global default for multi-tenant apps.
• Config caching: The YAML file should be read during service-provider boot and mapped into Laravel's config repository. Run php artisan config:cache in deployment; avoid reading the YAML file at runtime in application code.
• Tests: Override values with config(['currency.default' => 'USD']) in test setup. If the package exposes a formatter, assert exact output including separators and symbol placement.
• Migration from v1: Replace the old PHP config with the YAML file. Keep a copy of the old file to translate keys, then delete config/currency.php so it is not accidentally loaded.
• Exchange rates: If the package supports conversion, bind a custom rate provider in a service provider rather than editing vendor code.

Gotchas and Tips

• Breaking config format: v2.0.0 ignores config/currency.php. Existing customizations will silently disappear until you migrate them to config/currency.yaml. Diff the old file against the published YAML before deleting anything.
• Default currency change: New installs default to EUR. Upgrading apps that assumed USD will change formatting and potentially stored/displayed values. Explicitly set the default in YAML or env to preserve behavior.
• YAML syntax: Use spaces, never tabs. Quote strings that look like booleans or numbers (e.g. currency codes are usually safe, but locale strings may not be). Validate with a YAML linter before deploying.
• Missing YAML parser: A Class "Symfony\Component\Yaml\Yaml" not found error means symfony/yaml is missing. Add it to composer.json.
• Config cache quirks: After editing currency.yaml, run php artisan config:clear locally and php artisan config:cache in deployment. With Octane, restart workers after config changes.
• Env precedence: Confirm whether env variables override YAML values. If they do, a stale CURRENCY_DEFAULT in .env can mask your YAML default and cause confusion.
• Debugging: Use php artisan tinker and inspect config('currency'). If it is empty or missing keys, the YAML was not loaded—check the service provider and file permissions.
• Extension points: Prefer container bindings for custom formatters, rounding strategies, or exchange-rate providers. Avoid modifying the published YAML for application-specific logic that belongs in code.
• Precision and rounding: Changing the default currency can expose rounding assumptions (e.g. 0-decimal currencies like JPY). Re-test formatting and conversion paths after the upgrade.