1<?php
2/**
3 * Matomo - free/libre analytics platform
4 *
5 * @link https://matomo.org
6 * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
7 */
8namespace Piwik\Category;
9
10/**
11 * Base type for subcategories.
12 *
13 * All widgets within a subcategory will be rendered in the Piwik reporting UI under the same page. By default
14 * you do not have to specify any subcategory as they are created automatically. Only create a subcategory if you
15 * want to change the name for a specific subcategoryId or if you want to specify a different order so the subcategory
16 * appears eg at a different order in the reporting menu. It also affects the order of reports in
17 * `API.getReportMetadata` and wherever we display any reports.
18 *
19 * To define a subcategory just place a subclass within the `Categories` folder of your plugin.
20 *
21 * Subcategories can also be added through the {@hook Subcategory.addSubcategories} event.
22 *
23 * @api since Piwik 3.0.0
24 */
25class Subcategory
26{
27    /**
28     * The id of the subcategory, see eg {@link Piwik\Widget\WidgetConfig::setSubcategoryId()`} or
29     * {@link Piwik\Report\getSubcategoryId()}. The id will be used in the Piwik reporting URL and as the name
30     * in the Piwik reporting submenu. If you want to define a different URL and name, specify a {@link $name}.
31     * For example you might want to have the actual GoalId (eg '4') in the URL but the actual goal name in the
32     * submenu (eg 'Downloads'). In this case one should specify `$id=4;$name='Downloads'`.
33     *
34     * @var string eg 'General_Overview' or 'VisitTime_ByServerTimeWidgetName'.
35     */
36    protected $id = '';
37
38    /**
39     * The id of the category the subcategory belongs to, must be specified.
40     * See {@link Piwik\Widget\WidgetConfig::setCategoryId()`} or {@link Piwik\Report\getCategoryId()}.
41     *
42     * @var string A translation key eg 'General_Visits' or 'Goals_Goals'
43     */
44    protected $categoryId = '';
45
46    /**
47     * The name that shall be used in the menu etc, defaults to the specified {@link $id}. See {@link $id}.
48     * @var string
49     */
50    protected $name = '';
51
52    /**
53     * The order of the subcategory. The lower the value the earlier a widget or a report will be displayed.
54     * @var int
55     */
56    protected $order = 99;
57
58    /**
59     * Sets (overwrites) the id of the subcategory see {@link $id}.
60     *
61     * @param string $id A translation key eg 'General_Overview'.
62     * @return static
63     */
64    public function setId($id)
65    {
66        $this->id = $id;
67        return $this;
68    }
69
70    /**
71     * Get the id of the subcategory.
72     * @return string
73     */
74    public function getId()
75    {
76        return $this->id;
77    }
78
79    /**
80     * Get the specified categoryId see {@link $categoryId}.
81     *
82     * @return string
83     */
84    public function getCategoryId()
85    {
86        return $this->categoryId;
87    }
88
89    /**
90     * Sets (overwrites) the categoryId see {@link $categoryId}.
91     *
92     * @param string $categoryId
93     * @return static
94     */
95    public function setCategoryId($categoryId)
96    {
97        $this->categoryId = $categoryId;
98        return $this;
99    }
100
101    /**
102     * Sets (overwrites) the name see {@link $name} and {@link $id}.
103     *
104     * @param string $name A translation key eg 'General_Overview'.
105     * @return static
106     */
107    public function setName($name)
108    {
109        $this->name = $name;
110        return $this;
111    }
112
113    /**
114     * Get the name of the subcategory.
115     * @return string
116     */
117    public function getName()
118    {
119        if (!empty($this->name)) {
120            return $this->name;
121        }
122
123        return $this->id;
124    }
125
126    /**
127     * Sets (overwrites) the order see {@link $order}.
128     *
129     * @param int $order
130     * @return static
131     */
132    public function setOrder($order)
133    {
134        $this->order = (int) $order;
135        return $this;
136    }
137
138    /**
139     * Get the order of the subcategory.
140     * @return int
141     */
142    public function getOrder()
143    {
144        return $this->order;
145    }
146
147    /**
148     * Get the help text (if any) for this category.
149     * @return null
150     */
151    public function getHelp()
152    {
153        return null;
154    }
155}
156