| DOCUMENTATION |
##############################################################
# SunFramework - Open-Source PHP Framework ver. 1.2 #
# Author: Daniel Kurylo #
# #
# Homepage: www.SunFramework.org #
##############################################################
1. Installation
2. Directory tree
3. Writing first working module
4. Modules
a. view
b. model
c. action
5. Database
a. SDB
b. ORM
6. View object
7. Themes
8. Templates
9. I18n
10. Sfadmin
11. Apache rewrite
12. License
1. Instalation
You have to generate config file for your project. Please use sfadmin tool to
generate configuration file.
php lib/sfadmin.php init-app
Next, please change permission for var directory:
chmod 777 var
Please be sure your apache is allowing .htaccess files.
Apache rewrite configuration file .htaccess:
RewriteEngine on
rewritecond %{REQUEST_FILENAME} !^.*/themes/*.*$
RewriteRule .* index.php
Now, your Sunframework is installed.
2. Directory tree
|- conf
| |
| \- config.php Configuration file
|
|- doc Documentation directory
|- lang
| |
| |- src
| | |
| | |- pl_PL.UTF-8
| | \- en_US
| |
| \- bin
| |
| |- pl_PL.UTF-8
| \- en_US
|
|- lib Libraries
|- licences Licenses
|- modules Modules
| |
| |- auth Auth module (loaded when module perm is registred)
| |- module Sample module directory
| \- modules.inc.php Config file for modules
|
|- themes Themes directory
| |
| \- 1
| |- shtm
| | |- module
| | |
| | \- file.shtm
| |- css
| |- fonts
| |- img
| |- js
| \- config.theme.php Config for theme
|
\- var Temporary files directory
2. Writing first working module
First, add your module to modules/modules.inc.php, example:
'customers' => array( 'name' =>'customers', // Module name
'show' =>'yes', // yes, no
'type' =>'module', // library, module
'perm' =>'all', // all / registred with authorization (module auth)
),
Warning!
All modules must be registred in modules.inc.php in other way module will not
working.
Next step to make your first module is generate module by sfadmin
php lib/sfadmin.php add-module moduleName
Example:
php lib/sfadmin.php add-module customers
Now, you have module files in modules/customers.
Sunframework always is including your action.php and creating your module object
and starting run_ACTION method first.
Example:
In our config file is set project url to www.example.com. To visit our module
file we have to go
www.example.com/customers.html.
All working methods to run module:
www.example.com/customers.html
www.example.com/customers/method.html
Okay. We have working module - please read now documentation about themes.
3. Modules
All modules files have tree files:
action.php - framework is including this file and calling run_ACTION first
model.php - we should write all methods to get/send data (example from
DB/XML/RSS/etc)
view.php - view is geting data from model and assigning data to template to
display view (ex. HTML/XML/etc)
Controller is analizing url address to find module and action. If your url
address is www.example.com your module and
action address will be:
www.example.com/module/action.html.
All actions in actions.php have to be called with "_ACTION" string.
Warning !
Only public methods in action.php can be called by Controller. Other methods
like private or protected aren't calling.
COntroller is detecting connection and if connection is from AJAX View Object
isn't display frames - only content from
module. If we want display categories by AJAX to our page we can do something
like this:
sample method in action.php:
public function index_ACTION($argv)
{
$this->view->category_VIEW();
}
sample method in view.php to display HTML page:
public function CategoryTree_VIEW()
{
view::assign('categories', $this->model->getCategories());
return view::fetch("jobs/categories.shtm");
}
sample method in model.php to returning data from database:
public function getCategories()
{
$q = Doctrine_Query::create()
->from('Categories')
->orderby("ca_name")
->execute()
->toArray();
return $q;
}
4. Database
Sunframework is supporting two methods to connect to Database.
SDO - Standard Database Object
You can use standard queries to DB by SDO Object. SDO is based on PDO and have
binds, fetching methods, query methods
etc.
Methods:
select_db($dbname, $conn_id = 1)- Select database
begin($conn_id = 1) - Transaction begin
commit($conn_id = 1) - Transaction commit
rollback($conn_id = 1) - Transaction rollback
connect($db_type, $host, $dbname, $user, $pass, $conn_id = 1) - Connect to
database
disconnect($conn_id = 1) - Disconnect from database
lastInsertedId($conn_id = 1) - Get last inserted id
fetch_row($conn_id = 1) - Fetch one row
fetch_all($conn_id = 1) - Fetch all rows
Sample method in model.php:
public function getCategories()
{
$sql_bind = array(":dbINT_ca_id");
DB::query("SELECT * FROM categories where ca_id = :dbINT_ca_id",$sql_bind);
$arr = DB::fetch_all();
return $arr;
}
ORM - Object-Relational Mapping
More info:
http://www.phpdoctrine.org/
5. View object
View object displays HTML/XML or other view. Sunframework is supporting Dte
templates
(https://sourceforge.net/projects/dte/) and Smarty Template Engine
(http://www.smarty.net/). In config file you are
deciding what engine you want to use. Dte is more simple and fast that is
enabled in standard configuration file.
Methods:
display("/module/file.shtm",$show_frame) - display template
fetch("/module/file.shtm") - return fetched template
public function CategoryTree_VIEW()
{
view::assign('categories', $this->getCategories_VIEW());
return view::display("index/index.shtm");
}
6. Themes
View object is supporting themes. For one project you can have many themes and
for all modules you can set default
theme file. All themes is located in themes/ directory.
Structure:
/themes
|
\- 1 - number of theme
|
|- shtm - templates
|- js - javascript scripts
|- css - styles
|- img - images
|- fonts - fonts
\ config.theme.php - theme config
Configuration file: config.theme.php
public function __construct($theme_id)
{
$this->assign = array ( 'FW_URL' => FW_URL,
'css_dir' => FW_THEME_URL . '/'. $theme_id .'/css',
'img_dir' => FW_THEME_URL . '/'. $theme_id .'/img',
'js_dir' => FW_THEME_URL . '/'. $theme_id .'/js',
'myname' => FW_NAME,
);
$this->frame_file = 'frames.shtm';
$this->frames = array( 'HEAD' => "header.shtm",
'FOOTER' => 'footer.shtm'
);
$this->content_name = "CONTENT";
}
$this->assign - framework will assign this variables on load
$this->frame_file - default frame file (see theme idea)
$this->frames - all frames automatic fetched and assigned to variable on load
$this->content_name - variable name with CONTENT to display in frame file.
Theme idea:
when we want display page View Object is fetching all blocks to variables and
main frames.shtm file is displaying.
When we call view::display("categories.shtm") View object will display
frames.shtm with fetched categories.shtm in
$CONTENT variable. You can call view::display("categories.shtm", true) to
display page without frame file.
Sample frames.shtm:
{$HEAD}
{$CONTENT}
{$FOOTER}
Sample header.shtm:
Sample footer.shtm:
Example of use:
1. We have to create file in themes/1/shtm/module/file.shtm
2. We must call view::display("module/file.shtm") to display page with frames.
Remember!
You must have {$CONTENT} variable in your template because in this variable is
fetched module content.
The best way is creating one frame file and fetch content blocks in variables.
User profile file.
.---------------------------.
| header |
|---------------------------|
| .------. .--------------. |
| | foto | | user info | |
| '------' '--------------' |
| .------. .--------------. |
| | adv | | galery | |
| '------' '--------------' |
'---------------------------|
| footer |
'---------------------------'
All of this blocks should be fetched from modules grouped to functionality
example. Advertisments block should be
fetched from adverts module and foto, galery and user_info from user module. All
of this blocks are variables
frames.shtm:
.-------------------------------.
| {$HEAD} |
|-------------------------------|
| {$CONTENT} |
'-------------------------------|
| {$FOOTER} |
'-------------------------------'
profile.shtm:
|-------------------------------|
| .---------. .---------------. |
| | {$foto} | | {$user info} | |
| '---------' '---------------' |
| .--------. .---------------. |
| | {$adv} | | {$galery} | |
| '--------' '---------------' |
'-------------------------------|
Now, we are displaying profile.shtm and in result we've got:
.-------------------------------.
| {$HEAD} |
|-------------------------------|
| .---------. .---------------. |
| | {$foto} | | {$user info} | |
| '---------' '---------------' |
| .--------. .---------------. |
| | {$adv} | | {$galery} | |
| '--------' '---------------' |
'-------------------------------|
| {$FOOTER} |
'-------------------------------'
We should assign fetched variables by view:assign("name", $variable).
Example profile_VIEW()
{
/**
* We need to load and create adv obj
*/
Module::Load("adv");
$adv = new adv();
view::assign("foto", $this->getFoto_VIEW());
view::assign("user_info", $this->getUInfo_VIEW());
view::assign("adv", $adv->view->getAdv_VIEW());
view::assign("galery", $this->getGalery_VIEW());
view::display("profile.shtm");
}
7. Templates
Sunframework is supporting DTE and Smarty. All temp files is located in var/
directory.
8. Locales
You can find locales in lib/Lang/. If you want to create new locale you have to
crate file in lib/Lang/ called like
en, uk, pl etc. and create locale object. Sample locale file:
public $lang = array(
'name' => 'English',
'orig' => 'English',
'locale' => 'en_US',
'charset' => 'UTF-8',
'html' => 'en',
'money_format' => '$ %01.2f'
);
8. I18n
I18n is supported by gettext. Default gettext is enabled and DTE is working with
gettext file.
First create your language file - the same as your locale name. Example if we
have to pl_PL.UTF-8 we have to create
src file in lang/src/pl_PL.UTF-8/LC_MESSAGES/modulename.po
Sample of gettext source file index.po
msgid "work"
msgstr "praca"
Next, you have to compile language file by sfadmin
php lib/sfadmin.php compile-lang langCode moduleName
To translate file in php you can use _("work") or in shtm template file (DTE)
use {t}work{/t}
9. Sfadmin
Sfadmin is helpful to init application, add module, generate ORM models files,
new themes etc.
- Init application:
php lib/sfadmin.php init-app
- Add module:
php lib/sfadmin.php add-module name
- Generate models:
php lib/sfadmin.php gen-models
- Compile gettext src file to binary:
php lib/sfadmin.php compile-lang en module
- Clear cache:
php lib/sfadmin.php clear-cache
by:
php lib/sfadmin.php
10. Apache rewrite
Apache rewrite configuration file .htaccess:
RewriteEngine on
rewritecond %{REQUEST_FILENAME} !^.*/themes/*.*$
RewriteRule .* index.php
11. License
See more in licenses/ directory.
# SunFramework - Open-Source PHP Framework ver. 1.2 #
# Author: Daniel Kurylo
# #
# Homepage: www.SunFramework.org #
##############################################################
1. Installation
2. Directory tree
3. Writing first working module
4. Modules
a. view
b. model
c. action
5. Database
a. SDB
b. ORM
6. View object
7. Themes
8. Templates
9. I18n
10. Sfadmin
11. Apache rewrite
12. License
1. Instalation
You have to generate config file for your project. Please use sfadmin tool to
generate configuration file.
php lib/sfadmin.php init-app
Next, please change permission for var directory:
chmod 777 var
Please be sure your apache is allowing .htaccess files.
Apache rewrite configuration file .htaccess:
RewriteEngine on
rewritecond %{REQUEST_FILENAME} !^.*/themes/*.*$
RewriteRule .* index.php
Now, your Sunframework is installed.
2. Directory tree
|- conf
| |
| \- config.php Configuration file
|
|- doc Documentation directory
|- lang
| |
| |- src
| | |
| | |- pl_PL.UTF-8
| | \- en_US
| |
| \- bin
| |
| |- pl_PL.UTF-8
| \- en_US
|
|- lib Libraries
|- licences Licenses
|- modules Modules
| |
| |- auth Auth module (loaded when module perm is registred)
| |- module Sample module directory
| \- modules.inc.php Config file for modules
|
|- themes Themes directory
| |
| \- 1
| |- shtm
| | |- module
| | |
| | \- file.shtm
| |- css
| |- fonts
| |- img
| |- js
| \- config.theme.php Config for theme
|
\- var Temporary files directory
2. Writing first working module
First, add your module to modules/modules.inc.php, example:
'customers' => array( 'name' =>'customers', // Module name
'show' =>'yes', // yes, no
'type' =>'module', // library, module
'perm' =>'all', // all / registred with authorization (module auth)
),
Warning!
All modules must be registred in modules.inc.php in other way module will not
working.
Next step to make your first module is generate module by sfadmin
php lib/sfadmin.php add-module moduleName
Example:
php lib/sfadmin.php add-module customers
Now, you have module files in modules/customers.
Sunframework always is including your action.php and creating your module object
and starting run_ACTION method first.
Example:
In our config file is set project url to www.example.com. To visit our module
file we have to go
www.example.com/customers.html.
All working methods to run module:
www.example.com/customers.html
www.example.com/customers/method.html
Okay. We have working module - please read now documentation about themes.
3. Modules
All modules files have tree files:
action.php - framework is including this file and calling run_ACTION first
model.php - we should write all methods to get/send data (example from
DB/XML/RSS/etc)
view.php - view is geting data from model and assigning data to template to
display view (ex. HTML/XML/etc)
Controller is analizing url address to find module and action. If your url
address is www.example.com your module and
action address will be:
www.example.com/module/action.html.
All actions in actions.php have to be called with "_ACTION" string.
Warning !
Only public methods in action.php can be called by Controller. Other methods
like private or protected aren't calling.
COntroller is detecting connection and if connection is from AJAX View Object
isn't display frames - only content from
module. If we want display categories by AJAX to our page we can do something
like this:
sample method in action.php:
public function index_ACTION($argv)
{
$this->view->category_VIEW();
}
sample method in view.php to display HTML page:
public function CategoryTree_VIEW()
{
view::assign('categories', $this->model->getCategories());
return view::fetch("jobs/categories.shtm");
}
sample method in model.php to returning data from database:
public function getCategories()
{
$q = Doctrine_Query::create()
->from('Categories')
->orderby("ca_name")
->execute()
->toArray();
return $q;
}
4. Database
Sunframework is supporting two methods to connect to Database.
SDO - Standard Database Object
You can use standard queries to DB by SDO Object. SDO is based on PDO and have
binds, fetching methods, query methods
etc.
Methods:
select_db($dbname, $conn_id = 1)- Select database
begin($conn_id = 1) - Transaction begin
commit($conn_id = 1) - Transaction commit
rollback($conn_id = 1) - Transaction rollback
connect($db_type, $host, $dbname, $user, $pass, $conn_id = 1) - Connect to
database
disconnect($conn_id = 1) - Disconnect from database
lastInsertedId($conn_id = 1) - Get last inserted id
fetch_row($conn_id = 1) - Fetch one row
fetch_all($conn_id = 1) - Fetch all rows
Sample method in model.php:
public function getCategories()
{
$sql_bind = array(":dbINT_ca_id");
DB::query("SELECT * FROM categories where ca_id = :dbINT_ca_id",$sql_bind);
$arr = DB::fetch_all();
return $arr;
}
ORM - Object-Relational Mapping
More info:
http://www.phpdoctrine.org/
5. View object
View object displays HTML/XML or other view. Sunframework is supporting Dte
templates
(https://sourceforge.net/projects/dte/) and Smarty Template Engine
(http://www.smarty.net/). In config file you are
deciding what engine you want to use. Dte is more simple and fast that is
enabled in standard configuration file.
Methods:
display("/module/file.shtm",$show_frame) - display template
fetch("/module/file.shtm") - return fetched template
public function CategoryTree_VIEW()
{
view::assign('categories', $this->getCategories_VIEW());
return view::display("index/index.shtm");
}
6. Themes
View object is supporting themes. For one project you can have many themes and
for all modules you can set default
theme file. All themes is located in themes/ directory.
Structure:
/themes
|
\- 1 - number of theme
|
|- shtm - templates
|- js - javascript scripts
|- css - styles
|- img - images
|- fonts - fonts
\ config.theme.php - theme config
Configuration file: config.theme.php
public function __construct($theme_id)
{
$this->assign = array ( 'FW_URL' => FW_URL,
'css_dir' => FW_THEME_URL . '/'. $theme_id .'/css',
'img_dir' => FW_THEME_URL . '/'. $theme_id .'/img',
'js_dir' => FW_THEME_URL . '/'. $theme_id .'/js',
'myname' => FW_NAME,
);
$this->frame_file = 'frames.shtm';
$this->frames = array( 'HEAD' => "header.shtm",
'FOOTER' => 'footer.shtm'
);
$this->content_name = "CONTENT";
}
$this->assign - framework will assign this variables on load
$this->frame_file - default frame file (see theme idea)
$this->frames - all frames automatic fetched and assigned to variable on load
$this->content_name - variable name with CONTENT to display in frame file.
Theme idea:
when we want display page View Object is fetching all blocks to variables and
main frames.shtm file is displaying.
When we call view::display("categories.shtm") View object will display
frames.shtm with fetched categories.shtm in
$CONTENT variable. You can call view::display("categories.shtm", true) to
display page without frame file.
Sample frames.shtm:
{$HEAD}
{$CONTENT}
{$FOOTER}
Sample header.shtm:
Sample footer.shtm:
Example of use:
1. We have to create file in themes/1/shtm/module/file.shtm
2. We must call view::display("module/file.shtm") to display page with frames.
Remember!
You must have {$CONTENT} variable in your template because in this variable is
fetched module content.
The best way is creating one frame file and fetch content blocks in variables.
User profile file.
.---------------------------.
| header |
|---------------------------|
| .------. .--------------. |
| | foto | | user info | |
| '------' '--------------' |
| .------. .--------------. |
| | adv | | galery | |
| '------' '--------------' |
'---------------------------|
| footer |
'---------------------------'
All of this blocks should be fetched from modules grouped to functionality
example. Advertisments block should be
fetched from adverts module and foto, galery and user_info from user module. All
of this blocks are variables
frames.shtm:
.-------------------------------.
| {$HEAD} |
|-------------------------------|
| {$CONTENT} |
'-------------------------------|
| {$FOOTER} |
'-------------------------------'
profile.shtm:
|-------------------------------|
| .---------. .---------------. |
| | {$foto} | | {$user info} | |
| '---------' '---------------' |
| .--------. .---------------. |
| | {$adv} | | {$galery} | |
| '--------' '---------------' |
'-------------------------------|
Now, we are displaying profile.shtm and in result we've got:
.-------------------------------.
| {$HEAD} |
|-------------------------------|
| .---------. .---------------. |
| | {$foto} | | {$user info} | |
| '---------' '---------------' |
| .--------. .---------------. |
| | {$adv} | | {$galery} | |
| '--------' '---------------' |
'-------------------------------|
| {$FOOTER} |
'-------------------------------'
We should assign fetched variables by view:assign("name", $variable).
Example profile_VIEW()
{
/**
* We need to load and create adv obj
*/
Module::Load("adv");
$adv = new adv();
view::assign("foto", $this->getFoto_VIEW());
view::assign("user_info", $this->getUInfo_VIEW());
view::assign("adv", $adv->view->getAdv_VIEW());
view::assign("galery", $this->getGalery_VIEW());
view::display("profile.shtm");
}
7. Templates
Sunframework is supporting DTE and Smarty. All temp files is located in var/
directory.
8. Locales
You can find locales in lib/Lang/. If you want to create new locale you have to
crate file in lib/Lang/ called like
en, uk, pl etc. and create locale object. Sample locale file:
public $lang = array(
'name' => 'English',
'orig' => 'English',
'locale' => 'en_US',
'charset' => 'UTF-8',
'html' => 'en',
'money_format' => '$ %01.2f'
);
8. I18n
I18n is supported by gettext. Default gettext is enabled and DTE is working with
gettext file.
First create your language file - the same as your locale name. Example if we
have to pl_PL.UTF-8 we have to create
src file in lang/src/pl_PL.UTF-8/LC_MESSAGES/modulename.po
Sample of gettext source file index.po
msgid "work"
msgstr "praca"
Next, you have to compile language file by sfadmin
php lib/sfadmin.php compile-lang langCode moduleName
To translate file in php you can use _("work") or in shtm template file (DTE)
use {t}work{/t}
9. Sfadmin
Sfadmin is helpful to init application, add module, generate ORM models files,
new themes etc.
- Init application:
php lib/sfadmin.php init-app
- Add module:
php lib/sfadmin.php add-module name
- Generate models:
php lib/sfadmin.php gen-models
- Compile gettext src file to binary:
php lib/sfadmin.php compile-lang en module
- Clear cache:
php lib/sfadmin.php clear-cache
by:
php lib/sfadmin.php
10. Apache rewrite
Apache rewrite configuration file .htaccess:
RewriteEngine on
rewritecond %{REQUEST_FILENAME} !^.*/themes/*.*$
RewriteRule .* index.php
11. License
See more in licenses/ directory.
