ceytek-labs/tcmb-services-lite

A lightweight library for retrieving exchange rates and other data from TCMB's APIs.

v1.3.8 2024-10-27 16:19 UTC

README

🇹🇷 Türkçe sürüm için buraya tıklayın

TCMB Services Lite

Total Downloads Latest Version Size License

TCMB Services Lite

The TCMB (Central Bank of the Republic of Turkey) Services Lite is designed to help you easily utilize various data and APIs provided by the TCMB. Currently, it offers the feature of fetching exchange rates, but it can be expanded in the future to include other APIs from the TCMB.

Disclaimer: This package is not an official product of Central Bank of the Republic of Türkiye (Türkiye Cumhuriyet Merkez Bankası). The developers accept no responsibility for any issues, discrepancies, or damages that may arise from its use.

Requirements

  • PHP 8.1 or higher

Installation

You can add this package to your projects using Composer:

composer require ceytek-labs/tcmb-services-lite

Services

TCMB Exchange Rates

The TCMB Exchange Rates retrieves daily exchange rates from the Central Bank of Turkey, providing easy access to various currency information.

Example Usage

Here are a few examples of how you can use the TCMB Exchange Rates class in your PHP projects

⬆ Back to services

TCMB Exchange Rates: Display Raw XML Result from the API

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;

// Displays the raw XML result from the API
echo TcmbExchangeRates::make()->response();

⬆ Back to services

TCMB Exchange Rates: Display Raw JSON Result from the API

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;

// Converts the raw XML result from the API to JSON and displays it
echo TcmbExchangeRates::make()->jsonContent();

⬆ Back to services

TCMB Exchange Rates: Formatting Exchange Rates

You can receive data from the API in either object or array format. CamelCase is used in object format, and snake_case is used in array format.

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;
use CeytekLabs\TcmbServicesLite\Enums\Format;

// Getting data in object format
$exchangeRatesObject = TcmbExchangeRates::make()->format(Format::Object)->content();

// Getting data in array format
$exchangeRatesArray = TcmbExchangeRates::make()->format(Format::Array)->content();

⬆ Back to services

TCMB Exchange Rates: Getting All Exchange Rates

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;
use CeytekLabs\TcmbServicesLite\Enums\Format;

// Getting all exchange rates in object format
$currenciesObject = TcmbExchangeRates::make()->format(Format::Object)->currencies();

// Getting all exchange rates in array format
$currenciesArray = TcmbExchangeRates::make()->format(Format::Array)->currencies();

⬆ Back to services

TCMB Exchange Rates: Getting a Specific Currency

You can use the currency() method to get data for a specific currency.

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;
use CeytekLabs\TcmbServicesLite\Enums\Format;
use CeytekLabs\TcmbServicesLite\Enums\Currency;

// For example, getting the Australian Dollar (AUD) rate
$australianDollar = TcmbExchangeRates::make()
    ->format(Format::Object)
    ->currency(Currency::AustralianDollar)
    ->find();

⬆ Back to services

TCMB Exchange Rates: Accessing Currency Information

You can access detailed information of a specific currency:

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;
use CeytekLabs\TcmbServicesLite\Enums\Format;
use CeytekLabs\TcmbServicesLite\Enums\Currency;

// Getting information for the USD currency
$exchangeRates = TcmbExchangeRates::make()
    ->format(Format::Object)
    ->currency(Currency::UnitedStatesDollar);

// Currency code
echo $exchangeRates->code(); // "USD"

// Turkish name
echo $exchangeRates->turkishName(); // "ABD DOLARI"

// English name
echo $exchangeRates->englishName(); // "US DOLLAR"

// Unit amount
echo $exchangeRates->unit(); // "1"

// Forex buying rate (The buying rate valid in international markets and digital transactions)
echo $exchangeRates->forexBuying();

// Forex selling rate (The selling rate valid in international markets and digital transactions)
echo $exchangeRates->forexSelling();

// Banknote buying rate (The buying rate valid in cash currency transactions)
echo $exchangeRates->banknoteBuying();

// Banknote selling rate (The selling rate valid in cash currency transactions)
echo $exchangeRates->banknoteSelling();

⬆ Back to services

TCMB Exchange Rates: Displaying All Data in Object Format

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;
use CeytekLabs\TcmbServicesLite\Enums\Format;

print_r(TcmbExchangeRates::make()->format(Format::Object)->content());

Sample output:

stdClass Object
(
    [attributes] => stdClass Object
        (
            [date] => "2024-09-20 15:30"
            [bulletinNumber] => "2024/178"
        )

    [currencies] => stdClass Object
        (
            [USD] => stdClass Object
                (
                    [code] => "USD"
                    [name] => stdClass Object
                        (
                            [tr] => "ABD DOLARI"
                            [en] => "US DOLLAR"
                        )
                    [unit] => "1"
                    [forex] => stdClass Object
                        (
                            [buying] => "33.9531"
                            [selling] => "34.0142"
                        )
                    [banknote] => stdClass Object
                        (
                            [buying] => "33.9293"
                            [selling] => "34.0652"
                        )
                )
            // Other currencies...
        )
)

⬆ Back to services

TCMB Exchange Rates: Displaying All Data in Array Format

use CeytekLabs\TcmbServicesLite\TcmbExchangeRates;
use CeytekLabs\TcmbServicesLite\Enums\Format;

print_r(TcmbExchangeRates::make()->format(Format::Array)->content());

Sample output:

Array
(
    [attributes] => Array
        (
            [date] => "2024-09-20 15:30"
            [bulletin_number] => "2024/178"
        )

    [currencies] => Array
        (
            [USD] => Array
                (
                    [code] => "USD"
                    [name] => Array
                        (
                            [tr] => "ABD DOLARI"
                            [en] => "US DOLLAR"
                        )
                    [unit] => "1"
                    [forex] => Array
                        (
                            [buying] => "33.9531"
                            [selling] => "34.0142"
                        )
                    [banknote] => Array
                        (
                            [buying] => "33.9293"
                            [selling] => "34.0652"
                        )
                )
            // Other currencies...
        )
)

⬆ Back to services

TCMB Exchange Rates: Supported Currencies

The package supports the following currencies:

  • 🇺🇸 USD: United States Dollar
  • 🇦🇺 AUD: Australian Dollar
  • 🇩🇰 DKK: Danish Krone
  • 🇪🇺 EUR: Euro
  • 🇬🇧 GBP: British Pound
  • 🇨🇭 CHF: Swiss Franc
  • 🇸🇪 SEK: Swedish Krona
  • 🇨🇦 CAD: Canadian Dollar
  • 🇰🇼 KWD: Kuwaiti Dinar
  • 🇳🇴 NOK: Norwegian Krone
  • 🇸🇦 SAR: Saudi Riyal
  • 🇯🇵 JPY: Japanese Yen
  • 🇧🇬 BGN: Bulgarian Lev
  • 🇷🇴 RON: Romanian Leu
  • 🇷🇺 RUB: Russian Ruble
  • 🇮🇷 IRR: Iranian Rial
  • 🇨🇳 CNY: Chinese Yuan
  • 🇵🇰 PKR: Pakistani Rupee
  • 🇶🇦 QAR: Qatari Riyal
  • 🇰🇷 KRW: South Korean Won
  • 🇦🇿 AZN: Azerbaijani Manat
  • 🇦🇪 AED: United Arab Emirates Dirham

Debugging

  • If the response from the API is invalid or an error occurs, an Exception will be thrown.
  • If the XML format is invalid, you will receive the following error: Invalid XML format. Please check TcmbExchangeRates::make()->getResponse()

Future Plans

This package can be expanded to include other data and services provided by the TCMB, such as:

  • Interest Rates: Fetching interest rates published by the TCMB.
  • Inflation Data: Access to current inflation data.
  • Other Financial Data: Integrating other statistics and reports provided by the TCMB.

Contributing

If you'd like to contribute, please send a pull request or report an issue.

License

This project is licensed under the MIT License.