<?php
/**
 * Scope Class
 *
 * @version     1.0.$Revision:$
 * @version     SVN: $Id:$
 * @package     bplan-base/globals
 * @subpackage  Scopes
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 * @copyright   Copyright (C) 2025, 2026 bplan-solutions GmbH & Co. KG <https://www.bplan-solutions.de/>
 * /Δ\
 */

namespace BplanBase\Globals\Scopes;


use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;


/**
 * Scope Class
 *
 * Restricts queries to the current tenant by checking existence of a related
 * parent model that itself carries a TenantScope. This avoids adding a
 * redundant tenant_id column to child tables.
 *
 * @version     1.0.0 / 2026-04-13
 * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
 */
class TenantScopeViaRelation implements Scope
{


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


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


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


    /**
     * The name of the Eloquent relation to use for the EXISTS subquery.
     *
     * @var     string $_relation
     */
    private string $_relation;


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


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


    /**
     * @param       string $relation
     *              Name of the Eloquent relation on the child model whose
     *              parent carries a TenantScope (e.g. 'visitType').
     *
     * @version     1.0.0 / 2026-04-13
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public function __construct(string $relation)
    {
        $this->_relation = $relation;

    } // __construct()


    /**
     * Apply the scope to a given Eloquent query builder.
     *
     * Adds a WHERE EXISTS subquery on the specified relation. Because the
     * parent model has its own TenantScope, that scope is automatically
     * applied inside the subquery.
     *
     * @param       Builder $Builder
     *
     * @param       Model $Model
     *
     * @return      void
     *
     * @version     1.0.0 / 2026-04-13
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public function apply(Builder $Builder, Model $Model): void
    {
        $Builder->whereHas($this->_relation);

    } // apply()


    /**
     * Extend the query builder with a macro to bypass this scope.
     *
     * @param       Builder $Builder
     *
     * @return      void
     *
     * @version     1.0.0 / 2026-04-13
     * @author      Wassilios Meletiadis <wassilios.meletiadis@bplan-solutions.de>
     */
    public function extend(Builder $Builder): void
    {
        $Builder->macro('withoutTenancy', function (Builder $Builder) {
            return $Builder->withoutGlobalScope($this);
        });

    } // extend()


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


} // class TenantScopeViaRelation implements Scope {}
