<?php
/**
 * Piwik - Open source web analytics
 *
 * @link http://piwik.org
 * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
 *
 * @category Piwik
 * @package Piwik
 */

/**
 * A DataTable filter that replaces range label columns with prettier,
 * human-friendlier versions.
 *
 * When reports that summarize data over a set of ranges (such as the
 * reports in the VisitorInterest plugin) are archived, they are
 * archived with labels that read as: '$min-$max' or '$min+'. These labels
 * have no units and can look like '1-1'.
 *
 * This filter can be used to clean up and add units those range labels. To
 * do this, you supply a string to use when the range specifies only
 * one unit (ie '1-1') and another format string when the range specifies
 * more than one unit (ie '2-2', '3-5' or '6+').
 *
 * This filter can also be extended to beautify ranges differently based
 * on the range values.
 */
class Piwik_DataTable_Filter_BeautifyRangeLabels extends Piwik_DataTable_Filter_ColumnCallbackReplace
{
    /**
     * The string to use when the range being beautified is between 1-1 units.
     * @var string
     */
    protected $labelSingular;

    /**
     * The format string to use when the range being beautified references more than
     * one unit.
     * @var string
     */
    protected $labelPlural;

    /**
     * Constructor.
     *
     * @param Piwik_DataTable $table          The DataTable that will be filtered.
     * @param string $labelSingular  The string to use when the range being beautified
     *                                         is equal to '1-1 units'.
     * @param string $labelPlural    The string to use when the range being beautified
     *                                         references more than one unit. This must be a format
     *                                         string that takes one string parameter.
     */
    public function __construct($table, $labelSingular, $labelPlural)
    {
        parent::__construct($table, 'label', array($this, 'beautify'), array());

        $this->labelSingular = $labelSingular;
        $this->labelPlural = $labelPlural;
    }

    /**
     * Beautifies a range label and returns the pretty result.
     *
     * @param string $value  The range string. This must be in either a '$min-$max' format
     *                        a '$min+' format.
     * @return string  The pretty range label.
     */
    public function beautify($value)
    {
        // if there's more than one element, handle as a range w/ an upper bound
        if (strpos($value, "-") !== false) {
            // get the range
            sscanf($value, "%d - %d", $lowerBound, $upperBound);

            // if the lower bound is the same as the upper bound make sure the singular label
            // is used
            if ($lowerBound == $upperBound) {
                return $this->getSingleUnitLabel($value, $lowerBound);
            } else {
                return $this->getRangeLabel($value, $lowerBound, $upperBound);
            }
        } // if there's one element, handle as a range w/ no upper bound
        else {
            // get the lower bound
            sscanf($value, "%d", $lowerBound);

            if ($lowerBound !== NULL) {
                $plusEncoded = urlencode('+');
                $plusLen = strlen($plusEncoded);
                $len = strlen($value);

                // if the label doesn't end with a '+', append it
                if ($len < $plusLen || substr($value, $len - $plusLen) != $plusEncoded) {
                    $value .= $plusEncoded;
                }

                return $this->getUnboundedLabel($value, $lowerBound);
            } else {
                // if no lower bound can be found, this isn't a valid range. in this case
                // we assume its a translation key and try to translate it.
                return Piwik_Translate(trim($value));
            }
        }
    }

    /**
     * Beautifies and returns a range label whose range spans over one unit, ie
     * 1-1, 2-2 or 3-3.
     *
     * This function can be overridden in derived types to customize beautifcation
     * behavior based on the range values.
     *
     * @param string $oldLabel    The original label value.
     * @param int $lowerBound  The lower bound of the range.
     * @return string  The pretty range label.
     */
    public function getSingleUnitLabel($oldLabel, $lowerBound)
    {
        if ($lowerBound == 1) {
            return $this->labelSingular;
        } else {
            return sprintf($this->labelPlural, $lowerBound);
        }
    }

    /**
     * Beautifies and returns a range label whose range is bounded and spans over
     * more than one unit, ie 1-5, 5-10 but NOT 11+.
     *
     * This function can be overridden in derived types to customize beautifcation
     * behavior based on the range values.
     *
     * @param string $oldLabel    The original label value.
     * @param int $lowerBound  The lower bound of the range.
     * @param int $upperBound  The upper bound of the range.
     * @return string  The pretty range label.
     */
    public function getRangeLabel($oldLabel, $lowerBound, $upperBound)
    {
        return sprintf($this->labelPlural, $oldLabel);
    }

    /**
     * Beautifies and returns a range label whose range is unbounded, ie
     * 5+, 10+, etc.
     *
     * This function can be overridden in derived types to customize beautifcation
     * behavior based on the range values.
     *
     * @param string $oldLabel    The original label value.
     * @param int $lowerBound  The lower bound of the range.
     * @return string  The pretty range label.
     */
    public function getUnboundedLabel($oldLabel, $lowerBound)
    {
        return sprintf($this->labelPlural, $oldLabel);
    }
}