<?php

declare(strict_types=1);

/*
 * Chill is a software for social workers
 *
 * For the full copyright and license information, please view
 * the LICENSE file that was distributed with this source code.
 */

namespace Chill\MainBundle\Workflow\Helper;

/**
 * Helper to give supplementary permissions to a related entity.
 *
 * If a related entity is associated within a workflow, the logic of the workflow can give more permissions, or
 * remove some permissions.
 *
 * The methods of this helper return either:
 *
 * - FORCE_GRANT, which means that a permission can be given, even if it would be denied when the related
 *   entity is not associated with a workflow;
 * - FORCE_DENIED, which means that a permission should be denied, even if it would be granted when the related entity
 *   is not associated with a workflow
 * - ABSTAIN, if there is no workflow logic to add or remove permission
 *
 * For read operations:
 *
 * - if the user is involved in the workflow (is part of the current step, of a step before), the user is granted read
 *   operation;
 * - if there is a pending signature for a person, the workflow grant access to the related entity;
 * - if there a signature applyied in less than 12 hours, the workflow grant access to the related entity. This allow to
 *   show the related entity to the person during this time frame.
 *
 *
 * For write operation:
 *
 * - if the workflow is finalized "positive" (means "not canceled"), the workflow denys write operations;
 * - if there isn't any finalized "positive" workflow, and if there is a signature appliyed for a running workflow (not finalized nor canceled),
 *   the workflow denys write operations;
 * - if there is no case above and the user is involved in the workflow (is part of the current step, of a step before), the user is granted;
 */
interface WorkflowRelatedEntityPermissionHelperInterface
{
    public const FORCE_GRANT = 'FORCE_GRANT';
    public const FORCE_DENIED = 'FORCE_DENIED';
    public const ABSTAIN = 'ABSTAIN';

    /**
     * @param object $entity The entity may be an object that is a related entity of a workflow, or an EntityWorkflow itself
     *
     * @return 'FORCE_GRANT'|'FORCE_DENIED'|'ABSTAIN'
     */
    public function isAllowedByWorkflowForReadOperation(object $entity): string;

    /**
     * @param object $entity the entity may be an object which is the related entity of a workflow
     *
     * @return 'FORCE_GRANT'|'FORCE_DENIED'|'ABSTAIN'
     */
    public function isAllowedByWorkflowForWriteOperation(object $entity): string;
}
