<?php
/**
 * Model OrderBy Scope Trait
 *
 * @version     1.0.$Revision:$
 * @version     SVN: $Id:$
 * @package     bplan-base/globals
 * @subpackage  Traits
 * @author      Emilio Cannarozzo <emilio.cannarozzo@bplan-solutions.de>
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025 bplan-solutions GmbH & Co. KG <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Traits;


use BplanBase\Globals\Helpers\QueryHelper;
use Illuminate\Database\Eloquent\Builder;


/**
 * Model OrderBy Scope Trait
 *
 * @version     1.0.0 / 2025-05-25
 * @author      Emilio Cannarozzo <emilio.cannarozzo@bplan-solutions.de>
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
trait HasOrderedScope
{


/* +++ TRAITS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS CONSTANTS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ OBJECT MEMBERS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS MEMBERS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ OBJECT METHODS +++ +++++++++++++++++++++++++++++++++++++++++++++++++++ */


/* +++ CLASS METHODS +++ ++++++++++++++++++++++++++++++++++++++++++++++++++++ */


    /**
     *
     * @param       Builder $Query
     *
     * @param       array|string|null $orderBy
     *              The ordering instructions.
     *              The $orderBy parameter can take several formats:
     *
     *              1. A single column name as a string:
     *                  'name'
     *
     *              2. An array of column names as strings (default direction: asc):
     *                  ['name', 'created_at']
     *
     *              3. An array of arrays with 'column' and optional 'direction':
     *                  [
     *                      ['column' => 'name'],
     *                      ['column' => 'created_at', 'direction' => 'desc']
     *                  ]
     *
     *              Mixed format is also supported:
     *                  [
     *                      'priority',
     *                      ['column' => 'created_at', 'direction' => 'desc']
     *                  ]
     *
     * @return      Builder
     *
     * @version     1.0.0 / 2025-05-25
     * @author      Emilio Cannarozzo <emilio.cannarozzo@bplan-solutions.de>
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public function scopeOrdered(Builder $Query, array|string|null $orderBy): Builder
    {
        return QueryHelper::applyOrderBy($Query, $orderBy);

    } // scopeOrdered()


} // trait HasOrderedScope {}
