FinanceBuddy/Helper/FinanceHelper.php

<?php

namespace Kanboard\Plugin\FinanceBuddy\Helper;

use Kanboard\Core\Base;

/**
 * Template/controller helper for FinanceBuddy.
 *
 * FinanceBuddy is opt-in per board: every render and save point is gated on isEnabled(), so an
 * un-enabled board is untouched. The enable flag lives in project metadata (financebuddy_enabled);
 * the per-task money lives in task metadata under the keys below.
 */
class FinanceHelper extends Base
{
    const ENABLED_KEY = 'financebuddy_enabled';
    const AMOUNT_KEY = 'financebuddy_amount';
    const DIRECTION_KEY = 'financebuddy_direction';
    const INSTALLMENT_CURRENT_KEY = 'financebuddy_installment_current';
    const INSTALLMENT_TOTAL_KEY = 'financebuddy_installment_total';

    // Hidden marker present only when the task form was submitted with the finance fieldset, so
    // non-finance task updates (moves, API calls) are ignored by the persistence hooks.
    const FORM_MARKER = 'financebuddy_form';

    // Memoized per project_id: the board hooks below call isEnabled() once per card.
    private static $enabledCache = array();

    /**
     * Is FinanceBuddy enabled for this board?
     *
     * @param  integer $project_id
     * @return bool
     */
    public function isEnabled($project_id)
    {
        $project_id = (int) $project_id;

        if (! isset(self::$enabledCache[$project_id])) {
            self::$enabledCache[$project_id] = (int) $this->projectMetadataModel->get($project_id, self::ENABLED_KEY, 0) === 1;
        }

        return self::$enabledCache[$project_id];
    }

    /**
     * Stored finance values for a task, with defaults. One query (getAll) since the board renders
     * this per card.
     *
     * @param  integer $task_id
     * @return array
     */
    public function get($task_id)
    {
        $all = $this->taskMetadataModel->getAll($task_id);

        return array(
            'amount' => isset($all[self::AMOUNT_KEY]) ? $all[self::AMOUNT_KEY] : '',
            'direction' => (isset($all[self::DIRECTION_KEY]) && $all[self::DIRECTION_KEY] === 'credit') ? 'credit' : 'debit',
            'installment_current' => isset($all[self::INSTALLMENT_CURRENT_KEY]) ? $all[self::INSTALLMENT_CURRENT_KEY] : '',
            'installment_total' => isset($all[self::INSTALLMENT_TOTAL_KEY]) ? $all[self::INSTALLMENT_TOTAL_KEY] : '',
        );
    }

    /**
     * Values to prefill the task-form fields: a re-post (after a validation error) wins, then the
     * stored metadata for an existing task, otherwise blanks for a new task.
     *
     * @param  array $values
     * @return array
     */
    public function formValues(array $values)
    {
        if (isset($values[self::FORM_MARKER])) {
            return array(
                'amount' => isset($values[self::AMOUNT_KEY]) ? $values[self::AMOUNT_KEY] : '',
                'direction' => (isset($values[self::DIRECTION_KEY]) && $values[self::DIRECTION_KEY] === 'credit') ? 'credit' : 'debit',
                'installment_current' => isset($values[self::INSTALLMENT_CURRENT_KEY]) ? $values[self::INSTALLMENT_CURRENT_KEY] : '',
                'installment_total' => isset($values[self::INSTALLMENT_TOTAL_KEY]) ? $values[self::INSTALLMENT_TOTAL_KEY] : '',
            );
        }

        if (! empty($values['id'])) {
            return $this->get($values['id']);
        }

        return array('amount' => '', 'direction' => 'debit', 'installment_current' => '', 'installment_total' => '');
    }

    /**
     * Parse a user-typed amount. Accepts a dot or a comma as the decimal separator and an optional
     * "R$"; there is no thousand separator. Returns a non-negative float (0.0 when unparseable).
     *
     * @param  string $raw
     * @return float
     */
    public static function parseAmount($raw)
    {
        $raw = str_replace(array('R$', ' '), '', trim((string) $raw));
        $raw = str_replace(',', '.', $raw);

        if ($raw === '' || ! is_numeric($raw)) {
            return 0.0;
        }

        $value = round((float) $raw, 2);

        return $value > 0 ? $value : 0.0;
    }

    /**
     * Format a money value for display: two decimals, comma decimal separator, no thousand
     * separator (e.g. 20.9 -> "20,90"). Accepts a float or a canonical dot-string.
     *
     * @param  float|string $amount
     * @return string
     */
    public static function money($amount)
    {
        return number_format((float) $amount, 2, ',', '');
    }
}