Documentation

WelcomeController extends Controller
in package

Application

Forms used for setting up SproutCMS for the first time

Constants

ALLOW_PRODUCTION : mixed = TRUE

Properties

$action_log : mixed: Should this controller log add/edit/delete actions?

Methods

__call() : void: Handles methods that do not exist.
__construct() : void
_run() : mixed: The router/kohana will invoke this method to invoke an action.
addSampleAction() : mixed: Add sample content
checklist() : mixed: Display the welcome checklist
dbConfForm() : mixed: Show a UI for generating a database config
dbConfResult() : mixed: Display the generated database config
dbConfTest() : mixed: Ajax method to test the db connection for a given set of params
getAbsModulePath() : string: Get the absolute path of the current module for this controller.
getCssClassName() : string: Return the class name for this controller, expressed in CSS style, i.e. with dashes
getModule() : ModuleInterface|null: Get the module that this controller belongs to.
getModulePath() : string: Get the a prefix suitable for finding views for this controller.
phpInfo() : mixed: Show a phpinfo() view along with some extra information
redirect() : mixed: Redirect home page traffic to the welcome checklist
superOperatorAction() : void: Create a super operator
superOperatorForm() : mixed: Show a UI to create a super-operator
superOperatorResult() : mixed: Show the generated super operator details
sync() : mixed: Run a database sync
addSampleFiles() : mixed: Add sample files from sample_content/files.xml
addSampleHomePage() : mixed: Updates to home page - hardcoded rather than an xml file
addSamplePages() : mixed: Add sample files from sample_content/pages.xml
autoSetEmptyParam() : void: Auto-set the "empty" param for fields with foreign keys to be NULL
deleteRecord() : int: Deletes a record, and logs the deletion This should be used by all _deleteSave methods Starts a transaction and commits it if not already in a transaction when called
generateFormView() : PhpView: Generates a form view from a JSON config file
jsonExtraValidate() : void: Do any additional validation prior to saving the record
loadEditJson() : array<string, array<string|int, array<string, mixed>>>: Loads a JSON config file for an automated edit-type form for this controller
loadFormJson() : array<string|int, mixed>: Loads a config file for a JsonForm associated with this controller
loadRecord() : array<string|int, mixed>|bool: Fetches the pre-update record from the database.
logAction() : int: Stores a history item in the database, recording an add (i.e. insert), edit, or delete.
logAdd() : int: Logs an add action. This is a wrapper for {@see Controller::logAction}
logAddCategory() : int: Logs the adding of a record to a category. This is a wrapper for {@see Controller::logAction}
logDelete() : int: Logs a delete action. This is a wrapper for {@see Controller::logAction}
logDeleteCategory() : int: Logs the removal of a record from a category. This is a wrapper for {@see Controller::logAction}
logEdit() : int: Logs an edit action. This is a wrapper for {@see Controller::logAction}
replaceSet() : void: Inserts records which are in $new_records, but are not in the specified table Deletes records which are in the specified table, but not in $new_records Updates records which are in both
saveJsonData() : bool: Automatically saves the data associated with a submission on a JSON-generated form
wipeTables() : mixed: Wipe the tables used by the sample code system (dev only code)
genEnvFile() : string: Generate a database config from given parameters
passwordComplexity() : mixed: Ensure password has enough complexity
superOperatorConf() : string: Generate and download super operator config file
testDbconf() : array<string|int, mixed>: Test the database config is correct
testDbsync() : array<string|int, mixed>: Test that tables are available
testSampleContent() : array<string|int, mixed>: Test that sample content has been added
testSuperOp() : array<string|int, mixed>: Test whether one or more super operators have been created
testWelcome() : array<string|int, mixed>: Test that the welcome module isn't installed

ALLOW_PRODUCTION


    public
        mixed
    ALLOW_PRODUCTION
    = TRUE

$action_log

Should this controller log add/edit/delete actions?


        protected
            mixed
    $action_log
     = false

__call()

Handles methods that do not exist.


    public
                    __call(string $method, array<string|int, mixed> $args) : void

Parameters

$method : string: Method name
$args : array<string|int, mixed>: Arguments

__construct()


    public
                    __construct() : void

_run()

The router/kohana will invoke this method to invoke an action.


    public
                    _run(mixed $method, mixed $args) : mixed

Parameters

$method : mixed
$args : mixed

addSampleAction()

Add sample content


    public
                    addSampleAction() : mixed

checklist()

Display the welcome checklist


    public
                    checklist() : mixed

dbConfForm()

Show a UI for generating a database config


    public
                    dbConfForm() : mixed

dbConfResult()

Display the generated database config


    public
                    dbConfResult() : mixed

dbConfTest()

Ajax method to test the db connection for a given set of params


    public
                    dbConfTest() : mixed

getAbsModulePath()

Get the absolute path of the current module for this controller.


    public
                    getAbsModulePath() : string

TODO this might be too broad. It's only used for loading JSON forms and perhaps encourages bad behaviour. Such as assuming common path structures for all modules, where instead this should be written into the module class.

Return values

string

getCssClassName()

Return the class name for this controller, expressed in CSS style, i.e. with dashes


    public
                    getCssClassName() : string

Example: When called from BlogPostController --> 'blog-post-controller'

Return values

string —

Name of this PHP class, in a format suitable for use in CSS

getModule()

Get the module that this controller belongs to.


    public
                    getModule() : ModuleInterface|null

If the controllers belongs to Sprout itself, this returns null.

Return values

ModuleInterface|null

getModulePath()

Get the a prefix suitable for finding views for this controller.


    public
                    getModulePath() : string

Do not assume that all modules, or even core sprout live relative to each other or the DOCROOT (as they previously did).

TODO rename this - like getViewPrefix()

Return values

string —

'sprout' or 'modules/AwesomeModule'

phpInfo()

Show a phpinfo() view along with some extra information


    public
                    phpInfo() : mixed

redirect()

Redirect home page traffic to the welcome checklist


    public
                    redirect() : mixed

superOperatorAction()

Create a super operator


    public
                    superOperatorAction() : void

Return values

void —

Redirects

superOperatorForm()

Show a UI to create a super-operator


    public
                    superOperatorForm() : mixed

superOperatorResult()

Show the generated super operator details


    public
                    superOperatorResult() : mixed

sync()

Run a database sync


    public
                    sync() : mixed

addSampleFiles()

Add sample files from sample_content/files.xml


    protected
                    addSampleFiles() : mixed

addSampleHomePage()

Updates to home page - hardcoded rather than an xml file


    protected
                    addSampleHomePage() : mixed

addSamplePages()

Add sample files from sample_content/pages.xml


    protected
                    addSamplePages() : mixed

autoSetEmptyParam()

Auto-set the "empty" param for fields with foreign keys to be NULL


    protected
                    autoSetEmptyParam(array<string, array<string|int, array<string, mixed>>> &$conf) : void

This greatly reduces the number of foreign-key constraints hit in day-to-day use, especially with file fields.

Parameters

$conf : array<string, array<string|int, array<string, mixed>>>: Json form configuration

Return values

void —

Array $conf is altered in-place

deleteRecord()

Deletes a record, and logs the deletion This should be used by all _deleteSave methods Starts a transaction and commits it if not already in a transaction when called


    protected
                    deleteRecord(string $table, int $record_id[, int $parent_log_id = 0 ]) : int

Parameters

$table : string: Table name
$record_id : int
$parent_log_id : int = 0: ID of a parent entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data.

Return values

int —

ID of the record inserted into the history_items table (0 if no logging)

generateFormView()

Generates a form view from a JSON config file


    protected
                    generateFormView(mixed $file_name) : PhpView

Parameters

$file_name : mixed

Return values

PhpView

jsonExtraValidate()

Do any additional validation prior to saving the record


    protected
                    jsonExtraValidate(int $id, Validator $validator) : void

Parameters

$id : int: Record ID or 0 for adds
$validator : Validator: Validator instance to attach your errors to

loadEditJson()

Loads a JSON config file for an automated edit-type form for this controller


    protected
                    loadEditJson() : array<string, array<string|int, array<string, mixed>>>

Return values

array<string, array<string|int, array<string, mixed>>>

loadFormJson()

Loads a config file for a JsonForm associated with this controller


    protected
                    loadFormJson(string $file_name) : array<string|int, mixed>

Parameters

$file_name : string: The config file name, e.g. 'register.json'

Return values

array<string|int, mixed>

loadRecord()

Fetches the pre-update record from the database.


    protected
                    loadRecord(string $table, int $record_id) : array<string|int, mixed>|bool

Used by the action log system, and disabled if the action log system has been turned off

Parameters

$table : string: Name of table to load record from
$record_id : int: ID of record to load

Return values

array<string|int, mixed>|bool —

False if not using logging for this controller, else the record row

logAction()

Stores a history item in the database, recording an add (i.e. insert), edit, or delete.


    protected
                    logAction(string $table, int $record_id, string $type[, array<string|int, mixed> $data = [] ][, int $parent_log_id = 0 ]) : int

Should be called AFTER the action has been made. N.B. This is a low-level method; the friendlier wrapper methods are preferred; e.g. Controller::logAdd, Controller::logEdit

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the added/edited/deleted record
$type : string: ENUM value from history_items.type
$data : array<string|int, mixed> = []: Data associated with an add/edit. The handling differs based on the $type parameter: 'Add' ignored 'Edit' should be an array of the pre-update data, used to build a diff 'Delete' should contain the complete data of the deleted record 'Add category' should contain ['cat_id' => value] 'Delete category' should contain ['cat_id' => value] 'Change password' should be an empty array
$parent_log_id : int = 0: ID of a parent log entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data. N.B. This is only relevant for deletes

Return values

int —

ID of the record inserted into the history_items table; 0 if no insert was done; -1 if it failed

logAdd()

Logs an add action. This is a wrapper for {@see Controller::logAction}


    protected
                    logAdd(string $table, int $record_id) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the added record

Return values

int —

ID of the record inserted into the history_items table

logAddCategory()

Logs the adding of a record to a category. This is a wrapper for {@see Controller::logAction}


    protected
                    logAddCategory(string $table, int $record_id, int $cat_id) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The ID of the record which was added to the category
$cat_id : int: The ID of the category which the record was added to

Return values

int —

ID of the record inserted into the history_items table

logDelete()

Logs a delete action. This is a wrapper for {@see Controller::logAction}


    protected
                    logDelete(string $table, int $record_id, array<string|int, mixed> $data[, int $parent_log_id = 0 ]) : int

Parameters

$table : string: The table which contained the deleted record
$record_id : int: The id of the deleted record
$data : array<string|int, mixed>: The complete contents of the record which was deleted, i.e. [field => value], so it can be restored if necessary
$parent_log_id : int = 0: ID of a parent log entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data.

Return values

int —

ID of the record inserted into the history_items table

logDeleteCategory()

Logs the removal of a record from a category. This is a wrapper for {@see Controller::logAction}


    protected
                    logDeleteCategory(string $table, int $record_id, int $cat_id) : int

Parameters

$table : string: The table which contains the record which was removed from the category
$record_id : int: The ID of the record which was removed from the category
$cat_id : int: The ID of the category which the record was removed from

Return values

int —

ID of the record inserted into the history_items table

logEdit()

Logs an edit action. This is a wrapper for {@see Controller::logAction}


    protected
                    logEdit(string $table, int $record_id, array<string|int, mixed> $data) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the edited record
$data : array<string|int, mixed>: Pre-update data, used to build a diff

Return values

int —

ID of the record inserted into the history_items table

replaceSet()

Inserts records which are in $new_records, but are not in the specified table Deletes records which are in the specified table, but not in $new_records Updates records which are in both


    protected
                    replaceSet(string $table, array<string|int, mixed> $new_records, array<string|int, mixed> $conditions) : void

Matching is done on the 'id' field, as a result the $new_records arrays MUST contain an id field.

Parameters

$table : string: The table name. Do not include prefix.
$new_records : array<string|int, mixed>: The new records for the table. Should be an array of arrays, With each sub-array being the arguments which would normally be passed to Pdb::insert or Pdb::update
$conditions : array<string|int, mixed>: A where clause to use when looking to see what records already exist. Pdb::buildClause

saveJsonData()

Automatically saves the data associated with a submission on a JSON-generated form


    protected
                    saveJsonData(array<string, array<string|int, array<string, mixed>>> $conf, int &$item_id[, string $mode = '' ]) : bool

Parameters

$conf : array<string, array<string|int, array<string, mixed>>>: Config loaded from a JSON file
$item_id : int: Database ID of record to store data in. If zero, a new record will be inserted, and as this argument is a reference, it will be updated with the auto-increment ID generated by the insert.
$mode : string = '': Mode: 'add', 'edit', or something custom (e.g. 'duplicate', 'verify'). If blank, 'add' or 'edit' will be automatically determined, based on $item_id

Return values

bool —

True if the save succeeded. If false is returned, errors will be saved in $_SESSION

wipeTables()

Wipe the tables used by the sample code system (dev only code)


    protected
                    wipeTables() : mixed

genEnvFile()

Generate a database config from given parameters


    private
            static        genEnvFile(array<string|int, mixed> $data) : string

Parameters

$data : array<string|int, mixed>: Config params; 'env', 'type', 'host', 'user', 'pass', 'database'

Return values

string

passwordComplexity()

Ensure password has enough complexity


    private
            static        passwordComplexity(mixed $str) : mixed

Parameters

$str : mixed

superOperatorConf()

Generate and download super operator config file


    private
            static        superOperatorConf(array<string|int, mixed> $params) : string

Parameters

$params : array<string|int, mixed>: [ user, hash, salt ]

Return values

string

testDbconf()

Test the database config is correct


    private
                    testDbconf() : array<string|int, mixed>