Initial commit

application/Espo/Core/Select/Order/Applier.php

@@ -0,0 +1,233 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\Core\Acl;
+use Espo\Core\AclManager;
+use Espo\Core\Exceptions\BadRequest;
+use Espo\Core\ORM\Type\FieldType;
+use Espo\Entities\User;
+use Espo\ORM\Name\Attribute;
+use Espo\ORM\Query\Part\OrderList;
+use Espo\Core\Exceptions\Forbidden;
+use Espo\Core\Select\Order\Item as OrderItem;
+use Espo\Core\Select\Order\Params as OrderParams;
+use Espo\Core\Select\SearchParams;
+use Espo\ORM\Query\SelectBuilder as QueryBuilder;
+
+use RuntimeException;
+
+class Applier
+{
+    public function __construct(
+        private string $entityType,
+        private MetadataProvider $metadataProvider,
+        private ItemConverterFactory $itemConverterFactory,
+        private OrdererFactory $ordererFactory,
+        private AclManager $aclManager,
+        private User $user,
+    ) {}
+
+    /**
+     * @throws Forbidden
+     * @throws BadRequest
+     */
+    public function apply(QueryBuilder $queryBuilder, OrderParams $params): void
+    {
+        if ($params->forceDefault()) {
+            $this->applyDefaultOrder($queryBuilder, $params->getOrder());
+
+            return;
+        }
+
+        $orderBy = $params->getOrderBy();
+
+        if ($orderBy) {
+            if (
+                str_contains($orderBy, '.') ||
+                str_contains($orderBy, ':')
+            ) {
+                throw new Forbidden("Complex expressions are forbidden in 'orderBy'.");
+            }
+
+            if ($this->metadataProvider->isFieldOrderDisabled($this->entityType, $orderBy)) {
+                throw new Forbidden("Order by the field '$orderBy' is disabled.");
+            }
+
+            if ($this->metadataProvider->getFieldType($this->entityType, $orderBy) === FieldType::PASSWORD) {
+                throw new Forbidden("Order by field '$orderBy' is not allowed.");
+            }
+
+            if (
+                $params->applyPermissionCheck() &&
+                !$this->aclManager->checkField($this->user, $this->entityType, $orderBy)
+            ) {
+                throw new Forbidden("Not access to order by field '$orderBy'.");
+            }
+        }
+
+        if ($orderBy === null) {
+            $orderBy = $this->metadataProvider->getDefaultOrderBy($this->entityType);
+        }
+
+        if (!$orderBy) {
+            return;
+        }
+
+        $this->applyOrder($queryBuilder, $orderBy, $params->getOrder());
+    }
+
+    /**
+     * @param SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null $order
+     * @throws BadRequest
+     */
+    private function applyDefaultOrder(QueryBuilder $queryBuilder, ?string $order): void
+    {
+        $orderBy = $this->metadataProvider->getDefaultOrderBy($this->entityType);
+
+        if (!$orderBy) {
+            $queryBuilder->order(Attribute::ID, $order);
+
+            return;
+        }
+
+        if (!$order) {
+            $order = $this->metadataProvider->getDefaultOrder($this->entityType);
+
+            if ($order && strtolower($order) === 'desc') {
+                $order = SearchParams::ORDER_DESC;
+            } else if ($order && strtolower($order) === 'asc') {
+                $order = SearchParams::ORDER_ASC;
+            } else if ($order !== null) {
+                throw new RuntimeException("Bad default order.");
+            }
+        }
+
+        /** @var SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null $order */
+
+        $this->applyOrder($queryBuilder, $orderBy, $order);
+    }
+
+    /**
+     * @param SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null $order
+     * @throws BadRequest
+     */
+    private function applyOrder(QueryBuilder $queryBuilder, string $orderBy, ?string $order): void
+    {
+        if (!$orderBy) {
+            throw new RuntimeException("Could not apply empty order.");
+        }
+
+        if ($order === null) {
+            $order = SearchParams::ORDER_ASC;
+        }
+
+        $hasOrderer = $this->ordererFactory->has($this->entityType, $orderBy);
+
+        if ($hasOrderer) {
+            $orderer = $this->ordererFactory->create($this->entityType, $orderBy);
+
+            $orderer->apply(
+                $queryBuilder,
+                OrderItem::create($orderBy, $order)
+            );
+
+            if ($order !== Attribute::ID) {
+                $queryBuilder->order(Attribute::ID, $order);
+            }
+
+            return;
+        }
+
+        $resultOrderBy = $orderBy;
+
+        $type = $this->metadataProvider->getFieldType($this->entityType, $orderBy);
+
+        $hasItemConverter = $this->itemConverterFactory->has($this->entityType, $orderBy);
+
+        if ($hasItemConverter) {
+            $converter = $this->itemConverterFactory->create($this->entityType, $orderBy);
+
+            $resultOrderBy = $this->orderListToArray(
+                $converter->convert(
+                    OrderItem::create($orderBy, $order)
+                )
+            );
+        } else if (in_array($type, [FieldType::LINK, FieldType::FILE, FieldType::IMAGE, FieldType::LINK_ONE])) {
+            $resultOrderBy .= 'Name';
+        } else if ($type === FieldType::LINK_PARENT) {
+            $resultOrderBy .= 'Type';
+        } else if (
+            !$this->metadataProvider->hasAttribute($this->entityType, $orderBy)
+        ) {
+            throw new BadRequest("Order by non-existing field '$orderBy'.");
+        }
+
+        $orderByAttribute = null;
+
+        if (!is_array($resultOrderBy)) {
+            $orderByAttribute = $resultOrderBy;
+
+            $resultOrderBy = [
+                [$resultOrderBy, $order]
+            ];
+        }
+
+        if (
+            $orderBy !== Attribute::ID &&
+            (
+                !$orderByAttribute ||
+                !$this->metadataProvider->isAttributeParamUniqueTrue($this->entityType, $orderByAttribute)
+            ) &&
+            $this->metadataProvider->hasAttribute($this->entityType, Attribute::ID)
+        ) {
+            $resultOrderBy[] = [Attribute::ID, $order];
+        }
+
+        $queryBuilder->order($resultOrderBy);
+    }
+
+    /**
+     * @return array<array{string, string}>
+     */
+    private function orderListToArray(OrderList $orderList): array
+    {
+        $list = [];
+
+        foreach ($orderList as $order) {
+            $list[] = [
+                $order->getExpression()->getValue(),
+                $order->getDirection(),
+            ];
+        }
+
+        return $list;
+    }
+}

application/Espo/Core/Select/Order/Item.php

@@ -0,0 +1,90 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\Core\Select\SearchParams;
+
+use InvalidArgumentException;
+
+/**
+ * Immutable.
+ */
+class Item
+{
+    private string $orderBy;
+    /** @var SearchParams::ORDER_ASC|SearchParams::ORDER_DESC */
+    private string $order;
+
+    /**
+     * @param SearchParams::ORDER_ASC|SearchParams::ORDER_DESC $order
+     */
+    private function __construct(string $orderBy, string $order)
+    {
+        if (
+            $order !== SearchParams::ORDER_ASC &&
+            $order !== SearchParams::ORDER_DESC
+        ) {
+            throw new InvalidArgumentException("Bad order.");
+        }
+
+        $this->orderBy = $orderBy;
+        $this->order = $order;
+    }
+
+    /**
+     * @param SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null $order
+     */
+    public static function create(string $orderBy, ?string $order = null): self
+    {
+        if ($order === null) {
+            $order = SearchParams::ORDER_ASC;
+        }
+
+        return new self($orderBy, $order);
+    }
+
+    /**
+     * Get a field.
+     */
+    public function getOrderBy(): string
+    {
+        return $this->orderBy;
+    }
+
+    /**
+     * Get a direction.
+     *
+     * @return SearchParams::ORDER_ASC|SearchParams::ORDER_DESC
+     */
+    public function getOrder(): string
+    {
+        return $this->order;
+    }
+}

application/Espo/Core/Select/Order/ItemConverter.php

@@ -0,0 +1,40 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\ORM\Query\Part\OrderList;
+
+/**
+ * Converts an order item (passed from front-end) to an ORM order list.
+ */
+interface ItemConverter
+{
+    public function convert(Item $item): OrderList;
+}

application/Espo/Core/Select/Order/ItemConverterFactory.php

@@ -0,0 +1,113 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\Entities\User;
+
+use Espo\Core\InjectableFactory;
+use Espo\Core\Utils\Metadata;
+use Espo\Core\Binding\BindingContainerBuilder;
+use Espo\Core\Binding\ContextualBinder;
+
+use Espo\ORM\Defs\Params\FieldParam;
+use RuntimeException;
+
+class ItemConverterFactory
+{
+    public function __construct(
+        private InjectableFactory $injectableFactory,
+        private Metadata $metadata,
+        private User $user
+    ) {}
+
+    public function has(string $entityType, string $field): bool
+    {
+        return (bool) $this->getClassName($entityType, $field);
+    }
+
+    public function create(string $entityType, string $field): ItemConverter
+    {
+        $className = $this->getClassName($entityType, $field);
+
+        if (!$className) {
+            throw new RuntimeException("Order item converter class name is not defined.");
+        }
+
+        $container = BindingContainerBuilder::create()
+            ->bindInstance(User::class, $this->user)
+            ->inContext($className, function (ContextualBinder $binder) use ($entityType) {
+                $binder->bindValue('$entityType', $entityType);
+            })
+            ->build();
+
+        return $this->injectableFactory->createWithBinding($className, $container);
+    }
+
+    /**
+     * @return ?class-string<ItemConverter>
+     */
+    private function getClassName(string $entityType, string $field): ?string
+    {
+        /** @var ?class-string<ItemConverter> $className1 */
+        $className1 = $this->metadata->get([
+            'selectDefs', $entityType, 'orderItemConverterClassNameMap', $field
+        ]);
+
+        if ($className1) {
+            return $className1;
+        }
+
+        $type = $this->metadata->get([
+            'entityDefs', $entityType, 'fields', $field, FieldParam::TYPE
+        ]);
+
+        if (!$type) {
+            return null;
+        }
+
+        /** @var ?class-string<ItemConverter> $className2 */
+        $className2 = $this->metadata->get([
+            'app', 'select', 'orderItemConverterClassNameMap', $type
+        ]);
+
+        if ($className2) {
+            return $className2;
+        }
+
+        $className3 = 'Espo\\Core\\Select\\Order\\ItemConverters\\' . ucfirst($type) . 'Type';
+
+        if (class_exists($className3)) {
+            /** @var class-string<ItemConverter> */
+            return $className3;
+        }
+
+        return null;
+    }
+}

application/Espo/Core/Select/Order/ItemConverters/AddressType.php

@@ -0,0 +1,51 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order\ItemConverters;
+
+use Espo\ORM\Query\Part\OrderList;
+use Espo\ORM\Query\Part\Order;
+
+use Espo\Core\Select\Order\Item;
+use Espo\Core\Select\Order\ItemConverter;
+
+class AddressType implements ItemConverter
+{
+    public function convert(Item $item): OrderList
+    {
+        $orderBy = $item->getOrderBy();
+        $order = $item->getOrder();
+
+        return OrderList::create([
+            Order::fromString($orderBy . 'Country')->withDirection($order),
+            Order::fromString($orderBy . 'City')->withDirection($order),
+            Order::fromString($orderBy . 'Street')->withDirection($order),
+        ]);
+    }
+}

application/Espo/Core/Select/Order/ItemConverters/EnumType.php

@@ -0,0 +1,79 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order\ItemConverters;
+
+use Espo\ORM\Query\Part\OrderList;
+use Espo\ORM\Query\Part\Order;
+use Espo\ORM\Query\Part\Expression;
+use Espo\Core\Select\Order\Item;
+use Espo\Core\Select\Order\ItemConverter;
+use Espo\Core\Select\SearchParams;
+use Espo\Core\Utils\Metadata;
+
+class EnumType implements ItemConverter
+{
+    public function __construct(
+        private string $entityType,
+        private Metadata $metadata
+    ) {}
+
+    public function convert(Item $item): OrderList
+    {
+        $orderBy = $item->getOrderBy();
+        $order = $item->getOrder();
+
+        /** @var ?string[] $list */
+        $list = $this->metadata->get([
+            'entityDefs', $this->entityType, 'fields', $orderBy, 'options'
+        ]);
+
+        if (!is_array($list) || !count($list)) {
+            return OrderList::create([
+                Order::fromString($orderBy)->withDirection($order)
+            ]);
+        }
+
+        $isSorted = $this->metadata->get([
+            'entityDefs', $this->entityType, 'fields', $orderBy, 'isSorted'
+        ]);
+
+        if ($isSorted) {
+            asort($list);
+        }
+
+        if ($order === SearchParams::ORDER_DESC) {
+            $list = array_reverse($list);
+        }
+
+        return OrderList::create([
+            Order::createByPositionInList(Expression::column($orderBy), $list),
+        ]);
+    }
+}

application/Espo/Core/Select/Order/MetadataProvider.php

@@ -0,0 +1,85 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\Core\Utils\Metadata;
+use Espo\ORM\Defs\Params\FieldParam;
+use Espo\ORM\EntityManager;
+
+class MetadataProvider
+{
+    public function __construct(private Metadata $metadata, private EntityManager $entityManager)
+    {}
+
+    public function getFieldType(string $entityType, string $field): ?string
+    {
+        return $this->metadata->get([
+            'entityDefs', $entityType, 'fields', $field, FieldParam::TYPE
+        ]) ?? null;
+    }
+
+    public function getDefaultOrderBy(string $entityType): ?string
+    {
+        return $this->metadata->get([
+            'entityDefs', $entityType, 'collection', 'orderBy'
+        ]) ?? null;
+    }
+
+    public function getDefaultOrder(string $entityType): ?string
+    {
+        return $this->metadata->get([
+            'entityDefs', $entityType, 'collection', 'order'
+        ]) ?? null;
+    }
+
+    public function isFieldOrderDisabled(string $entityType, string $field): bool
+    {
+        return $this->metadata->get("entityDefs.$entityType.fields.$field.orderDisabled") ?? false;
+    }
+
+    public function hasAttribute(string $entityType, string $attribute): bool
+    {
+        return $this->entityManager
+            ->getMetadata()
+            ->getDefs()
+            ->getEntity($entityType)
+            ->hasAttribute($attribute);
+    }
+
+    public function isAttributeParamUniqueTrue(string $entityType, string $attribute): bool
+    {
+        return (bool) $this->entityManager
+            ->getMetadata()
+            ->getDefs()
+            ->getEntity($entityType)
+            ->getAttribute($attribute)
+            ->getParam('unique');
+    }
+}

application/Espo/Core/Select/Order/Orderer.php

@@ -0,0 +1,40 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\ORM\Query\SelectBuilder;
+
+/**
+ * A custom orderer. Should call SelectBuilder::order.
+ */
+interface Orderer
+{
+    public function apply(SelectBuilder $queryBuilder, Item $item): void;
+}

application/Espo/Core/Select/Order/OrdererFactory.php

@@ -0,0 +1,81 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\Core\InjectableFactory;
+use Espo\Core\Utils\Metadata;
+use Espo\Core\Binding\BindingContainerBuilder;
+use Espo\Core\Binding\ContextualBinder;
+
+use Espo\Entities\User;
+use RuntimeException;
+
+class OrdererFactory
+{
+    public function __construct(
+        private InjectableFactory $injectableFactory,
+        private Metadata $metadata,
+        private User $user
+    ) {}
+
+    public function has(string $entityType, string $field): bool
+    {
+        return (bool) $this->getClassName($entityType, $field);
+    }
+
+    public function create(string $entityType, string $field): Orderer
+    {
+        $className = $this->getClassName($entityType, $field);
+
+        if (!$className) {
+            throw new RuntimeException("Orderer class name is not defined.");
+        }
+
+        $container = BindingContainerBuilder::create()
+            ->bindInstance(User::class, $this->user)
+            ->inContext($className, function (ContextualBinder $binder) use ($entityType) {
+                $binder->bindValue('$entityType', $entityType);
+            })
+            ->build();
+
+        return $this->injectableFactory->createWithBinding($className, $container);
+    }
+
+    /**
+     * @return ?class-string<Orderer>
+     */
+    private function getClassName(string $entityType, string $field): ?string
+    {
+        /** @var ?class-string<Orderer> */
+        return $this->metadata->get([
+            'selectDefs', $entityType, 'ordererClassNameMap', $field
+        ]);
+    }
+}

application/Espo/Core/Select/Order/Params.php

@@ -0,0 +1,126 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\Select\Order;
+
+use Espo\Core\Select\SearchParams;
+
+use InvalidArgumentException;
+
+/**
+ * Order parameters.
+ *
+ * Immutable.
+ */
+class Params
+{
+    private bool $forceDefault = false;
+    private mixed $orderBy = null;
+    /** @var SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null */
+    private $order = null;
+    private bool $applyPermissionCheck = false;
+
+    private function __construct() {}
+
+    /**
+     * @param array{
+     *     forceDefault?: bool,
+     *     orderBy?: ?string,
+     *     order?: SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null,
+     *     applyPermissionCheck?: bool,
+     * } $params
+     */
+    public static function fromAssoc(array $params): self
+    {
+        $object = new self();
+
+        $object->forceDefault = $params['forceDefault'] ?? false;
+        $object->orderBy = $params['orderBy'] ?? null;
+        $object->order = $params['order'] ?? null;
+        $object->applyPermissionCheck = $params['applyPermissionCheck'] ?? false;
+
+        foreach ($params as $key => $value) {
+            if (!property_exists($object, $key)) {
+                throw new InvalidArgumentException("Unknown parameter '{$key}'.");
+            }
+        }
+
+        if ($object->orderBy && !is_string($object->orderBy)) {
+            throw new InvalidArgumentException("Bad orderBy.");
+        }
+
+        /** @var ?string $order */
+        $order = $object->order;
+
+        if (
+            $order &&
+            $order !== SearchParams::ORDER_ASC &&
+            $order !== SearchParams::ORDER_DESC
+        ) {
+            throw new InvalidArgumentException("Bad order.");
+        }
+
+        return $object;
+    }
+
+    /**
+     * Force default order.
+     */
+    public function forceDefault(): bool
+    {
+        return $this->forceDefault;
+    }
+
+    /**
+     * An order-By field.
+     */
+    public function getOrderBy(): ?string
+    {
+        /** @var ?string */
+        return $this->orderBy;
+    }
+
+    /**
+     * An order direction.
+     *
+     * @return SearchParams::ORDER_ASC|SearchParams::ORDER_DESC|null
+     */
+    public function getOrder(): ?string
+    {
+        return $this->order;
+    }
+
+    /**
+     * Apply permission check.
+     */
+    public function applyPermissionCheck(): bool
+    {
+        return $this->applyPermissionCheck;
+    }
+}