KMP PHP API Reference

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

$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

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
throws
NotFoundException

When the specified approval entity does not exist

throws
MethodNotAllowedException

When the request method is not POST

throws
ForbiddenException

When the current user is not authorized to deny the approval

since

Activities Plugin 1.0.0

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|void

initialize()

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
bool

mobileApprove()

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|null

myQueue()

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
see
AuthorizationApprovalsController::getAuthorizationApprovalsQuery()

For query construction.

since

Activities Plugin 1.0.0

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|void

switchView()

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|void

viewGridData()

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|void

applyCustomFilterHandlers()

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:

  1. Query string parameters (user-applied filters)
  2. Saved user view configuration (when loading a saved view)
  3. 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
throws
ForbiddenException

When authorization fails

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:

  1. exportValue callback if defined in column metadata
  2. renderField path for nested entity access (e.g., 'member.name_for_herald')
  3. 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
Query

getQueueSystemViewCounts()

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:

  1. Query Mode (default): Uses the query from result to build SQL SELECT statements. Best for simple fields that map directly to database columns.

  2. 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):

  1. exportValue callback in column metadata - custom formatting function
  2. renderField path (e.g., 'member.name_for_herald') - for nested entity access
  3. queryField for relation columns in query mode
  4. 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
throws
ForbiddenException

If user lacks export permission

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:

  1. Simple string (table name): Uses 'id' for value, 'name' for label

    'filterOptionsSource' => 'Branches'
    
  2. 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)
    ]
    
  3. 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.

  4. 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


        
On this page

Search results