Core Classes {menu:} app {menu:} appController {menu:} view {menu:} controller {menu:}

EXC | DEV | Documentation | Version 1.0

App Controller

The class appController is the orchestrator of your application lifecycle. Every application must a have an instance of an appController. To better understand this section you should read about controllers, if you haven't done so already.

Every interaction or request to your backend is orchestrated by the appController. It is responsible for managing messages and events and sending the response.

For most scenarios in EXC you will make your own appController class to handle your app's logic or you may have EXC create a generic instance for you.

EXC will look for your appController class in a file named controller.app.php. This file may be placed in your src folder or in your application folder.

./
└── myapp/
    └── src/
	    └── controller.app.php

You may also place the class in your startup php file, or specify the path to your src folder in a constant named SRC_PATH. For example in your index.php you can add:

<?php
	define('SRC_PATH', __DIR__ . '/src/');

If EXC does not find an appController class it will create a generic instance of the appController automatically.

Structure of your appController

The class appController extends the built in controller \exc\controller\appController which does the heavy lifting.

In your appController we basically handle events and messages, and configure and control certain options.

A basic appController looks like this:

<?php
class appController extends \exc\controller\appController {
	public function config(){
		//config our app...
	}
	public function initialize(){
		error_log("--- @appController->initialize() ---");
	}
	public function unhandled($msg){
		//called when a message is not implemented
		error_log("@appController->unhandled ---- $msg");
	}
	public function willDispatchAction($actionName){
		//about to execute an action
		//we can change the action by returning a different action name here
	}
}
?>

In the config() message we setup different options. These options are explained here.

The functions initialize() and unhandled() are handlers for messages. To learn more check the controller documentation.

Since your appController is valid controller you may add message handlers to implement your app logic here. In many cases is best to segregate your app logic in separate controller classes.

Getting the appController instance

There are various ways to get a reference of the appController.

<?php
$app = \exc\app::controller();

<?php
$app = \exc\controller\appController::instance();

If you have a class that inherits from viewController or processController you can use:

<?php
$app = $myObject->appController();

or inside a viewController or processController as:

<?php
$app = $this->appController();

Using the appController

The appController is used to publish events related to the execution of your app. In general we add event handlers to the appController.

The appController may have delegate controllers, which actually implement the behavior or execute your applications logic, these are called application controllers.

The application controllers are instances of viewController or processController that you create. See Adding your own controllers in this document for more information.

When your controller is added as an application controller EXC will automatically register event handlers for events published by the appController.

You can manually register for an appController event by using it's on() function.

<?php
$app = \exc\controller\appController::instance(); //get an instance of the app controller

$app->on( 'appStart', $callback ); //register for the event appStart

Class appController

Inherits from the class \exc\core\controller and \exc\core\base.

Instance Methods	Description
`setOption(string $key, mixed $value)`	Sets an application option.
`getDefaultView()`	Returns the view instance designated as default view. Returns null if the default view is not set.
`setDefaultView(mixed $view)`	Sets the default view. Parameters: `$view` A string with the name of the view or an instance of a `view`.
`client()`	Returns the `\exc\client` instance.
`header(string $name, string $value)`	Sets an HTTP header.
`end()`	Terminates the application execution.
`abort()`	Aborts the application execution.
`sendJSON(mixed $data)`	Sends a JSON payload to the front-end. The parameter `$data` may be a hash of key-value pairs or a json encoded string.
`sendJS(string $code)`	Sends valid a string with javascript code to the front-end.
`sendView(object $aView)`	Sends the contents of a `view` to the front-end.
`write(string $data)`	Appends the contents of `$data` to the output buffer.
`commit(string $payload)`	Sends a payload to the front-end.
`sendDownloadWithData(string $mime, string $data, string $filename=null)`	Sends `$data` as a file attachment.
`willDispatchAction(string $actionName)`	Message EXC will dispatch a controller action. You may change the action to execute by returning a string with a different action name.
`canBecomeFirstResponder(string $controllerClassName, object $controllerInstance)`	Message EXC will delegate the role of first responder to a given controller. Return false to deny the switch.

Class Methods	Description
`instance()`	returns the global instance of the `appController`.