Documentation

RestController extends ControllerBehavior
in package
Uses FormModelSaver

Rest Controller Behavior

Adds REST features for working with backend models.

Usage:

In the model class definition:

public $implement = ['Mohsin.Rest.Behaviors.RestController'];

Tags
author

Saifur Rahman Mohsin

Table of Contents

$assetPath  : string
$extendableStaticCalledClass  : string
$layout  : string
$suppressLayout  : bool
$vars  : array<string|int, mixed>
$actions  : array<string|int, mixed>
$assets  : array<string|int, mixed>
$config  : array<string|int, mixed>
$configPath  : string
$controller  : Model
$extensionCallbacks  : array<string|int, mixed>
$extensionHidden  : mixed
$layoutPath  : string
$model  : Model
$modelsToSave  : array<string|int, mixed>
$prefix  : string
$requiredConfig  : array<string|int, mixed>
$requiredProperties  : array<string|int, mixed>
$viewPath  : string|array<string|int, mixed>
__construct()  : mixed
Behavior constructor
addCss()  : void
Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
addJs()  : void
Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
addRss()  : void
Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.
addViewPath()  : void
Prepends a path on the available view path locations.
combineAssets()  : string
Run the provided assets through the Asset Combiner
createModelObject()  : Model
Creates a new instance of the model. This logic can be changed by overriding it in the rest controller.
destroy()  : Response
Remove the specified record.
extend()  : mixed
extendModel()  : Model
Extend supplied model, the model can be altered by overriding it in the controller.
extensionApplyInitCallbacks()  : mixed
extensionExtendCallback()  : void
Helper method for `::extend()` static method
extensionIsHiddenField()  : mixed
extensionIsHiddenMethod()  : mixed
findModelObject()  : Model
Finds a Model record by its primary identifier, used by show, update actions.
flushAssets()  : void
Disables the use, and subequent broadcast, of assets. This is useful to call during an AJAX request to speed things up. This method works by specifically targeting the hasAssetsDefined method.
getAssetPath()  : string
Locates a file based on it's definition. If the file starts with a forward slash, it will be returned in context of the application public path, otherwise it will be returned in context of the asset path.
getAssetPaths()  : array<string|int, mixed>
Returns an array of all registered asset paths.
getCalledExtensionClass()  : mixed
getConfig()  : string
Safe accessor for configuration values.
getConfigPath()  : string
Locates a file based on it's definition. If the file starts with the ~ symbol it will be returned in context of the application base path, otherwise it will be returned in context of the config path.
getPaginator()  : mixed
getViewPath()  : string
Locates a file based on its definition. The file name can be prefixed with a symbol (~|$) to return in context of the application or plugin base path, otherwise it will be returned in context of this object view path.
getViewPaths()  : array<string|int, mixed>
Returns the active view path locations.
guessConfigPath()  : string
Guess the package path for the called class.
guessConfigPathFrom()  : string
Guess the package path from a specified class.
guessViewPath()  : string
Guess the package path for the called class.
guessViewPathFrom()  : string
Guess the package path from a specified class.
hasAssetsDefined()  : bool
Returns true if assets any have been added.
index()  : Response
Display the records.
makeAssets()  : string
Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls
makeConfig()  : array<string|int, mixed>|stdClass
Reads the contents of the supplied file and applies it to this object.
makeConfigFromArray()  : stdClass
Makes a config object from an array, making the first level keys properties of a new object.
makeFileContents()  : string
Includes a file path using output buffering.
makeFormWidget()  : FormWidgetBase
Makes a form widget object with the supplied form field and widget configuration.
makeLayout()  : mixed
Render a layout.
makeLayoutPartial()  : string
Renders a layout partial
makePartial()  : mixed
Render a partial file contents located in the views folder.
makeView()  : string
Loads a view with the name specified. Applies layout if its name is provided by the parent object.
makeViewContent()  : string
Renders supplied contents inside a layout.
makeWidget()  : mixed|WidgetBase
Makes a widget object with the supplied configuration file.
mergeConfig()  : stdClass
Merges two configuration sources, either prepared or not, and returns them as a single configuration object.
resetSession()  : void
Resets all session data related to this widget.
setConfig()  : mixed
Sets the configuration values
show()  : Response
Display the specified record.
store()  : Response
Store a newly created record using post data.
update()  : Response
Update the specified record in using post data.
addAsset()  : mixed
Adds the provided asset to the internal asset collections
controllerMethodExists()  : bool
Returns true in case if a specified method exists in the extended controller.
createModel()  : Model
Internal method, prepare the model object
deferPurgedSaveAttributes()  : void
Removes an array of attributes from the model. If the model implements the Purgeable trait, this is preferred over the internal logic.
extensionHideField()  : mixed
extensionHideMethod()  : mixed
getAssetEntryBuildPath()  : string
Internal helper, attaches a build code to an asset path
getAssetScheme()  : string
Internal helper, get asset scheme
getLocalPath()  : mixed
getSession()  : string
Retrieves a widget related key/value pair from session data.
handleViewException()  : void
Handle a view exception.
hideAction()  : mixed
Protects a public method from being available as an controller action.
makeSessionId()  : string
Returns a unique session identifier for this widget and controller action.
prepareModelsToSave()  : array<string|int, mixed>
Takes a model and fills it with data from a multidimensional array.
putSession()  : void
Saves a widget related key/value pair in to session data.
removeDuplicates()  : void
Removes duplicate assets from the entire collection.
setModelAttributes()  : void
Sets a data collection to a model attributes, relations are also set.

Properties

$assetPath

public string $assetPath

Specifies a path to the asset directory.

$extendableStaticCalledClass

public static string $extendableStaticCalledClass = null

The calling class when using a static method.

$layout

public string $layout

Layout to use for the view.

$suppressLayout

public bool $suppressLayout = false

Prevents the use of a layout.

$vars

public array<string|int, mixed> $vars = []

A list of variables to pass to the page.

$actions

protected array<string|int, mixed> $actions

Visible actions in context of the controller. Only takes effect if it is an array

$assets

protected array<string|int, mixed> $assets = ['js' => [], 'css' => [], 'rss' => []]

Collection of assets to display in the layout.

$configPath

protected string $configPath

Specifies a path to the config directory.

$controller

protected Model $controller

The child controller that implements the behavior.

$extensionCallbacks

protected static array<string|int, mixed> $extensionCallbacks = []

Used to extend the constructor of an extension class. Eg:

BehaviorClass::extend(function($obj) { })

$extensionHidden

protected mixed $extensionHidden = ['fields' => [], 'methods' => ['extensionIsHiddenField', 'extensionIsHiddenMethod']]

$layoutPath

protected string $layoutPath

Specifies a path to the layout directory.

$model

protected Model $model

The initialized model used by the rest controller.

$modelsToSave

protected array<string|int, mixed> $modelsToSave = []

List of prepared models that require saving.

$prefix

protected string $prefix = ''

The prefix for verb methods.

$requiredConfig

protected array<string|int, mixed> $requiredConfig = ['modelClass', 'allowedActions']

Configuration values that must exist when applying the primary config file.

  • modelClass: Class name for the model
  • list: List column definitions

$requiredProperties

protected array<string|int, mixed> $requiredProperties = ['restConfig']

Properties that must exist in the controller using this behavior.

$viewPath

protected string|array<string|int, mixed> $viewPath

Specifies a path to the views directory.

Methods

__construct()

Behavior constructor

public __construct(Controller $controller) : mixed
Parameters
$controller : Controller
Return values
mixed —

addCss()

Adds StyleSheet asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

public addCss(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
$name : string

Specifies a path (URL) to the script.

$attributes : array<string|int, mixed> = []

Adds extra HTML attributes to the asset link.

Return values
void —

addJs()

Adds JavaScript asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

public addJs(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
$name : string

Specifies a path (URL) to the script.

$attributes : array<string|int, mixed> = []

Adds extra HTML attributes to the asset link.

Return values
void —

addRss()

Adds an RSS link asset to the asset list. Call $this->makeAssets() in a view to output corresponding markup.

public addRss(string $name[, array<string|int, mixed> $attributes = [] ]) : void
Parameters
$name : string

Specifies a path (URL) to the RSS channel

$attributes : array<string|int, mixed> = []

Adds extra HTML attributes to the asset link.

Return values
void —

addViewPath()

Prepends a path on the available view path locations.

public addViewPath(string|array<string|int, mixed> $path) : void
Parameters
$path : string|array<string|int, mixed>
Return values
void —

combineAssets()

Run the provided assets through the Asset Combiner

public combineAssets(array<string|int, mixed> $assets[, string $localPath = '' ]) : string
Parameters
$assets : array<string|int, mixed>

Collection of assets

$localPath : string = ''

Prefix all assets with this path (optional)

Return values
string —

createModelObject()

Creates a new instance of the model. This logic can be changed by overriding it in the rest controller.

public createModelObject() : Model
Return values
Model —

destroy()

Remove the specified record.

public destroy(mixed $recordId) : Response
Parameters
$recordId : mixed
Return values
Response —

extend()

public static extend(callable $callback) : mixed
Parameters
$callback : callable
Return values
mixed —

extendModel()

Extend supplied model, the model can be altered by overriding it in the controller.

public extendModel(Model $model) : Model
Parameters
$model : Model
Return values
Model —

extensionApplyInitCallbacks()

public extensionApplyInitCallbacks() : mixed
Return values
mixed —

extensionExtendCallback()

Helper method for `::extend()` static method

public static extensionExtendCallback(callable $callback) : void
Parameters
$callback : callable
Return values
void —

extensionIsHiddenField()

public extensionIsHiddenField(mixed $name) : mixed
Parameters
$name : mixed
Return values
mixed —

extensionIsHiddenMethod()

public extensionIsHiddenMethod(mixed $name) : mixed
Parameters
$name : mixed
Return values
mixed —

findModelObject()

Finds a Model record by its primary identifier, used by show, update actions.

public findModelObject(string $recordId) : Model

This logic can be changed by overriding it in the rest controller.

Parameters
$recordId : string
Return values
Model —

flushAssets()

Disables the use, and subequent broadcast, of assets. This is useful to call during an AJAX request to speed things up. This method works by specifically targeting the hasAssetsDefined method.

public flushAssets() : void
Return values
void —

getAssetPath()

Locates a file based on it's definition. If the file starts with a forward slash, it will be returned in context of the application public path, otherwise it will be returned in context of the asset path.

public getAssetPath(string $fileName[, string $assetPath = null ]) : string
Parameters
$fileName : string

File to load.

$assetPath : string = null

Explicitly define an asset path.

Return values
string —

Relative path to the asset file.

getAssetPaths()

Returns an array of all registered asset paths.

public getAssetPaths() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getCalledExtensionClass()

public static getCalledExtensionClass() : mixed
Return values
mixed —

getConfig()

Safe accessor for configuration values.

public getConfig([string $name = null ][, mixed $default = null ]) : string
Parameters
$name : string = null

Config name, supports array names like "field[key]"

$default : mixed = null

Default value if nothing is found

Return values
string —

getConfigPath()

Locates a file based on it's definition. If the file starts with the ~ symbol it will be returned in context of the application base path, otherwise it will be returned in context of the config path.

public getConfigPath(string $fileName[, mixed $configPath = null ]) : string
Parameters
$fileName : string

File to load.

$configPath : mixed = null

Explicitly define a config path.

Return values
string —

Full path to the config file.

getPaginator()

public getPaginator(mixed $model, mixed $pageSize, mixed $page) : mixed
Parameters
$model : mixed
$pageSize : mixed
$page : mixed
Return values
mixed —

getViewPath()

Locates a file based on its definition. The file name can be prefixed with a symbol (~|$) to return in context of the application or plugin base path, otherwise it will be returned in context of this object view path.

public getViewPath(string $fileName[, mixed $viewPath = null ]) : string
Parameters
$fileName : string

File to load.

$viewPath : mixed = null

Explicitly define a view path.

Return values
string —

Full path to the view file.

getViewPaths()

Returns the active view path locations.

public getViewPaths() : array<string|int, mixed>
Return values
array<string|int, mixed> —

guessConfigPath()

Guess the package path for the called class.

public guessConfigPath([string $suffix = '' ]) : string
Parameters
$suffix : string = ''

An extra path to attach to the end

Return values
string —

guessConfigPathFrom()

Guess the package path from a specified class.

public guessConfigPathFrom(string $class[, string $suffix = '' ]) : string
Parameters
$class : string

Class to guess path from.

$suffix : string = ''

An extra path to attach to the end

Return values
string —

guessViewPath()

Guess the package path for the called class.

public guessViewPath([string $suffix = '' ][, bool $isPublic = false ]) : string
Parameters
$suffix : string = ''

An extra path to attach to the end

$isPublic : bool = false

Returns public path instead of an absolute one

Return values
string —

guessViewPathFrom()

Guess the package path from a specified class.

public guessViewPathFrom(string $class[, string $suffix = '' ][, bool $isPublic = false ]) : string
Parameters
$class : string

Class to guess path from.

$suffix : string = ''

An extra path to attach to the end

$isPublic : bool = false

Returns public path instead of an absolute one

Return values
string —

hasAssetsDefined()

Returns true if assets any have been added.

public hasAssetsDefined() : bool
Return values
bool —

index()

Display the records.

public index() : Response
Return values
Response —

makeAssets()

Outputs `<link>` and `<script>` tags to load assets previously added with addJs and addCss method calls

public makeAssets([string $type = null ]) : string
Parameters
$type : string = null

Return an asset collection of a given type (css, rss, js) or null for all.

Return values
string —

makeConfig()

Reads the contents of the supplied file and applies it to this object.

public makeConfig([array<string|int, mixed> $configFile = [] ][, array<string|int, mixed> $requiredConfig = [] ]) : array<string|int, mixed>|stdClass
Parameters
$configFile : array<string|int, mixed> = []
$requiredConfig : array<string|int, mixed> = []
Return values
array<string|int, mixed>|stdClass —

makeConfigFromArray()

Makes a config object from an array, making the first level keys properties of a new object.

public makeConfigFromArray([array<string|int, mixed> $configArray = [] ]) : stdClass
Parameters
$configArray : array<string|int, mixed> = []

Config array.

Return values
stdClass —

The config object

makeFileContents()

Includes a file path using output buffering.

public makeFileContents(string $filePath[, array<string|int, mixed> $extraParams = [] ]) : string

Ensures that vars are available.

Parameters
$filePath : string

Absolute path to the view file.

$extraParams : array<string|int, mixed> = []

Parameters that should be available to the view.

Return values
string —

makeFormWidget()

Makes a form widget object with the supplied form field and widget configuration.

public makeFormWidget(string $class[, mixed $fieldConfig = [] ][, array<string|int, mixed> $widgetConfig = [] ]) : FormWidgetBase
Parameters
$class : string

Widget class name

$fieldConfig : mixed = []

A field name, an array of config or a FormField object.

$widgetConfig : array<string|int, mixed> = []

An array of config.

Return values
FormWidgetBase —

The widget object

makeLayout()

Render a layout.

public makeLayout([string $name = null ][, array<string|int, mixed> $params = [] ][, bool $throwException = true ]) : mixed
Parameters
$name : string = null

Specifies the layout name. If this parameter is omitted, the $layout property will be used.

$params : array<string|int, mixed> = []

Parameter variables to pass to the view.

$throwException : bool = true

Throw an exception if the layout is not found

Return values
mixed —

The layout contents, or false.

makeLayoutPartial()

Renders a layout partial

public makeLayoutPartial(string $partial[, array<string|int, mixed> $params = [] ]) : string
Parameters
$partial : string

The view to load.

$params : array<string|int, mixed> = []

Parameter variables to pass to the view.

Return values
string —

The layout partial contents

makePartial()

Render a partial file contents located in the views folder.

public makePartial(string $partial[, array<string|int, mixed> $params = [] ][, bool $throwException = true ]) : mixed
Parameters
$partial : string

The view to load.

$params : array<string|int, mixed> = []

Parameter variables to pass to the view.

$throwException : bool = true

Throw an exception if the partial is not found.

Return values
mixed —

Partial contents or false if not throwing an exception.

makeView()

Loads a view with the name specified. Applies layout if its name is provided by the parent object.

public makeView(string $view) : string

The view file must be situated in the views directory, and has the extension "htm".

Parameters
$view : string

Specifies the view name, without extension. Eg: "index".

Return values
string —

makeViewContent()

Renders supplied contents inside a layout.

public makeViewContent(string $contents[, string $layout = null ]) : string
Parameters
$contents : string

The inner contents as a string.

$layout : string = null

Specifies the layout name.

Return values
string —

makeWidget()

Makes a widget object with the supplied configuration file.

public makeWidget(string $class[, array<string|int, mixed> $widgetConfig = [] ]) : mixed|WidgetBase
Parameters
$class : string

Widget class name

$widgetConfig : array<string|int, mixed> = []

An array of config.

Return values
mixed|WidgetBase —

The widget object

mergeConfig()

Merges two configuration sources, either prepared or not, and returns them as a single configuration object.

public mergeConfig(mixed $configA, mixed $configB) : stdClass
Parameters
$configA : mixed
$configB : mixed
Return values
stdClass —

The config object

resetSession()

Resets all session data related to this widget.

public resetSession() : void
Return values
void —

setConfig()

Sets the configuration values

public setConfig(mixed $config[, array<string|int, mixed> $required = [] ]) : mixed
Parameters
$config : mixed

Config object or array

$required : array<string|int, mixed> = []

Required config items

Return values
mixed —

show()

Display the specified record.

public show(int $recordId) : Response
Parameters
$recordId : int
Return values
Response —

store()

Store a newly created record using post data.

public store() : Response
Return values
Response —

update()

Update the specified record in using post data.

public update(int $recordId) : Response
Parameters
$recordId : int
Return values
Response —

addAsset()

Adds the provided asset to the internal asset collections

protected addAsset(string $type, string $path, array<string|int, mixed> $attributes) : mixed
Parameters
$type : string

The type of the asset: 'js' || 'css' || 'rss'

$path : string

The path to the asset

$attributes : array<string|int, mixed>

The attributes for the asset

Return values
mixed —

controllerMethodExists()

Returns true in case if a specified method exists in the extended controller.

protected controllerMethodExists(string $methodName) : bool
Parameters
$methodName : string

Specifies the method name

Return values
bool —

createModel()

Internal method, prepare the model object

protected createModel() : Model
Return values
Model —

deferPurgedSaveAttributes()

Removes an array of attributes from the model. If the model implements the Purgeable trait, this is preferred over the internal logic.

protected deferPurgedSaveAttributes(Model $model, array<string|int, mixed> $attributesToPurge) : void
Parameters
$model : Model

Model to adjust.

$attributesToPurge : array<string|int, mixed>

Attribute values to remove from the model.

Return values
void —

extensionHideField()

protected extensionHideField(mixed $name) : mixed
Parameters
$name : mixed
Return values
mixed —

extensionHideMethod()

protected extensionHideMethod(mixed $name) : mixed
Parameters
$name : mixed
Return values
mixed —

getAssetEntryBuildPath()

Internal helper, attaches a build code to an asset path

protected getAssetEntryBuildPath(array<string|int, mixed> $asset) : string
Parameters
$asset : array<string|int, mixed>

Stored asset array

Return values
string —

getAssetScheme()

Internal helper, get asset scheme

protected getAssetScheme(string $asset) : string
Parameters
$asset : string

Specifies a path (URL) to the asset.

Return values
string —

getLocalPath()

protected getLocalPath(string $relativePath) : mixed
Parameters
$relativePath : string
Return values
mixed —

getSession()

Retrieves a widget related key/value pair from session data.

protected getSession([string $key = null ][, string $default = null ]) : string
Parameters
$key : string = null

Unique key for the data store.

$default : string = null

A default value to use when value is not found.

Return values
string —

handleViewException()

Handle a view exception.

protected handleViewException(Exception $e, int $obLevel) : void
Parameters
$e : Exception
$obLevel : int
Return values
void —

hideAction()

Protects a public method from being available as an controller action.

protected hideAction(mixed $methodName) : mixed

These methods could be defined in a controller to override a behavior default action. Such methods should be defined as public, to allow the behavior object to access it. By default public methods of a controller are considered as actions. To prevent this occurrence, methods should be hidden by using this method.

Parameters
$methodName : mixed

Specifies a method name.

Return values
mixed —

makeSessionId()

Returns a unique session identifier for this widget and controller action.

protected makeSessionId() : string
Return values
string —

prepareModelsToSave()

Takes a model and fills it with data from a multidimensional array.

protected prepareModelsToSave(Model $model, array<string|int, mixed> $saveData) : array<string|int, mixed>

If an attribute is found to be a relationship, that relationship is also filled.

$modelsToSave = $this->prepareModelsToSave($model, [...]);

foreach ($modelsToSave as $modelToSave) {
    $modelToSave->save();
}
Parameters
$model : Model

Model to fill.

$saveData : array<string|int, mixed>

Attribute values to fill model.

Return values
array<string|int, mixed> —

The collection of models to save.

putSession()

Saves a widget related key/value pair in to session data.

protected putSession(string $key, string $value) : void
Parameters
$key : string

Unique key for the data store.

$value : string

The value to store.

Return values
void —

removeDuplicates()

Removes duplicate assets from the entire collection.

protected removeDuplicates() : void
Return values
void —

setModelAttributes()

Sets a data collection to a model attributes, relations are also set.

protected setModelAttributes(Model $model, array<string|int, mixed> $saveData) : void
Parameters
$model : Model

Model to fill.

$saveData : array<string|int, mixed>

Attribute values to fill model.

Return values
void —

Search results