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\Domain\Repository;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Modules\Profiles\Domain\Model\FieldPermissionType;
12use App\Modules\Profiles\Domain\Model\PermissionProfile;
13use App\Modules\Profiles\Domain\Model\ProfileFieldPermission;
14use App\Modules\Profiles\Domain\Model\ProfileModulePermission;
15
16/**
17 * Profile Permission Repository Contract.
18 *
19 * Defines data access methods for managing functional profiles and module/field security.
20 *
21 * @package App\Modules\Profiles\Domain\Repository
22 */
23interface ProfilePermissionRepositoryInterface
24{
25    /**
26     * Retrieves a permission profile by its primary key.
27     *
28     * @param int $profileId Profile identifier.
29     * @return PermissionProfile|null Profile entity or null if not found.
30     */
31    public function getProfile(int $profileId): ?PermissionProfile;
32
33    /**
34     * Retrieves all active permission profiles.
35     *
36     * @return list<PermissionProfile> List of active profiles.
37     */
38    public function getAllProfiles(): array;
39
40    /**
41     * Retrieves all module permissions for a given profile.
42     *
43     * @param int $profileId Profile identifier.
44     * @return array<string, ProfileModulePermission> Map of module permissions keyed by module name.
45     */
46    public function getModulePermissions(int $profileId): array;
47
48    /**
49     * Retrieves all field permissions for a given profile, optionally filtered by module.
50     *
51     * @param int         $profileId  Profile identifier.
52     * @param string|null $moduleName Optional module filter.
53     * @return array<string, ProfileFieldPermission> Map keyed by "module_name.field_key".
54     */
55    public function getFieldPermissions(int $profileId, ?string $moduleName = null): array;
56
57    /**
58     * Checks if a profile has view/read access to a module.
59     *
60     * @param int    $profileId  Profile identifier.
61     * @param string $moduleName Machine module name.
62     * @return bool True if permitted.
63     */
64    public function canViewModule(int $profileId, string $moduleName): bool;
65
66    /**
67     * Checks if a profile has create access to a module.
68     *
69     * @param int    $profileId  Profile identifier.
70     * @param string $moduleName Machine module name.
71     * @return bool True if permitted.
72     */
73    public function canCreateInModule(int $profileId, string $moduleName): bool;
74
75    /**
76     * Checks if a profile has edit/update access to a module.
77     *
78     * @param int    $profileId  Profile identifier.
79     * @param string $moduleName Machine module name.
80     * @return bool True if permitted.
81     */
82    public function canEditInModule(int $profileId, string $moduleName): bool;
83
84    /**
85     * Checks if a profile has delete access to a module.
86     *
87     * @param int    $profileId  Profile identifier.
88     * @param string $moduleName Machine module name.
89     * @return bool True if permitted.
90     */
91    public function canDeleteInModule(int $profileId, string $moduleName): bool;
92
93    /**
94     * Retrieves the permission type for a specific field within a module.
95     *
96     * @param int    $profileId  Profile identifier.
97     * @param string $moduleName Machine module name.
98     * @param string $fieldKey   Field key.
99     * @return FieldPermissionType Assigned permission type (defaults to EDIT).
100     */
101    public function getFieldPermission(int $profileId, string $moduleName, string $fieldKey): FieldPermissionType;
102
103    /**
104     * Sets or updates CRUD permissions for a module within a profile.
105     *
106     * @param int    $profileId  Profile identifier.
107     * @param string $moduleName Machine module name.
108     * @param bool   $canView    View permission flag.
109     * @param bool   $canCreate  Create permission flag.
110     * @param bool   $canEdit    Edit permission flag.
111     * @param bool   $canDelete  Delete permission flag.
112     */
113    public function setModulePermission(
114        int    $profileId,
115        string $moduleName,
116        bool   $canView,
117        bool   $canCreate,
118        bool   $canEdit,
119        bool   $canDelete
120    ): void;
121
122    /**
123     * Bulk sets a specific action permission across all modules for a profile.
124     *
125     * @param int    $profileId Target profile ID.
126     * @param string $action    Target action ('view', 'create', 'edit', 'delete').
127     * @param bool   $value     Permission boolean value.
128     */
129    public function bulkSetModulePermission(int $profileId, string $action, bool $value): void;
130
131    /**
132     * Sets or updates the field-level security permission for a specific field.
133     *
134     * @param int                 $profileId  Profile identifier.
135     * @param string              $moduleName Machine module name.
136     * @param string              $fieldKey   Field key.
137     * @param FieldPermissionType $permission Assigned permission type.
138     */
139    public function setFieldPermission(
140        int                 $profileId,
141        string              $moduleName,
142        string              $fieldKey,
143        FieldPermissionType $permission
144    ): void;
145
146    /**
147     * Bulk sets the field-level security permission for all fields of a module.
148     *
149     * @param int                 $profileId  Profile identifier.
150     * @param string              $moduleName Machine module name.
151     * @param FieldPermissionType $permission Assigned permission type.
152     */
153    public function bulkSetFieldPermissions(
154        int                 $profileId,
155        string              $moduleName,
156        FieldPermissionType $permission
157    ): void;
158
159    /**
160     * Saves entire permission matrix (modules and fields) in an atomic transaction.
161     *
162     * @param int                        $profileId Target profile ID.
163     * @param list<array<string, mixed>> $modules   Module permissions list.
164     * @param list<array<string, mixed>> $fields    Field permissions list.
165     */
166    public function saveMatrix(int $profileId, array $modules, array $fields): void;
167
168    /**
169     * Copies all functional and field-level permissions from source profile to target profile.
170     *
171     * @param int $sourceProfileId Source profile identifier.
172     * @param int $targetProfileId Target profile identifier.
173     */
174    public function copyPermissions(int $sourceProfileId, int $targetProfileId): void;
175
176    /**
177     * Explicitly invalidates any in-memory or runtime cache for a profile.
178     *
179     * @param int $profileId Profile identifier.
180     */
181    public function invalidateCache(int $profileId): void;
182}