AuthorizationApprovalsController
extends AppController
in package
uses
MailerAwareTrait, DataverseGridTrait
AuthorizationApprovals Controller - Approval Workflow Management
Manages authorization approval queues, multi-level approval processing, and workflow oversight. Handles approve/deny operations, personal queues, and administrative analytics.
Table of Contents
Constants
- VIEW_DATA_EVENT = 'KMP.plugins.callForViewData'
- VIEW_PLUGIN_EVENT = 'KMP.plugins.callForViewCells'
Properties
- $AuthorizationApprovals : AuthorizationApprovalsTable
- $isCsvRequest : bool
- $pluginViewCells : array<string|int, mixed>
Methods
- approve() : Response|null
- Process authorization approval and assign next approver if needed.
- availableApproversList() : Response
- Get available approvers for next approval step, excluding previous approvers.
- beforeFilter() : void
- Configure authorization and component setup.
- deny() : Response|null
- Process a denial for an authorization approval and redirect back to the referring page.
- gridData() : Response|null|void
- Provides Dataverse grid data for authorization approver rollup listing.
- index() : Response|null|void
- Display approval queue analytics and approver management dashboard.
- initialize() : void
- Initialize plugin controllers with authentication, authorization, and flash components.
- isCsvRequest() : bool
- Check if current request is for CSV export.
- mobileApprove() : Response|null
- Renders a mobile-optimized approval form for an authorization and processes approval submissions.
- mobileApproveAuthorizations() : void
- Mobile-optimized approval queue interface for processing authorization requests.
- mobileDeny() : Response|null
- Mobile-optimized denial form interface.
- myQueue() : mixed
- Display the authenticated approver's personal approval queue, optionally filtered by an email access token.
- myQueueGridData() : Response|null|void
- Provides Dataverse grid data for my-queue with system views for pending/approved/denied.
- switchView() : Response
- Switch between mobile and desktop view modes.
- view() : Response|null|void
- Display approval queue for a specific approver.
- viewGridData() : Response|null|void
- Provides Dataverse grid data for view queue with system views for pending/approved/denied.
- applyCustomFilterHandlers() : SelectQuery
- Apply custom filter handlers for columns with complex filtering logic
- authorizeCurrentUrl() : void
- Authorize the current URL/action via Authorization component.
- buildDataverseGridState() : array<string|int, mixed>
- Build complete grid state object (single source of truth)
- buildExportDataFromEntities() : array<string|int, mixed>
- Build export data from pre-processed entities (Data Mode)
- buildExportDataFromQuery() : array<string|int, mixed>
- Build export data from database query (Query Mode)
- extractExportValue() : string
- Extract export value from entity using column metadata
- extractFilterFromExpression() : mixed
- Recursively extract a filter value from an expression tree
- extractFilterFromSystemView() : mixed
- Extract a specific filter value from a system view configuration
- extractFilterFromViewConfig() : mixed
- Extract a specific filter value from a saved user view's config
- extractFilterGrouping() : array<string|int, mixed>
- Extract filter grouping information from expression tree
- extractSystemViewDefaults() : array{filters: array, dateRange: array, search: ?string, skipFilterColumns: array}
- Extract default filters/search metadata for a system view configuration
- formatExportValue() : string
- Format value for CSV export
- getAuthorizationApprovalsQuery() : Query
- Build query for authorization approvals with related data.
- getQueueSystemViewCounts() : array<string, int>
- Get counts for authorization approval queue system views
- handleCsvExport() : Response
- Handle CSV export from grid result
- isCsvExportRequest() : bool
- Check if the current request is for CSV export
- loadFilterOptions() : array<string|int, mixed>
- Load filter options from a data source
- organizeViewCells() : array<string|int, mixed>
- Organize view cells by type and display order.
- processDataverseGrid() : array<string|int, mixed>
- Process dataverse grid request with unified logic
- resolveNestedValue() : mixed
- Resolve nested value from entity using dot notation path
Constants
VIEW_DATA_EVENT
public
string
VIEW_DATA_EVENT
= 'KMP.plugins.callForViewData'
Event for plugin view data enhancement
VIEW_PLUGIN_EVENT
public
string
VIEW_PLUGIN_EVENT
= 'KMP.plugins.callForViewCells'
Event for plugin view cell registration
Properties
$AuthorizationApprovals
public
AuthorizationApprovalsTable
$AuthorizationApprovals
$isCsvRequest
protected
bool
$isCsvRequest
= false
Whether current request is for CSV export (.csv extension)
$pluginViewCells
protected
array<string|int, mixed>
$pluginViewCells
= []
View cells from plugins for current request
Methods
approve()
Process authorization approval and assign next approver if needed.
public
approve(AuthorizationManagerInterface $maService[, string|null $id = null ]) : Response|null
Parameters
- $maService : AuthorizationManagerInterface
-
Authorization management service
- $id : string|null = null
-
Authorization Approval ID
Return values
Response|null —Redirect to referer
availableApproversList()
Get available approvers for next approval step, excluding previous approvers.
public
availableApproversList(string $id) : Response
Parameters
- $id : string
-
Authorization Approval ID
Return values
Response —JSON response with available approvers
beforeFilter()
Configure authorization and component setup.
public
beforeFilter(EventInterface $event) : void
Parameters
- $event : EventInterface
-
The beforeFilter event
deny()
Process a denial for an authorization approval and redirect back to the referring page.
public
deny(AuthorizationManagerInterface $maService[, string|null $id = null ]) : Response|null
Calls the AuthorizationManager service to perform denial processing (including recording approver notes, terminating the approval workflow, triggering notifications, and writing audit information), flashes a success or error message for the user, and returns a redirect to the referrer.
Parameters
- $maService : AuthorizationManagerInterface
-
Authorization management service used to execute denial logic
- $id : string|null = null
-
Authorization Approval ID; if null the id will be read from request data
Tags
Return values
Response|null —Redirect response to the referring page or null
gridData()
Provides Dataverse grid data for authorization approver rollup listing.
public
gridData(CsvExportService $csvExportService) : Response|null|void
Parameters
- $csvExportService : CsvExportService
-
Injected CSV export service
Return values
Response|null|void —Renders grid view or CSV response
index()
Display approval queue analytics and approver management dashboard.
public
index() : Response|null|void
Return values
Response|null|voidinitialize()
Initialize plugin controllers with authentication, authorization, and flash components.
public
initialize() : void
isCsvRequest()
Check if current request is for CSV export.
public
isCsvRequest() : bool
Return values
boolmobileApprove()
Renders a mobile-optimized approval form for an authorization and processes approval submissions.
public
mobileApprove(AuthorizationManagerInterface $maService[, string|null $id = null ]) : Response|null
Displays authorization request details and whether further approvals are required. If the request is a POST, attempts to perform the approval via the provided authorization manager and redirects to the approver's mobile card on success; on failure it renders the form with an error flash message.
Parameters
- $maService : AuthorizationManagerInterface
-
Authorization management service used to perform approve operations.
- $id : string|null = null
-
Authorization Approval ID; if null the value is read from request data.
Return values
Response|null —A redirect response when the approval succeeds, or null after rendering the form or when approval fails.
mobileApproveAuthorizations()
Mobile-optimized approval queue interface for processing authorization requests.
public
mobileApproveAuthorizations() : void
Provides a mobile-friendly interface for approvers to view and process their pending authorization approval requests. Uses the mobile_app layout for consistent PWA experience.
mobileDeny()
Mobile-optimized denial form interface.
public
mobileDeny(AuthorizationManagerInterface $maService[, string|null $id = null ]) : Response|null
Displays authorization request details and allows approver to deny with reason. Handles both GET (display form) and POST (process denial).
Parameters
- $maService : AuthorizationManagerInterface
-
Authorization management service
- $id : string|null = null
-
Authorization Approval ID
Return values
Response|nullmyQueue()
Display the authenticated approver's personal approval queue, optionally filtered by an email access token.
public
myQueue([string|null $token = null ]) : mixed
When a token is provided, the queue is restricted to approvals matching that token to support secure email-based access; otherwise the method shows all pending approvals assigned to the authenticated user.
Parameters
- $token : string|null = null
-
Optional authorization token from an email notification used to filter the queue.
Tags
myQueueGridData()
Provides Dataverse grid data for my-queue with system views for pending/approved/denied.
public
myQueueGridData(CsvExportService $csvExportService) : Response|null|void
Parameters
- $csvExportService : CsvExportService
-
Injected CSV export service
Return values
Response|null|voidswitchView()
Switch between mobile and desktop view modes.
public
switchView() : Response
Stores preference in session and redirects to appropriate interface. Mobile redirects to viewMobileCard, desktop to profile.
Return values
Response —Redirect response
view()
Display approval queue for a specific approver.
public
view([string|null $id = null ]) : Response|null|void
Parameters
- $id : string|null = null
-
Approver member ID
Return values
Response|null|voidviewGridData()
Provides Dataverse grid data for view queue with system views for pending/approved/denied.
public
viewGridData(CsvExportService $csvExportService[, string|null $id = null ]) : Response|null|void
Parameters
- $csvExportService : CsvExportService
-
Injected CSV export service
- $id : string|null = null
-
Approver member ID
Return values
Response|null|voidapplyCustomFilterHandlers()
Apply custom filter handlers for columns with complex filtering logic
protected
applyCustomFilterHandlers(SelectQuery $query, array<string|int, mixed> $customFilterColumns, string $tableName, bool $canFilter, array<string|int, mixed> $currentFilters, mixed $currentView, array<string|int, mixed>|null $selectedSystemView, bool $dirtyFilters) : SelectQuery
Columns can define a customFilterHandler in their metadata to specify
a static method that handles their filtering. This allows complex filter
logic (like querying multiple tables) to be defined alongside the column
definition rather than requiring special controller knowledge.
Filter values are extracted from:
- Query string parameters (user-applied filters)
- Saved user view configuration (when loading a saved view)
- System view configuration (when loading a system view)
Parameters
- $query : SelectQuery
-
The query to filter
- $customFilterColumns : array<string|int, mixed>
-
Columns with customFilterHandler defined
- $tableName : string
-
The main table name
- $canFilter : bool
-
Whether user filtering is enabled
- $currentFilters : array<string|int, mixed>
-
Current filter values from query params
- $currentView : mixed
-
Current saved user view (or null)
- $selectedSystemView : array<string|int, mixed>|null
-
Current system view config (or null)
- $dirtyFilters : bool
-
Whether user explicitly modified filters
Return values
SelectQuery —The filtered query
authorizeCurrentUrl()
Authorize the current URL/action via Authorization component.
protected
authorizeCurrentUrl() : void
Tags
buildDataverseGridState()
Build complete grid state object (single source of truth)
protected
buildDataverseGridState(mixed $currentView, array<string|int, mixed>|null $selectedSystemView, array<string|int, mixed>|null $systemViews, iterable<string|int, mixed> $availableViews, Member|null $currentMember, string|int|null $preferredViewId, string $search, array<string|int, mixed> $filters, array<string|int, mixed> $filterOptions, array<string|int, mixed> $dropdownFilterColumns, array<string|int, mixed> $dateRangeFilterColumns, array<string|int, mixed> $sort, array<string|int, mixed> $visibleColumns, array<string|int, mixed> $allColumns, string $gridKey, int $pageSize, bool $showAllTab, bool $canAddViews, bool $canFilter, bool $hasSearch, bool $hasDropdownFilters, bool $hasDateRangeFilters, array<string|int, mixed> $skipFilterColumns, bool $canExportCsv, bool $showFilterPills, bool $showViewTabs, bool $enableColumnPicker[, array<string|int, mixed> $lockedFilters = [] ][, bool $enableBulkSelection = false ][, array<string|int, mixed> $bulkActions = [] ]) : array<string|int, mixed>
Parameters
- $currentView : mixed
-
Current saved view entity (null for system views or "All")
- $selectedSystemView : array<string|int, mixed>|null
-
Currently selected system view
- $systemViews : array<string|int, mixed>|null
-
All available system views
- $availableViews : iterable<string|int, mixed>
-
Collection of saved views
- $currentMember : Member|null
-
Authenticated member
- $preferredViewId : string|int|null
-
Preferred view ID from user preferences
- $search : string
-
Current search term
- $filters : array<string|int, mixed>
-
Active filters by column key
- $filterOptions : array<string|int, mixed>
-
Available filter options by column key
- $dropdownFilterColumns : array<string|int, mixed>
-
Metadata for filterable columns
- $dateRangeFilterColumns : array<string|int, mixed>
- $sort : array<string|int, mixed>
-
Current sort configuration
- $visibleColumns : array<string|int, mixed>
-
Array of visible column keys
- $allColumns : array<string|int, mixed>
-
Complete column metadata
- $gridKey : string
-
Unique grid identifier
- $pageSize : int
-
Number of rows per page
- $showAllTab : bool
-
Whether to show "All" tab
- $canAddViews : bool
-
Whether users can create custom views
- $canFilter : bool
-
Whether filtering is enabled
- $hasSearch : bool
- $hasDropdownFilters : bool
- $hasDateRangeFilters : bool
- $skipFilterColumns : array<string|int, mixed>
-
Columns with filter UI but not query application
- $canExportCsv : bool
-
Whether CSV export button is shown
- $showFilterPills : bool
-
Whether active filter pills/badges are displayed
- $showViewTabs : bool
-
Whether view tabs are displayed
- $enableColumnPicker : bool
-
Whether column picker is available
- $lockedFilters : array<string|int, mixed> = []
-
Filter column keys that cannot be removed by users
- $enableBulkSelection : bool = false
- $bulkActions : array<string|int, mixed> = []
Return values
array<string|int, mixed> —Complete grid state
buildExportDataFromEntities()
Build export data from pre-processed entities (Data Mode)
protected
buildExportDataFromEntities(iterable<string|int, mixed> $data, array<string|int, mixed> $visibleColumns, array<string|int, mixed> $columnsMetadata) : array<string|int, mixed>
Extracts values from entities using column metadata configuration. Supports virtual properties, nested relations via renderField, and custom exportValue callbacks.
Parameters
- $data : iterable<string|int, mixed>
-
Pre-processed entities or arrays
- $visibleColumns : array<string|int, mixed>
-
List of visible column keys
- $columnsMetadata : array<string|int, mixed>
-
Column configuration metadata
Return values
array<string|int, mixed> —Transformed data ready for CSV export
buildExportDataFromQuery()
Build export data from database query (Query Mode)
protected
buildExportDataFromQuery(Query $query, array<string|int, mixed> $visibleColumns, array<string|int, mixed> $columnsMetadata, string $tableName) : array<string|int, mixed>
Builds SQL SELECT statements and executes query for simple database fields. Best for exports that don't require computed fields.
Parameters
- $query : Query
-
Database query to execute
- $visibleColumns : array<string|int, mixed>
-
List of visible column keys
- $columnsMetadata : array<string|int, mixed>
-
Column configuration metadata
- $tableName : string
-
Full table name for model alias extraction
Return values
array<string|int, mixed> —Transformed data ready for CSV export
extractExportValue()
Extract export value from entity using column metadata
protected
extractExportValue(mixed $entity, string $columnKey, array<string|int, mixed> $columnMeta) : string
Resolution order:
- exportValue callback if defined in column metadata
- renderField path for nested entity access (e.g., 'member.name_for_herald')
- Direct property access using column key
Parameters
- $entity : mixed
-
Entity or array to extract value from
- $columnKey : string
-
Column key identifier
- $columnMeta : array<string|int, mixed>
-
Column metadata configuration
Return values
string —Extracted and formatted value
extractFilterFromExpression()
Recursively extract a filter value from an expression tree
protected
extractFilterFromExpression(array<string|int, mixed> $expression, string $columnKey) : mixed
Parameters
- $expression : array<string|int, mixed>
-
The expression node to search
- $columnKey : string
-
The column key to find
Return values
mixed —The filter value or null if not found
extractFilterFromSystemView()
Extract a specific filter value from a system view configuration
protected
extractFilterFromSystemView(array<string|int, mixed> $systemView, string $columnKey) : mixed
Parameters
- $systemView : array<string|int, mixed>
-
The system view configuration
- $columnKey : string
-
The column key to find
Return values
mixed —The filter value or null if not found
extractFilterFromViewConfig()
Extract a specific filter value from a saved user view's config
protected
extractFilterFromViewConfig(mixed $view, string $columnKey) : mixed
Parameters
- $view : mixed
-
The GridView entity
- $columnKey : string
-
The column key to find
Return values
mixed —The filter value or null if not found
extractFilterGrouping()
Extract filter grouping information from expression tree
protected
extractFilterGrouping(array<string|int, mixed>|null $selectedSystemView, array<string|int, mixed> $skipFilterColumns) : array<string|int, mixed>
Analyzes the expression tree to determine OR relationships between filters. Returns metadata that the frontend can use to display visual OR indicators.
Parameters
- $selectedSystemView : array<string|int, mixed>|null
-
Currently active system view
- $skipFilterColumns : array<string|int, mixed>
-
Columns that show as pills but don't query
Return values
array<string|int, mixed> —Grouping metadata with 'orGroups' array
extractSystemViewDefaults()
Extract default filters/search metadata for a system view configuration
protected
extractSystemViewDefaults(array<string, mixed> $systemViewConfig) : array{filters: array, dateRange: array, search: ?string, skipFilterColumns: array}
Parameters
- $systemViewConfig : array<string, mixed>
-
Raw system view config
Return values
array{filters: array, dateRange: array, search: ?string, skipFilterColumns: array}formatExportValue()
Format value for CSV export
protected
formatExportValue(mixed $value) : string
Handles various data types and converts to string representation.
Parameters
- $value : mixed
-
Value to format
Return values
string —Formatted string value
getAuthorizationApprovalsQuery()
Build query for authorization approvals with related data.
protected
getAuthorizationApprovalsQuery(int $memberId) : Query
Parameters
- $memberId : int
-
The approver member ID to filter by
Return values
QuerygetQueueSystemViewCounts()
Get counts for authorization approval queue system views
protected
getQueueSystemViewCounts(int $approverId[, string|null $token = null ]) : array<string, int>
Parameters
- $approverId : int
-
Approver member ID to get counts for
- $token : string|null = null
-
Optional token to filter by
Return values
array<string, int> —System view ID => count mapping
handleCsvExport()
Handle CSV export from grid result
protected
handleCsvExport(array<string|int, mixed> $result, CsvExportService $csvExportService, string $entityName[, string|null $tableName = null ][, iterable<string|int, mixed>|null $data = null ]) : Response
Generates a CSV export response from the grid processing result. Supports two modes:
-
Query Mode (default): Uses the query from result to build SQL SELECT statements. Best for simple fields that map directly to database columns.
-
Data Mode: Pass pre-processed data with computed/virtual fields already populated. Best for exports that include calculated fields, virtual properties, or complex transformations that can't be done in SQL.
Column Value Resolution (in order of precedence):
exportValuecallback in column metadata - custom formatting functionrenderFieldpath (e.g., 'member.name_for_herald') - for nested entity accessqueryFieldfor relation columns in query mode- Direct column key access on entity/array
Parameters
- $result : array<string|int, mixed>
-
Result from processDataverseGrid() with isCsvExport flag
- $csvExportService : CsvExportService
-
CSV export service instance
- $entityName : string
-
Base name for the export file (e.g., 'members', 'warrants')
- $tableName : string|null = null
-
Optional table name for fetchTable (e.g., 'Awards.Recommendations' for plugin tables) If not provided, uses ucfirst($entityName)
- $data : iterable<string|int, mixed>|null = null
-
Optional pre-processed data. If provided, uses data mode instead of query mode. Data should be an iterable of entities or arrays with all computed fields populated.
Tags
Return values
Response —CSV download response
isCsvExportRequest()
Check if the current request is for CSV export
protected
isCsvExportRequest() : bool
Return values
bool —True if CSV export is requested
loadFilterOptions()
Load filter options from a data source
protected
loadFilterOptions(array<string|int, mixed>|string $source) : array<string|int, mixed>
Supports multiple formats for filterOptionsSource:
-
Simple string (table name): Uses 'id' for value, 'name' for label
'filterOptionsSource' => 'Branches' -
Array with table: Database table with full control
'filterOptionsSource' => [ 'table' => 'Waivers.WaiverTypes', // Required: table name for fetchTable() 'valueField' => 'id', // Optional: field for option value (default: 'id') 'labelField' => 'name', // Optional: field for option label (default: 'name') 'conditions' => ['is_active' => true], // Optional: filter conditions 'order' => ['name' => 'ASC'], // Optional: sort order (default: labelField ASC) ] -
Array with appSetting: Load from app settings (YAML array)
'filterOptionsSource' => [ 'appSetting' => 'Branches.Types', // Required: app setting key ]The app setting should contain a YAML array like: ['Kingdom', 'Principality', 'Barony'] Both value and label will be set to the array item value.
-
Array with method: Call a static method on a class to get options
'filterOptionsSource' => [ 'method' => 'getGatheringsFilterOptions', // Required: static method name 'class' => 'Awards\\KMP\\GridColumns\\RecommendationsGridColumns', // Required: fully qualified class name ]The method should return array of ['value' => string, 'label' => string].
Parameters
- $source : array<string|int, mixed>|string
-
Source identifier string (table name) or configuration array
Return values
array<string|int, mixed> —Filter options as array of ['value' => string, 'label' => string]
organizeViewCells()
Organize view cells by type and display order.
protected
organizeViewCells(array<string|int, mixed> $viewCells) : array<string|int, mixed>
Unused - view cells organized in ViewCellRegistry
Parameters
- $viewCells : array<string|int, mixed>
-
Flat array of view cell configurations
Return values
array<string|int, mixed> —Organized array grouped by type and sorted by order
processDataverseGrid()
Process dataverse grid request with unified logic
protected
processDataverseGrid(array<string|int, mixed> $config) : array<string|int, mixed>
This method handles all aspects of grid processing including view management, filtering, searching, sorting, and pagination. It supports both saved user views and system-defined views.
Parameters
- $config : array<string|int, mixed>
-
Grid configuration with the following keys:
- gridKey (string): Unique identifier for the grid
- gridColumnsClass (string): Fully qualified class name for grid columns metadata
- baseQuery (Query): Base query object to start with
- tableName (string): Primary table name for field qualification
- defaultSort (array): Default sort configuration ['field' => 'direction']
- defaultPageSize (int): Default number of records per page (default: 25)
- systemViews (array|null): Optional array of system views (for Warrants-style grids)
- defaultSystemView (string|null): Default system view key (required if systemViews provided)
- queryCallback (callable|null): Optional callback to modify query per system view
- showAllTab (bool): Whether to show "All" tab (default: true for saved views, false for system views)
- canAddViews (bool): Whether users can create custom views (default: true)
- canFilter (bool): Whether user filtering is enabled (default: true). When false, users cannot add/remove filters via the UI or query parameters. However, filters defined by system views are ALWAYS applied regardless of this setting.
- canExportCsv (bool): Whether CSV export button is shown (default: true)
- showFilterPills (bool): Whether active filter pills/badges are displayed (default: true)
- showViewTabs (bool): Whether view tabs are displayed (default: true)
- enableColumnPicker (bool): Whether column picker is available (default: true)
- lockedFilters (array): Array of filter column keys that cannot be removed by users. Locked filters will not show remove (×) buttons and their values cannot be cleared via query string parameters. Useful for embedded grids where context filters (e.g., member_id) must always be applied.
- enableBulkSelection (bool): Whether row selection checkboxes are shown (default: false)
- bulkActions (array): Array of bulk action button configurations when enableBulkSelection is true. Each action is an array with keys: label, icon, modalTarget, permission.
NOTE: Authorization scope must be applied to baseQuery BEFORE calling this method. Use
$baseQuery = $this->Authorization->applyScope($baseQuery, 'index');in your controller before passing the query to processDataverseGrid().
Return values
array<string|int, mixed> —Result array with keys: data, gridState, columnsMetadata, etc.
resolveNestedValue()
Resolve nested value from entity using dot notation path
protected
resolveNestedValue(mixed $entity, string $path) : mixed
Parameters
- $entity : mixed
-
Entity to traverse
- $path : string
-
Dot-notation path (e.g., 'member.name_for_herald')
Return values
mixed —Resolved value or null if path doesn't exist