Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Modules\Profiles\Application\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Profiles\Domain\Model\PermissionProfile;
12
13/**
14 * Profile Permission Application Service Contract.
15 *
16 * Defines use cases for managing module and field security for profiles.
17 *
18 * @package App\Modules\Profiles\Application\Service
19 */
20interface ProfilePermissionServiceInterface
21{
22    /**
23     * Retrieves the profile aggregate entity by ID.
24     *
25     * @param int $profileId Profile identifier.
26     * @return PermissionProfile|null Profile entity or null.
27     */
28    public function getProfile(int $profileId): ?PermissionProfile;
29
30    /**
31     * Builds comprehensive module & field permissions matrix for the specified profile.
32     *
33     * @param int $profileId Profile identifier.
34     * @return array<string, mixed> Hierarchical permissions matrix.
35     */
36    public function buildPermissionMatrix(int $profileId): array;
37
38    /**
39     * Builds comprehensive module & field permissions matrix for a user.
40     *
41     * @param int $userId Target user identifier.
42     * @return array<string, mixed> Hierarchical permissions matrix for user.
43     */
44    public function buildUserPermissionMatrix(int $userId): array;
45
46    /**
47     * Determines whether a module belongs to the end-user client operational scope.
48     *
49     * @param string $moduleName Machine module name.
50     * @return bool True if client operational module, false if admin/system/config module.
51     */
52    public function isClientModule(string $moduleName): bool;
53
54    /**
55     * Updates module-level permissions for a specific module in a profile.
56     *
57     * @param int    $profileId  Profile identifier.
58     * @param string $moduleName Machine module name.
59     * @param bool   $canView    View permission flag.
60     * @param bool   $canCreate  Create permission flag.
61     * @param bool   $canEdit    Edit permission flag.
62     * @param bool   $canDelete  Delete permission flag.
63     */
64    public function updateModulePermission(
65        int    $profileId,
66        string $moduleName,
67        bool   $canView,
68        bool   $canCreate,
69        bool   $canEdit,
70        bool   $canDelete
71    ): void;
72
73    /**
74     * Bulk updates a specific action permission across all modules for a profile.
75     *
76     * @param int    $profileId Target profile ID.
77     * @param string $action    Target action ('view', 'create', 'edit', 'delete').
78     * @param bool   $value     Permission value.
79     */
80    public function bulkUpdateModulePermission(int $profileId, string $action, bool $value): void;
81
82    /**
83     * Updates field-level security permission for a single field in a profile.
84     *
85     * @param int    $profileId  Profile identifier.
86     * @param string $moduleName Machine module name.
87     * @param string $fieldKey   Field key name.
88     * @param string $permission String representation ('edit', 'view', 'hide').
89     */
90    public function updateFieldPermission(
91        int    $profileId,
92        string $moduleName,
93        string $fieldKey,
94        string $permission
95    ): void;
96
97    /**
98     * Bulk updates all fields of a module to the specified permission level.
99     *
100     * @param int    $profileId  Target profile ID.
101     * @param string $moduleName Machine module name.
102     * @param string $permission Permission string ('edit', 'view', 'hide').
103     */
104    public function bulkUpdateFieldPermissions(
105        int    $profileId,
106        string $moduleName,
107        string $permission
108    ): void;
109
110    /**
111     * Saves entire permission matrix (modules and fields) in an atomic operation.
112     *
113     * @param int                        $profileId Target profile ID.
114     * @param list<array<string, mixed>> $modules   Module permissions list.
115     * @param list<array<string, mixed>> $fields    Field permissions list.
116     */
117    public function savePermissionMatrix(
118        int   $profileId,
119        array $modules,
120        array $fields
121    ): void;
122}