Alpha Framework 4.0.0 API Documentation

DEnumController extends ActiveRecordController
in package
implements ControllerInterface

Controller used to edit DEnums and associated DEnumItems.

Tags
since
1.0
author

John Collins dev@alphaframework.org

license

http://www.opensource.org/licenses/bsd-license.php The BSD License

copyright

Copyright (c) 2021, John Collins (founder of Alpha Framework). All rights reserved.

Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:

* Redistributions of source code must retain the above
  copyright notice, this list of conditions and the
  following disclaimer.
* Redistributions in binary form must reproduce the above
  copyright notice, this list of conditions and the
  following disclaimer in the documentation and/or other
  materials provided with the distribution.
* Neither the name of the Alpha Framework nor the names
  of its contributors may be used to endorse or promote
  products derived from this software without specific
  prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents

Interfaces

ControllerInterface
The interface for all page controllers.

Properties

$description  : string
Meta description for the controller page.
$dirtyObjects  : array<string|int, mixed>
An array for storing dirty record objects in a session (i.e. persistent business objects that have not been updated in the database yet).
$filterField  : string
The name of the Record field to filter the list by (optional).
$filterValue  : string
The value of the filterField to filter by (optional).
$firstJob  : string
The name of the first controller that is used in this unit of work.
$keywords  : string
Meta keywords for the controller page, generally populated from tags.
$lastJob  : string
The name of the last controller that is used in this unit of work.
$limit  : int
The amount of records to return during pageination.
$name  : string
The name of the controller.
$newObjects  : array<string|int, mixed>
An array for storing new reord objects in a session (transient business objects that have no ID yet).
$nextJob  : string
The name of the next controller that is used in this unit of work.
$order  : string
The order to sort the list by (optional, should be ASC or DESC, default is ASC).
$previousJob  : string
The name of the previous controller that is used in this unit of work.
$record  : DEnum
DEnum to work on
$recordCount  : int
The count of the records of this type in the database (used during pagination).
$request  : Request
The request that has been passed to this controller for processing.
$sort  : string
The field name to sort the list by (optional, default is ID).
$start  : int
The start number for list pageination.
$statusMessage  : string
Used to set status update messages to display to the user (messages stored between requests in session). Useful for when you want to display a message to a user after POSTing a request, or when moving from one page to the next.
$title  : string
The title to be displayed on the controller page.
$unitEndTime  : Timestamp
Stores the end time of a unit of work transaction.
$unitOfWork  : string
Used to determine if the controller is part of a unit of work sequence (either empty or the name of the unit).
$unitStartTime  : Timestamp
Stores the start time of a unit of work transaction.
$visibility  : string
Used to set access privileages for the controller to the name of the rights group allowed to access it. 'Public' by default.
$logger  : Logger
Trace logger.

Methods

__construct()  : mixed
constructor to set up the object.
abort()  : void
Method to clearup a cancelled unit of work.
accessError()  : Response
Method to return an access error for trespassing users. HTTP response header code will be 403.
afterDisplayPageHead()  : string
Use this callback to inject in the admin menu template fragment.
beforeDisplayPageFoot()  : string
Method to display the page footer with pageination links.
checkControllerDefExists()  : bool
Checks that the definition for the controller classname provided exists. Will also return true if you pass "/" for the root of the web application.
checkIfAccessingFromSecureURL()  : bool
Method for determining if the current request URL is a secure one (has a tk string or not).
checkRights()  : bool
Checks the user rights of the currently logged-in person against the page visibility set for this controller. Will return false if the user has not got the correct rights.
checkSecurityFields()  : bool
Method to check the validity of the two hidden form security fields which aim to ensure that a post to the controller is being sent from the same server that is hosting it.
clearUnitOfWorkAttributes()  : void
Clears the session and object attributes related to unit of work sessions.
commit()  : void
Commits (saves) all of the new and modified (dirty) objects in the unit of work to the database.
doDELETE()  : Response
{@inheritdoc}
doGET()  : Response
Handle GET requests.
doHEAD()  : Response
{@inheritdoc}
doOPTIONS()  : Response
{@inheritdoc}
doPATCH()  : Response
{@inheritdoc}
doPOST()  : Response
Handle POST requests.
doPUT()  : Response
{@inheritdoc}
doTRACE()  : Response
{@inheritdoc}
generateSecurityFields()  : array<string|int, mixed>
Generates the two security fields to prevent remote form processing, returned as an array.
generateURLSlug()  : string
Converts the supplied string to a "slug" that is URL safe and suitable for SEO.
getCustomControllerName()  : string|null
Returns the name of a custom controller if one is found, otherwise returns null.
getDescription()  : string|null
Getter for the page description.
getDirtyObjects()  : array<string|int, mixed>
Getter for the dirty objects array.
getEndTime()  : Timestamp
Getter for the unit end time.
getFirstJob()  : string|null
Gets the name of the first job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.
getKeywords()  : string|null
Getter for the page keywords.
getLastJob()  : string|null
Gets the name of the last job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.
getLimit()  : int
Get the pagination limit
getName()  : string
Get the name of the unit of work job.
getNewObjects()  : array<string|int, mixed>
Getter for the new objects array.
getNextJob()  : string|null
Gets the name of the next job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.
getPreviousJob()  : string|null
Gets the name of the previous job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.
getRecord()  : ActiveRecord|null
Get the record for this controller (if any).
getRecordCount()  : int
Get the pagination record count
getRequest()  : Request
Get the request this controller is processing (if any).
getStart()  : int
Get the pagination start point
getStartTime()  : Timestamp
Getter for the unit start time.
getStatusMessage()  : string|null
Gets the current status message for this controller. Note that by getting the current status message, you clear out the value stored in the session so this method can only be used to get the status message once for display purposes.
getTitle()  : string
Getter for the page title.
getUnitDuration()  : int
Calculates and returns the unit of work current duration in seconds.
getVisibility()  : string
Get the name of the rights group that has access to this controller.
loadControllerDef()  : void
Loads the definition for the controller classname provided.
markDirty()  : void
Adds the supplied business object to the dirtyObjects array in the session.
markNew()  : void
Adds a newly created business object to the newObjects array in the session.
process()  : Response
Maps the supplied request with the appropiate method to run on this controller, for example GET to doGET(), POST to doPOST() etc. Returns the response generated by the method called.
setDescription()  : void
Setter for the page description.
setKeywords()  : void
Setter for the page keywords, should pass a comma-seperated list as a string.
setName()  : void
Setter for the unit of work job name.
setRecord()  : void
Setter for the record for this controller.
setRequest()  : void
Set the request this controller is processing.
setStatusMessage()  : void
Set the status message in the session to the value provided.
setTitle()  : void
Setter for the page title.
setUnitEndTime()  : void
Setter for the unit end time (value will be stored in the session as key unitEndTime).
setUnitOfWork()  : void
Sets the name of the controller job sequence to the values in the supplied array (and stores the array in the session).
setUnitStartTime()  : void
Setter for the unit start time (value will be stored in the session as key unitStartTime).
setVisibility()  : void
Setter for the name of the rights group that has access to this controller.
createDEnumTables()  : string
Method to create the DEnum tables if they don't exist.
decryptFieldNames()  : array<string|int, mixed>
Descrypts the HTTP param fieldnames in the array provided and returns the plain version.
renderRecord()  : string
Load the requested record and render the HTML or JSON for it.
renderRecords()  : string
Load all records of the type requested and render the HTML or JSON for them.

Properties

$description

Meta description for the controller page.

protected string $description
Tags
since
1.0

$dirtyObjects

An array for storing dirty record objects in a session (i.e. persistent business objects that have not been updated in the database yet).

protected array<string|int, mixed> $dirtyObjects = array()
Tags
since
1.0

$filterField

The name of the Record field to filter the list by (optional).

protected string $filterField
Tags
since
2.0

$filterValue

The value of the filterField to filter by (optional).

protected string $filterValue
Tags
since
2.0

$firstJob

The name of the first controller that is used in this unit of work.

protected string $firstJob
Tags
since
1.0

$keywords

Meta keywords for the controller page, generally populated from tags.

protected string $keywords
Tags
since
1.0

$lastJob

The name of the last controller that is used in this unit of work.

protected string $lastJob
Tags
since
1.0

$name

The name of the controller.

protected string $name
Tags
since
1.0

$newObjects

An array for storing new reord objects in a session (transient business objects that have no ID yet).

protected array<string|int, mixed> $newObjects = array()
Tags
since
1.0

$nextJob

The name of the next controller that is used in this unit of work.

protected string $nextJob
Tags
since
1.0

$order

The order to sort the list by (optional, should be ASC or DESC, default is ASC).

protected string $order
Tags
since
2.0

$previousJob

The name of the previous controller that is used in this unit of work.

protected string $previousJob
Tags
since
1.0

$recordCount

The count of the records of this type in the database (used during pagination).

protected int $recordCount = 0
Tags
since
2.0

$request

The request that has been passed to this controller for processing.

protected Request $request
Tags
since
2.0

$sort

The field name to sort the list by (optional, default is ID).

protected string $sort
Tags
since
2.0

$statusMessage

Used to set status update messages to display to the user (messages stored between requests in session). Useful for when you want to display a message to a user after POSTing a request, or when moving from one page to the next.

protected string $statusMessage
Tags
since
1.0

$title

The title to be displayed on the controller page.

protected string $title
Tags
since
1.0

$unitEndTime

Stores the end time of a unit of work transaction.

protected Timestamp $unitEndTime
Tags
since
1.0

$unitOfWork

Used to determine if the controller is part of a unit of work sequence (either empty or the name of the unit).

protected string $unitOfWork
Tags
since
1.0

$unitStartTime

Stores the start time of a unit of work transaction.

protected Timestamp $unitStartTime
Tags
since
1.0

$visibility

Used to set access privileages for the controller to the name of the rights group allowed to access it. 'Public' by default.

protected string $visibility = 'Public'
Tags
since
1.0

Methods

__construct()

constructor to set up the object.

public __construct() : mixed
Tags
since
1.0

accessError()

Method to return an access error for trespassing users. HTTP response header code will be 403.

public accessError() : Response
Tags
since
1.0
Return values
Response

afterDisplayPageHead()

Use this callback to inject in the admin menu template fragment.

public afterDisplayPageHead() : string
Tags
since
1.2
Return values
string

beforeDisplayPageFoot()

Method to display the page footer with pageination links.

public beforeDisplayPageFoot() : string
Tags
since
2.0
Return values
string

checkControllerDefExists()

Checks that the definition for the controller classname provided exists. Will also return true if you pass "/" for the root of the web application.

public static checkControllerDefExists(string $controllerName) : bool
Parameters
$controllerName : string
Tags
since
1.0
deprecated
Return values
bool

checkIfAccessingFromSecureURL()

Method for determining if the current request URL is a secure one (has a tk string or not).

public checkIfAccessingFromSecureURL() : bool
Tags
since
1.0
Return values
bool

checkRights()

Checks the user rights of the currently logged-in person against the page visibility set for this controller. Will return false if the user has not got the correct rights.

public checkRights() : bool
Tags
since
1.0
Return values
bool

checkSecurityFields()

Method to check the validity of the two hidden form security fields which aim to ensure that a post to the controller is being sent from the same server that is hosting it.

public checkSecurityFields() : bool
Tags
since
1.0
Return values
bool

clearUnitOfWorkAttributes()

Clears the session and object attributes related to unit of work sessions.

public clearUnitOfWorkAttributes() : void
Tags
since
1.0

commit()

Commits (saves) all of the new and modified (dirty) objects in the unit of work to the database.

public commit() : void
Tags
throws
FailedUnitCommitException
since
1.0

generateSecurityFields()

Generates the two security fields to prevent remote form processing, returned as an array.

public static generateSecurityFields() : array<string|int, mixed>
Tags
since
1.0
Return values
array<string|int, mixed>

generateURLSlug()

Converts the supplied string to a "slug" that is URL safe and suitable for SEO.

public static generateURLSlug(string $URLPart[, string $seperator = '-' ][, array<string|int, mixed> $filter = array() ][, bool $crc32Prefix = false ]) : string
Parameters
$URLPart : string

The part of the URL to use as the slug

$seperator : string = '-'

The URL seperator to use (default is -)

$filter : array<string|int, mixed> = array()

An optional array of charactors to filter out

$crc32Prefix : bool = false

Set to true if you want to prefix the slug with the CRC32 hash of the URLPart supplied

Tags
since
1.2.4
Return values
string

getCustomControllerName()

Returns the name of a custom controller if one is found, otherwise returns null.

public static getCustomControllerName(string $ActiveRecordType) : string|null
Parameters
$ActiveRecordType : string

The classname of the active record

Tags
since
1.0
Return values
string|null

getDescription()

Getter for the page description.

public getDescription() : string|null
Tags
since
1.0
Return values
string|null

getDirtyObjects()

Getter for the dirty objects array.

public getDirtyObjects() : array<string|int, mixed>
Tags
since
1.0
Return values
array<string|int, mixed>

getFirstJob()

Gets the name of the first job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.

public getFirstJob() : string|null
Tags
since
1.0
Return values
string|null

getKeywords()

Getter for the page keywords.

public getKeywords() : string|null
Tags
since
1.0
Return values
string|null

getLastJob()

Gets the name of the last job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.

public getLastJob() : string|null
Tags
since
1.0
Return values
string|null

getName()

Get the name of the unit of work job.

public getName() : string
Tags
since
1.0
Return values
string

getNewObjects()

Getter for the new objects array.

public getNewObjects() : array<string|int, mixed>
Tags
since
1.0
Return values
array<string|int, mixed>

getNextJob()

Gets the name of the next job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.

public getNextJob() : string|null
Tags
since
1.0
Return values
string|null

getPreviousJob()

Gets the name of the previous job in this unit of work. Returns the fully-qualified controller class name, or an absolute URL.

public getPreviousJob() : string|null
Tags
since
1.0
Return values
string|null

getRecordCount()

Get the pagination record count

public getRecordCount() : int
Tags
since
3.0
Return values
int

getRequest()

Get the request this controller is processing (if any).

public getRequest() : Request
Tags
since
2.0
Return values
Request

getStart()

Get the pagination start point

public getStart() : int
Tags
since
3.0
Return values
int

getStatusMessage()

Gets the current status message for this controller. Note that by getting the current status message, you clear out the value stored in the session so this method can only be used to get the status message once for display purposes.

public getStatusMessage() : string|null
Tags
since
1.0
Return values
string|null

getTitle()

Getter for the page title.

public getTitle() : string
Tags
since
1.0
Return values
string

getUnitDuration()

Calculates and returns the unit of work current duration in seconds.

public getUnitDuration() : int
Tags
since
1.0
Return values
int

getVisibility()

Get the name of the rights group that has access to this controller.

public getVisibility() : string
Tags
since
1.0
Return values
string

loadControllerDef()

Loads the definition for the controller classname provided.

public static loadControllerDef(string $controllerName) : void
Parameters
$controllerName : string
Tags
throws
IllegalArguementException
since
1.0

markDirty()

Adds the supplied business object to the dirtyObjects array in the session.

public markDirty(ActiveRecord $object) : void
Parameters
$object : ActiveRecord
Tags
since
1.0

markNew()

Adds a newly created business object to the newObjects array in the session.

public markNew(ActiveRecord $object) : void
Parameters
$object : ActiveRecord
Tags
since
1.0

process()

Maps the supplied request with the appropiate method to run on this controller, for example GET to doGET(), POST to doPOST() etc. Returns the response generated by the method called.

public process(Request $request) : Response
Parameters
$request : Request
Tags
since
2.0
Return values
Response

setDescription()

Setter for the page description.

public setDescription(string $description) : void
Parameters
$description : string
Tags
since
1.0

setKeywords()

Setter for the page keywords, should pass a comma-seperated list as a string.

public setKeywords(string $keywords) : void
Parameters
$keywords : string
Tags
since
1.0

setName()

Setter for the unit of work job name.

public setName(string $name) : void
Parameters
$name : string

The fully-qualified controller class name, or an absolute URL.

Tags
since
1.0

setRequest()

Set the request this controller is processing.

public setRequest(Request $request) : void
Parameters
$request : Request
Tags
since
2.0

setStatusMessage()

Set the status message in the session to the value provided.

public setStatusMessage(string $message) : void
Parameters
$message : string
Tags
since
1.0

setTitle()

Setter for the page title.

public setTitle(string $title) : void
Parameters
$title : string
Tags
since
1.0

setUnitEndTime()

Setter for the unit end time (value will be stored in the session as key unitEndTime).

public setUnitEndTime(int $year, int $month, int $day, int $hour, int $minute, int $second) : void
Parameters
$year : int
$month : int
$day : int
$hour : int
$minute : int
$second : int
Tags
since
1.0

setUnitOfWork()

Sets the name of the controller job sequence to the values in the supplied array (and stores the array in the session).

public setUnitOfWork(array<string|int, mixed> $jobs) : void
Parameters
$jobs : array<string|int, mixed>

The names of the controllers in this unit of work sequence. Will accept fully-qualified controller class name, or an absolute URL.

Tags
throws
IllegalArguementException
since
1.0

setUnitStartTime()

Setter for the unit start time (value will be stored in the session as key unitStartTime).

public setUnitStartTime(int $year, int $month, int $day, int $hour, int $minute, int $second) : void
Parameters
$year : int
$month : int
$day : int
$hour : int
$minute : int
$second : int
Tags
since
1.0

setVisibility()

Setter for the name of the rights group that has access to this controller.

public setVisibility(string $visibility) : void
Parameters
$visibility : string
Tags
since
1.0

createDEnumTables()

Method to create the DEnum tables if they don't exist.

private createDEnumTables() : string
Tags
since
1.0
Return values
string

decryptFieldNames()

Descrypts the HTTP param fieldnames in the array provided and returns the plain version.

private decryptFieldNames( $params) : array<string|int, mixed>
Parameters
$params :

array

Tags
since
1.2.2
Return values
array<string|int, mixed>

renderRecord()

Load the requested record and render the HTML or JSON for it.

private renderRecord(array<string|int, mixed> $params, string|null $accept) : string
Parameters
$params : array<string|int, mixed>

The request params

$accept : string|null

The HTTP accept heard value

Tags
throws
ResourceNotFoundException
throws
IllegalArguementException
since
3.0
Return values
string

renderRecords()

Load all records of the type requested and render the HTML or JSON for them.

private renderRecords(array<string|int, mixed> $params, string|null $accept) : string
Parameters
$params : array<string|int, mixed>

The request params

$accept : string|null

The HTTP accept heard value

Tags
throws
ResourceNotFoundException
throws
IllegalArguementException
since
3.0
Return values
string

        
On this page

Search results