Application
Bootstrap #
Application
is the main entrant to start KoolReport Dashboard
Bootstrap the application
//index.php
//Load composer autoload will load koolreport/core/autoload.php
require_once "vendor/autoload.php";
require_once "App.php";
App::create()->run();
// App.php
use \koolreport\dashboard\Application;
class App extends Application
{
}
Adding dashboards #
You need to provide list of dashboards to the dashboards()
method like following.
class App extends Application
{
protected function dashboards()
{
return [
"Home"=>HomeBoard::create(),
"Sale"=>SaleBoard::create(),
];
}
}
Above example will produce 2 dashboards Home and Sale appearing on the menu of application. Learn how to create a dashboard.
Grouped dashboards #
use \koolreport\dashboard\menu\Group;
class App extends Application
{
protected function dashboards()
{
return [
"Home"=>HomeBoard::create(),
"Sale Reports"=>Group::create()->icon("fa fa-line-chart")->sub([
"Overview"=>SaleOverviewBoard::create(),
"Main Products"=>MainProductBoard::create(),
]),
"Cost Reports"=>Group::create()->icon("fa fa-pie-chart")->sub([
"Overview Cost"=>CostOverviewBoard::create(),
"BreakDown Cost"=>BreakDownCostBoard::create(),
])
];
}
}
3rd level of menu #
You can add another layers of menu breakdown which called Section
use \koolreport\dashboard\menu\Section;
use \koolreport\dashboard\menu\Group;
class App extends Application
{
protected function dashboards()
{
return [
"Home"=>HomeBoard::create(),
"Sale and Cost"=>Section::create()->sub([
"Sale Reports"=>Group::create()->icon("fa fa-line-chart")->sub([
"Overview"=>SaleOverviewBoard::create(),
"Main Products"=>MainProductBoard::create(),
]),
"Cost Reports"=>Group::create()->icon("fa fa-pie-chart")->sub([
"Overview Cost"=>CostOverviewBoard::create(),
"BreakDown Cost"=>BreakDownCostBoard::create(),
])
])
];
}
}
Properties #
Name | type | description |
---|---|---|
title | string | Get/set title of Dashboard which will appear on top of browser tab |
logo | string | Get/set the logo on top left of Dashboard |
favicon | string | Get/set the favicon for Dashboard |
footerLeft | string | Get/set html for left footer |
footerRight | string | Get/set html for right footer |
debugMode | boolean | Get/set whether dashboard is in debugMode, default is false |
csrf | CSRF/function | Get/set csrf object or function to return csrf object |
assets | array | Get/set the assets settings |
css | string/array | Get/set extra css style file |
js | string/array | Get/set extra js file |
Note: Those above properties follows this code rules.
Examples:
//Set property within App class:
class App extends Application
{
protected function onCreated()
{
$this
->title("My Dashboard")
->logo("<b>My Dashboard</b>")
->favicon("images/superman.ico")
->footerLeft("Dashboard@KoolReport")
->footerRight("Powered by KoolReport")
->csrf(\koolreport\dashboard\security\CSRF::create())
->css("extra.css") //->css(["extra1.css","extra2.css"])
->js("extra.js") //->js(["extra1.js","extra2.js"]);
}
}
//Set properties outside App class
App::create()
->title("My Dashboard")
->logo("<b>My Dashboard</b>")
->favicon("images/superman.ico")
->footerLeft("Dashboard@KoolReport")
->footerRight("Powered by KoolReport")
->csrf(\koolreport\dashboard\security\CSRF::create())
->css("extra.css") //->css(["extra1.css","extra2.css"])
->js("extra.js") //->js(["extra1.js","extra2.js"])
->run();
Methods #
Name | type | description |
---|---|---|
user() | User | Get user object |
request() | Request | Get request object |
permit() | Permit | Get the permission object |
Authentication #
Enable Login page #
By default, any one can access the dashboard. If you would like to have dashboard's login, you do as following:
use \koolreport\dashboard\Application;
use \koolreport\dashboard\pages\Login;
use \koolreport\dashboard\User;
class App extends Application
{
protected function login()
{
return Login::create()
->authenticate(function($username,$password){
if($username==="admin@example.com" && $password==="admin_password")
{
// If authenticated, return User object
return User::create()
->id(1)
->name("Admin")
->avatar("avatars/8.jpg")
->roles(["admin"]);
}
// If unauthenticated, return null
return null;
});
}
}
Basically, to turn on authentication feature, we will need to provide Login page with authenticate()
method. In the anonymous function provided inside authenticate()
, we will receive $username
and $password
as parameters, we will check whether they are valid login. If they are correct, we will return User
object. If not, we will return null
value indicating that login is failed.
Set user directly #
If you establish dashboard as a part of your existed application, there is high chance that you have login system already and when authenticated user access dashboard, we do not want user to do login again. In this case, we can set user like following:
//index.php
App::create()
->user(
User::create()
->id($id)
->name($name)
->avatar("avatars/user.jpg")
->roles(["user"])
)
->run();
By providing user object, the dashboard app will bypass the Login page.
Authorization #
App's access authorization #
allowAccess()
method is the front gate keeper of authorization. return false;
from the method will block the request and return Unauthorized
response. We can use the method to pre-check the request received and user's permission to decide whether request is authorized to go through.
use \koolreport\dashboard\Application;
class App extends Application
{
protected function allowAccess($request)
{
$user = $request->user();
$route = $request->route();
$action = $request->action();
$params = $request->params();
//Allow true to allow access and false otherwise
return true;
}
}
Permissions #
By deriving the permission()
method and provide Permit
object, we are able to set authorization rules for users and requests. For more information of Permit class, please click here.
use \koolreport\dashboard\Application;
class App extends Application
{
protected function permission()
{
return Permit::create();
}
}
Security #
CSRF Protection #
Cross-site request forgeries are a type of malicious exploit whereby unauthorized commands are performed on behalf of an authenticated user. Dashboard Framework makes it easy to protect your dashboard from Cross-Site Request Forgery (CSRF).
To enabled CSRF you only need to add csrf()
method inside your application class and return the CSRF class like following:
use \koolreport\dashboard\security\CSRF;
class App extends Application
{
//..
protected function csrf()
{
return CSRF::create();
}
}
Create your own csrf token:
use \koolreport\dashboard\security\CSRF;
class App extends Application
{
//..
protected function csrf()
{
return CSRF::create()
->name("_token")
->token(function(){
return "Your own generated token";
});
}
}
The name
is the name of csrf token posted from client, the default value is "_token"
but you can change to any value.
If you use dashboard inside Laravel and would like to use laravel-compatible CSRF, you do:
use \koolreport\dashboard\security\CSRF;
class App extends Application
{
//..
protected function csrf()
{
return CSRF::create()
->name("_token")
->token(csrf_token());
}
}
Another way of set csrf token is when you create application:
App::create()
->csrf(\koolreport\dashboard\security\CSRF::create())
->run();
Assets #
The assets of dashboard like js file or css file may be located inside prohibited folder like "vendor"
so the browser may not access them. So we will need to set a public place whether assets will be populated to.
General usage #
In order to set assets location, you only need to provide assets()
method inside Application and return assets settings:
class App extends Application
{
protected function assets()
{
return [
"url"=>"/assets",
"path"=>"../../public/assets"
];
}
}
Auto-configure Assets with other MVC Frameworks #
Laravel:
class App extends Application
{
use \koolreport\dashboard\inside\Laravel;
...
}
CodeIgniter:
class App extends Application
{
use \koolreport\dashboard\inside\CodeIgniter;
...
}
Yii2:
class App extends Application
{
use \koolreport\dashboard\inside\Yii2;
...
}
Language #
In order to set language, we do:
use \koolreport\dashboard\Application;
class App extends Application
{
use \koolreport\dashboard\languages\ES;
}
Theme #
In order to set theme, we do:
use \koolreport\dashboard\Application;
class App extends Application
{
use \koolreport\dashboard\amazing\Theme;
}
Currently, Amazing
theme is default and the only theme of Dashboard app. This Amazing
theme will be used regardless you set theme. In the future, more themes will be available.
Get started with KoolReport
KoolReport will help you to construct good php data report by gathering your data from multiple sources, transforming them into valuable insights, and finally visualizing them in stunning charts and graphs.