ongr/currency-exchange-bundle

ONGR currency exchange bundle

v2.0.6 2016-08-01 08:05 UTC

README

This bundle provides an easy way to display price in multiple currencies. It gives a solution to fetch and store current currency rates, to convert prices and display them in Twig templates.

Stable Release Build Status Coverage Status Quality Score

Documentation

The documentation of the bundle can be found in Resources/doc/

Installation

Follow 5 quick steps to setup this bundle.

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

$ composer require ongr/currency-exchange-bundle

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 2: Enable the Bundle

Register bundles in app/AppKernel.php:

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        return [
            // ...
            new ONGR\ElasticsearchBundle\ONGRElasticsearchBundle(),
            new ONGR\CurrencyExchangeBundle\ONGRCurrencyExchangeBundle(),    
        ];
    }

    // ...
}

Step 3: Update Elasticsearch Mapping

This bundle provides Elasticsearch document to store currency rates. Add this bundle to your ES manager's mapping to associate it:

# app/config/config.yml
ongr_elasticsearch:
    # ...
    managers:
        default:
            # ...
            mappings:
                # ...
                - AppBundle
                - ONGRCurrencyExchangeBundle

Step 4: Configure the Bundle

Configure the currencies you need in config.yml file.

# app/config/config.yml
ongr_currency_exchange:
    es_manager: default
    default_currency: EUR
    separators:
        decimal: ','
        thousands: '.'
    currencies:
        EUR: "%s €"    # %s stands for the price itself
        USD: "$ %s"

That's it for setup, jump to the next chapter to learn how to use this bundle.

Usage

The main parts of this bundle are a command to update currency rates and Twig helpers to display price in various currencies.

Before converting prices you need to fetch the latest currency rates:

$ app/console ongr:currency:update

Tip: setup a cron job to update currencies daily in your production environment.

Now you are ready to use currency conversion logic in your templates. Here is a simple example how to convert currency:

<ul>
    <li>Price in default currency: {{ 123.123|ongr_price(2) }}
    <li>Price in US dollars: {{ 123.123|ongr_price(2, 'USD') }}
</ul>

In this example the number 2 represents the number of decimal points. It will print the following information:

Price in default currency: 123.12 €
Price in US dollars: $ 123.12 

To learn more read about provided Twig helpers or check example currency switching implementation.

License

This package is licensed under the MIT license. For the full copyright and license information, please view the LICENSE file that was distributed with this source code.