Skip to content

utilities.md

Latest commit

 

History

History
142 lines (99 loc) · 3.64 KB

utilities.md

File metadata and controls

142 lines (99 loc) · 3.64 KB
Raw

Utilities

The SDK includes standalone utility classes for currency formatting and timezone conversion. These work with data already returned by the API — no extra HTTP requests needed.

CurrencyFormatter

CoCart's API returns prices as smallest-unit integers (e.g., 4599 for $45.99) along with currency metadata. CurrencyFormatter converts these into human-readable strings.

Setup

use CoCart\CurrencyFormatter;

$formatter = new CurrencyFormatter();

// With a specific locale (requires ext-intl)
$formatter = new CurrencyFormatter('de_DE');

Format a Price

$response = $client->cart()->get();
$currency = $response->getCurrency();

// Full formatted price with currency symbol
echo $formatter->format(4599, $currency); // "$45.99"

// Plain decimal (no symbol)
echo $formatter->formatDecimal(4599, $currency); // "45.99"

Zero-Decimal Currencies

Currencies like JPY have no minor units. The formatter handles this automatically:

// JPY currency info from the API
$currency = $response->getCurrency();
// currency_minor_unit = 0

echo $formatter->format(1500, $currency); // "¥1,500"
echo $formatter->formatDecimal(1500, $currency); // "1500"

How Formatting Works

  1. If the intl PHP extension is installed, the formatter uses NumberFormatter::formatCurrency() for proper locale-aware output (e.g., 1.234,56 € in German locale).
  2. If intl is not available, it falls back to using the currency_prefix, currency_suffix, currency_decimal_separator, and currency_thousand_separator values from the API response.

Currency Metadata

The API response includes this currency structure:

$currency = $response->getCurrency();
// [
//     'currency_code' => 'USD',
//     'currency_symbol' => '$',
//     'currency_minor_unit' => 2,
//     'currency_decimal_separator' => '.',
//     'currency_thousand_separator' => ',',
//     'currency_prefix' => '$',
//     'currency_suffix' => '',
// ]

Formatting Cart Items

$response = $client->cart()->get();
$currency = $response->getCurrency();
$formatter = new CurrencyFormatter();

foreach ($response->getItems() as $item) {
    $name = $item['name'];
    $price = $formatter->format($item['totals']['total'], $currency);
    echo "{$name}: {$price}\n";
}

$totals = $response->getTotals();
echo "Subtotal: " . $formatter->format($totals['subtotal'], $currency) . "\n";
echo "Total: " . $formatter->format($totals['total'], $currency) . "\n";

TimezoneHelper

WooCommerce stores dates in the store's configured timezone (often UTC). TimezoneHelper converts these to any other timezone.

Setup

use CoCart\TimezoneHelper;

$tz = new TimezoneHelper();

Detect System Timezone

echo $tz->detectTimezone(); // "America/New_York"

Convert Between Timezones

// Convert a UTC date to New York time
$local = $tz->convert('2025-01-15T15:00:00', 'UTC', 'America/New_York');
echo $local; // "2025-01-15T10:00:00"

// Convert between any two timezones
$tokyo = $tz->convert('2025-07-15T12:00:00', 'Europe/London', 'Asia/Tokyo');
echo $tokyo; // "2025-07-15T20:00:00"

Convert to Local Time

Shorthand to convert from the store's timezone to the system's timezone:

// Store is in UTC (default)
$local = $tz->toLocal('2025-01-15T15:00:00');

// Store is in a specific timezone
$local = $tz->toLocal('2025-01-15T10:00:00', 'America/Chicago');

Working with Cart/Order Dates

$tz = new TimezoneHelper();

$response = $client->cart()->get();
$expiryDate = $response->get('expiry.date');

if ($expiryDate) {
    $localExpiry = $tz->toLocal($expiryDate, 'UTC');
    echo "Cart expires: {$localExpiry}";
}