Sort::getDefaults() - Code Metrics - Inspection of "Add `Sort::getDefaults()`" - yiisoft/data - Measure and Improve Code Quality continuously with Scrutinizer

Passed

Pull Request — master (#156)

by Sergei

created 2024-01-23 07:34 UTC

Sort::getDefaults() A

↳ Parent: Sort

Complexity

Conditions	1
Paths	1

Size

Total Lines	5
Code Lines	3

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	4
CRAP Score	1

Importance

Changes

Metric	Value
cc	1
eloc	3
nc	1
nop	0
dl	0
loc	5
ccs	4
cts	4
cp	1
crap	1
rs	10
c	0
b	0
f	0

<?php

declare(strict_types=1);

namespace Yiisoft\Data\Reader;

use InvalidArgumentException;

use function array_key_exists;
use function array_merge;
use function implode;
use function is_array;
use function is_int;
use function is_string;
use function preg_split;
use function substr;
use function trim;

/**
 * Sort represents data sorting settings:
 *
 * - A config with a map of logical field => real fields along with their order. The config also contains default
 *   order for each logical field.
 * - Currently specified logical fields order such as field1 => asc, field2 => desc. Usually it is passed directly
 *   from end user.
 *
 * Logical fields are the ones user operates with. Real fields are the ones actually present in a data set.
 * Such a mapping helps when you need to sort by a single logical field that, in fact, consists of multiple fields
 * in underlying the data set. For example, we provide a user with a username which consists of first name and last name
 * fields in actual data set.
 *
 * Based on the settings, the class can produce a criteria to be applied to {@see SortableDataInterface}
 * when obtaining the data i.e. a list of real fields along with their order directions.
 *
 * There are two modes of forming a criteria available:
 *
 * - {@see Sort::only()} ignores user-specified order for logical fields that have no configuration.
 * - {@see Sort::any()} uses user-specified logical field name and order directly for fields that have no configuration.
 *
 * @psalm-type TOrder = array<string, "asc"|"desc">
 * @psalm-type TSortFieldItem = array<string, int>
 * @psalm-type TConfigItem = array{asc: TSortFieldItem, desc: TSortFieldItem, default: "asc"|"desc"}
 * @psalm-type TConfig = array<string, TConfigItem>
 * @psalm-type TUserConfigItem = array{
 *     asc?: int|"asc"|"desc"|array<string, int|"asc"|"desc">,
 *     desc?: int|"asc"|"desc"|array<string, int|"asc"|"desc">,
 *     default?: "asc"|"desc"
 * }
 * @psalm-type TUserConfig = array<int, string>|array<string, TUserConfigItem>
 */
final class Sort
{
    /**
     * Logical fields config.
     *
     * @psalm-var TConfig
     */
    private array $config;

    /**
     * @var bool Whether to add default sorting when forming criteria.
     */
    private bool $withDefaultSorting = true;

    /**
     * @var array Logical fields to order by in form of [name => direction].
     * @psalm-var TOrder
     */
    private array $currentOrder = [];

    /**
     * @param array $config Logical fields config.
     * @psalm-param TUserConfig $config
     *
     * @param bool $ignoreExtraFields Whether to ignore logical fields not present in the config when forming criteria.
     */
    private function __construct(private bool $ignoreExtraFields, array $config)
    {
        $normalizedConfig = [];

        foreach ($config as $fieldName => $fieldConfig) {
            if (
                !(is_int($fieldName) && is_string($fieldConfig))
                && !(is_string($fieldName) && is_array($fieldConfig))
            ) {
                throw new InvalidArgumentException('Invalid config format.');
            }

            if (is_int($fieldName)) {
                /** @var string $fieldConfig */
                $fieldName = $fieldConfig;
                $fieldConfig = [];
            } else {
                /** @psalm-var TUserConfigItem $fieldConfig */
                foreach ($fieldConfig as $key => &$criteria) {
                    // 'default' => 'asc' or 'desc'
                    if ($key === 'default') {
                        continue;
                    }
                    // 'asc'/'desc' => SORT_*
                    if (is_int($criteria)) {
                        continue;
                    }
                    // 'asc'/'desc' => 'asc' or 'asc'/'desc' => 'desc'
                    if (is_string($criteria)) {
                        $criteria = [$fieldName => $criteria === 'desc' ? SORT_DESC : SORT_ASC];
                        continue;
                    }
                    // 'asc'/'desc' => ['field' => SORT_*|'asc'|'desc']
                    foreach ($criteria as &$subCriteria) {
                        if (is_string($subCriteria)) {
                            $subCriteria = $subCriteria === 'desc' ? SORT_DESC : SORT_ASC;
                        }
                    }
                }
            }

            $normalizedConfig[$fieldName] = array_merge(
                [
                    'asc' => [$fieldName => SORT_ASC],
                    'desc' => [$fieldName => SORT_DESC],
                    'default' => 'asc',
                ],
                $fieldConfig,
            );
        }

        /** @psalm-var TConfig $normalizedConfig */
        $this->config = $normalizedConfig;
    }

    /**
     * Create a sort instance that ignores current order for extra logical fields that have no configuration.
     *
     * @param array $config Logical fields config.
     * @psalm-param TUserConfig $config
     *
     * ```php
     * [
     *     'age', // means will be sorted as is
     *     'name' => [
     *         'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
     *         'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
     *         'default' => 'desc',
     *     ],
     * ]
     * ```
     *
     * In the above, two fields are declared: `age` and `name`. The `age` field is
     * a simple field which is equivalent to the following:
     *
     * ```php
     * 'age' => [
     *     'asc' => ['age' => SORT_ASC],
     *     'desc' => ['age' => SORT_DESC],
     *     'default' => 'asc',
     * ]
     * ```
     *
     * The name field is a virtual field name that consists of two real fields, `first_name` and `last_name`. Virtual
     * field name is used in order string or order array while real fields are used in final sorting criteria.
     *
     * Each configuration has the following options:
     *
     * - `asc` - criteria for ascending sorting.
     * - `desc` - criteria for descending sorting.
     * - `default` - default sorting. Could be either `asc` or `desc`. If not specified, `asc` is used.
     */
    public static function only(array $config): self
    {
        return new self(true, $config);
    }

    /**
     * Create a sort instance that uses logical field itself and direction provided when there is no configuration.
     *
     * @param array $config Logical fields config.
     * @psalm-param TUserConfig $config
     *
     * ```php
     * [
     *     'age', // means will be sorted as is
     *     'name' => [
     *         'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
     *         'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
     *         'default' => 'desc',
     *     ],
     * ]
     * ```
     *
     * In the above, two fields are declared: `age` and `name`. The `age` field is
     * a simple field which is equivalent to the following:
     *
     * ```php
     * 'age' => [
     *     'asc' => ['age' => SORT_ASC],
     *     'desc' => ['age' => SORT_DESC],
     *     'default' => 'asc',
     * ]
     * ```
     *
     * The name field is a virtual field name that consists of two real fields, `first_name` and `last_name`. Virtual
     * field name is used in order string or order array while real fields are used in final sorting criteria.
     *
     * Each configuration has the following options:
     *
     * - `asc` - criteria for ascending sorting.
     * - `desc` - criteria for descending sorting.
     * - `default` - default sorting. Could be either `asc` or `desc`. If not specified, `asc` is used.
     */
    public static function any(array $config = []): self
    {
        return new self(false, $config);
    }

    /**
     * Get a new instance with logical fields order set from an order string.
     *
     * The string consists of comma-separated field names.
     * If the name is prefixed with `-`, field order is descending.
     * Otherwise, the order is ascending.
     *
     * @param string $orderString Logical fields order as comma-separated string.
     *
     * @return self New instance.
     */
    public function withOrderString(string $orderString): self
    {
        $order = [];
        $parts = preg_split('/\s*,\s*/', trim($orderString), -1, PREG_SPLIT_NO_EMPTY);

        foreach ($parts as $part) {
            if (str_starts_with($part, '-')) {
                $order[substr($part, 1)] = 'desc';
            } else {
                $order[$part] = 'asc';
            }
        }

        return $this->withOrder($order);
    }

    /**
     * Return a new instance with logical fields order set.
     *
     * @param array $order A map with logical field names to order by as keys, direction as values.
     * @psalm-param TOrder $order
     *
     * @return self New instance.
     */
    public function withOrder(array $order): self
    {
        $new = clone $this;
        $new->currentOrder = $order;
        return $new;
    }

    /**
     * Return a new instance without default sorting set.
     *
     * @return self New instance.
     */
    public function withoutDefaultSorting(): self
    {
        $new = clone $this;
        $new->withDefaultSorting = false;
        return $new;
    }

    /**
     * Returns default order of logical fields' directions.
     *
     * Example of result:
     *
     * ```
     * [
     *   'id' => 'asc',
     *   'name' => 'desc',
     * ]
     * ```
     *
     * @psalm-return TOrder
     */
    public function getDefaults(): array
    {
        return array_map(
            static fn($fieldConfig) => $fieldConfig['default'],
            $this->config,
        );
    }

    /**
     * Get current logical fields order.
     *
     * @return array Logical fields order.
     * @psalm-return TOrder
     */
    public function getOrder(): array
    {
        return $this->currentOrder;
    }

    /**
     * Get an order string based on current logical fields order.
     *
     * The string consists of comma-separated field names.
     * If the name is prefixed with `-`, field order is descending.
     * Otherwise, the order is ascending.
     *
     * @return string An order string.
     */
    public function getOrderAsString(): string
    {
        $parts = [];

        foreach ($this->currentOrder as $field => $direction) {
            $parts[] = ($direction === 'desc' ? '-' : '') . $field;
        }

        return implode(',', $parts);
    }

    /**
     * Get a sorting criteria to be applied to {@see SortableDataInterface}
     * when obtaining the data i.e. a list of real fields along with their order directions.
     *
     * @return array Sorting criteria.
     * @psalm-return array<string, int>
     */
    public function getCriteria(): array
    {
        $criteria = [];
        $config = $this->config;

        foreach ($this->currentOrder as $field => $direction) {
            if (array_key_exists($field, $config)) {
                $criteria = array_merge($criteria, $config[$field][$direction]);
                unset($config[$field]);
            } else {
                if ($this->ignoreExtraFields) {
                    continue;
                }
                $criteria = array_merge($criteria, [$field => $direction === 'desc' ? SORT_DESC : SORT_ASC]);
            }
        }

        if ($this->withDefaultSorting) {
            foreach ($config as $fieldConfig) {
                $criteria += $fieldConfig[$fieldConfig['default']];
            }
        }

        return $criteria;
    }
}


1		<?php
2
3		declare(strict_types=1);
4
5		namespace Yiisoft\Data\Reader;
6
7		use InvalidArgumentException;
8
9		use function array_key_exists;
10		use function array_merge;
11		use function implode;
12		use function is_array;
13		use function is_int;
14		use function is_string;
15		use function preg_split;
16		use function substr;
17		use function trim;
18
19		/**
20		* Sort represents data sorting settings:
21		*
22		* - A config with a map of logical field => real fields along with their order. The config also contains default
23		* order for each logical field.
24		* - Currently specified logical fields order such as field1 => asc, field2 => desc. Usually it is passed directly
25		* from end user.
26		*
27		* Logical fields are the ones user operates with. Real fields are the ones actually present in a data set.
28		* Such a mapping helps when you need to sort by a single logical field that, in fact, consists of multiple fields
29		* in underlying the data set. For example, we provide a user with a username which consists of first name and last name
30		* fields in actual data set.
31		*
32		* Based on the settings, the class can produce a criteria to be applied to {@see SortableDataInterface}
33		* when obtaining the data i.e. a list of real fields along with their order directions.
34		*
35		* There are two modes of forming a criteria available:
36		*
37		* - {@see Sort::only()} ignores user-specified order for logical fields that have no configuration.
38		* - {@see Sort::any()} uses user-specified logical field name and order directly for fields that have no configuration.
39		*
40		* @psalm-type TOrder = array<string, "asc"\|"desc">
41		* @psalm-type TSortFieldItem = array<string, int>
42		* @psalm-type TConfigItem = array{asc: TSortFieldItem, desc: TSortFieldItem, default: "asc"\|"desc"}
43		* @psalm-type TConfig = array<string, TConfigItem>
44		* @psalm-type TUserConfigItem = array{
45		* asc?: int\|"asc"\|"desc"\|array<string, int\|"asc"\|"desc">,
46		* desc?: int\|"asc"\|"desc"\|array<string, int\|"asc"\|"desc">,
47		* default?: "asc"\|"desc"
48		* }
49		* @psalm-type TUserConfig = array<int, string>\|array<string, TUserConfigItem>
50		*/
51		final class Sort
52		{
53		/**
54		* Logical fields config.
55		*
56		* @psalm-var TConfig
57		*/
58		private array $config;
59
60		/**
61		* @var bool Whether to add default sorting when forming criteria.
62		*/
63		private bool $withDefaultSorting = true;
64
65		/**
66		* @var array Logical fields to order by in form of [name => direction].
67		* @psalm-var TOrder
68		*/
69		private array $currentOrder = [];
70
71		/**
72		* @param array $config Logical fields config.
73		* @psalm-param TUserConfig $config
74		*
75		* @param bool $ignoreExtraFields Whether to ignore logical fields not present in the config when forming criteria.
76		*/
77	105	private function __construct(private bool $ignoreExtraFields, array $config)
78		{
79	105	$normalizedConfig = [];
80
81	105	foreach ($config as $fieldName => $fieldConfig) {
82		if (
83	99	!(is_int($fieldName) && is_string($fieldConfig))
84	99	&& !(is_string($fieldName) && is_array($fieldConfig))
85		) {
86	2	throw new InvalidArgumentException('Invalid config format.');
87		}
88
89	97	if (is_int($fieldName)) {
90		/** @var string $fieldConfig */
91	90	$fieldName = $fieldConfig;
92	90	$fieldConfig = [];
93		} else {
94		/** @psalm-var TUserConfigItem $fieldConfig */
95	11	foreach ($fieldConfig as $key => &$criteria) {
96		// 'default' => 'asc' or 'desc'
97	11	if ($key === 'default') {
98	9	continue;
99		}
100		// 'asc'/'desc' => SORT_*
101	10	if (is_int($criteria)) {
102	1	continue;
103		}
104		// 'asc'/'desc' => 'asc' or 'asc'/'desc' => 'desc'
105	10	if (is_string($criteria)) {
106	3	$criteria = [$fieldName => $criteria === 'desc' ? SORT_DESC : SORT_ASC];
107	3	continue;
108		}
109		// 'asc'/'desc' => ['field' => SORT_*\|'asc'\|'desc']
110	7	foreach ($criteria as &$subCriteria) {
111	7	if (is_string($subCriteria)) {
112	2	$subCriteria = $subCriteria === 'desc' ? SORT_DESC : SORT_ASC;
113		}
114		}
115		}
116		}
117
118	97	$normalizedConfig[$fieldName] = array_merge(
119	97	[
120	97	'asc' => [$fieldName => SORT_ASC],
121	97	'desc' => [$fieldName => SORT_DESC],
122	97	'default' => 'asc',
123	97	],
124	97	$fieldConfig,
125	97	);
126		}
127
128		/** @psalm-var TConfig $normalizedConfig */
129	103	$this->config = $normalizedConfig;
130		}
131
132		/**
133		* Create a sort instance that ignores current order for extra logical fields that have no configuration.
134		*
135		* @param array $config Logical fields config.
136		* @psalm-param TUserConfig $config
137		*
138		* ```php
139		* [
140		* 'age', // means will be sorted as is
141		* 'name' => [
142		* 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
143		* 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
144		* 'default' => 'desc',
145		* ],
146		* ]
147		* ```
148		*
149		* In the above, two fields are declared: `age` and `name`. The `age` field is
150		* a simple field which is equivalent to the following:
151		*
152		* ```php
153		* 'age' => [
154		* 'asc' => ['age' => SORT_ASC],
155		* 'desc' => ['age' => SORT_DESC],
156		* 'default' => 'asc',
157		* ]
158		* ```
159		*
160		* The name field is a virtual field name that consists of two real fields, `first_name` and `last_name`. Virtual
161		* field name is used in order string or order array while real fields are used in final sorting criteria.
162		*
163		* Each configuration has the following options:
164		*
165		* - `asc` - criteria for ascending sorting.
166		* - `desc` - criteria for descending sorting.
167		* - `default` - default sorting. Could be either `asc` or `desc`. If not specified, `asc` is used.
168		*/
169	99	public static function only(array $config): self
170		{
171	99	return new self(true, $config);
172		}
173
174		/**
175		* Create a sort instance that uses logical field itself and direction provided when there is no configuration.
176		*
177		* @param array $config Logical fields config.
178		* @psalm-param TUserConfig $config
179		*
180		* ```php
181		* [
182		* 'age', // means will be sorted as is
183		* 'name' => [
184		* 'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
185		* 'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
186		* 'default' => 'desc',
187		* ],
188		* ]
189		* ```
190		*
191		* In the above, two fields are declared: `age` and `name`. The `age` field is
192		* a simple field which is equivalent to the following:
193		*
194		* ```php
195		* 'age' => [
196		* 'asc' => ['age' => SORT_ASC],
197		* 'desc' => ['age' => SORT_DESC],
198		* 'default' => 'asc',
199		* ]
200		* ```
201		*
202		* The name field is a virtual field name that consists of two real fields, `first_name` and `last_name`. Virtual
203		* field name is used in order string or order array while real fields are used in final sorting criteria.
204		*
205		* Each configuration has the following options:
206		*
207		* - `asc` - criteria for ascending sorting.
208		* - `desc` - criteria for descending sorting.
209		* - `default` - default sorting. Could be either `asc` or `desc`. If not specified, `asc` is used.
210		*/
211	7	public static function any(array $config = []): self
212		{
213	7	return new self(false, $config);
214		}
215
216		/**
217		* Get a new instance with logical fields order set from an order string.
218		*
219		* The string consists of comma-separated field names.
220		* If the name is prefixed with `-`, field order is descending.
221		* Otherwise, the order is ascending.
222		*
223		* @param string $orderString Logical fields order as comma-separated string.
224		*
225		* @return self New instance.
226		*/
227	77	public function withOrderString(string $orderString): self
228		{
229	77	$order = [];
230	77	$parts = preg_split('/\s,\s/', trim($orderString), -1, PREG_SPLIT_NO_EMPTY);
231
232	77	foreach ($parts as $part) {
233	77	if (str_starts_with($part, '-')) {
234	18	$order[substr($part, 1)] = 'desc';
235		} else {
236	61	$order[$part] = 'asc';
237		}
238		}
239
240	77	return $this->withOrder($order);
241		}
242
243		/**
244		* Return a new instance with logical fields order set.
245		*
246		* @param array $order A map with logical field names to order by as keys, direction as values.
247		* @psalm-param TOrder $order
248		*
249		* @return self New instance.
250		*/
251	95	public function withOrder(array $order): self
252		{
253	95	$new = clone $this;
254	95	$new->currentOrder = $order;
255	95	return $new;
256		}
257
258		/**
259		* Return a new instance without default sorting set.
260		*
261		* @return self New instance.
262		*/
263	2	public function withoutDefaultSorting(): self
264		{
265	2	$new = clone $this;
266	2	$new->withDefaultSorting = false;
267	2	return $new;
268		}
269
270		/**
271		* Returns default order of logical fields' directions.
272		*
273		* Example of result:
274		*
275		* ```
276		* [
277		* 'id' => 'asc',
278		* 'name' => 'desc',
279		* ]
280		* ```
281		*
282		* @psalm-return TOrder
283		*/
284	1	public function getDefaults(): array
285		{
286	1	return array_map(
287	1	static fn($fieldConfig) => $fieldConfig['default'],
288	1	$this->config,
289	1	);
290		}
291
292		/**
293		* Get current logical fields order.
294		*
295		* @return array Logical fields order.
296		* @psalm-return TOrder
297		*/
298	78	public function getOrder(): array
299		{
300	78	return $this->currentOrder;
301		}
302
303		/**
304		* Get an order string based on current logical fields order.
305		*
306		* The string consists of comma-separated field names.
307		* If the name is prefixed with `-`, field order is descending.
308		* Otherwise, the order is ascending.
309		*
310		* @return string An order string.
311		*/
312	1	public function getOrderAsString(): string
313		{
314	1	$parts = [];
315
316	1	foreach ($this->currentOrder as $field => $direction) {
317	1	$parts[] = ($direction === 'desc' ? '-' : '') . $field;
318		}
319
320	1	return implode(',', $parts);
321		}
322
323		/**
324		* Get a sorting criteria to be applied to {@see SortableDataInterface}
325		* when obtaining the data i.e. a list of real fields along with their order directions.
326		*
327		* @return array Sorting criteria.
328		* @psalm-return array<string, int>
329		*/
330	92	public function getCriteria(): array
331		{
332	92	$criteria = [];
333	92	$config = $this->config;
334
335	92	foreach ($this->currentOrder as $field => $direction) {
336	86	if (array_key_exists($field, $config)) {
337	83	$criteria = array_merge($criteria, $config[$field][$direction]);
338	83	unset($config[$field]);
339		} else {
340	6	if ($this->ignoreExtraFields) {
341	3	continue;
342		}
343	3	$criteria = array_merge($criteria, [$field => $direction === 'desc' ? SORT_DESC : SORT_ASC]);
344		}
345		}
346
347	92	if ($this->withDefaultSorting) {
348	91	foreach ($config as $fieldConfig) {
349	36	$criteria += $fieldConfig[$fieldConfig['default']];
350		}
351		}
352
353	92	return $criteria;
354		}
355		}
356

yiisoft / data

Pull Request — master (#156)

Sort::getDefaults() A

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like