Welcome to the Dorguzen Documentation
Current version: V1.0.0
A PHP MVC development framework. Your Rapid Web Development Toolkit
It's light, fast, and up to the task. It's ideal for churning out small to medium size enterprise applications rapidly. Light-weight, yet powerful, fully equipped with useful development tools that you will get comfortable with in no time. The learning curve is non-deterring as is normally the case when you pick up a new framework, and this was the goal. The idea is to get you focused on your application logic.
It's readable and expressive. We believe the result of this combination is a smooth flow in the development process that amounts to faster development.
Its key hallmarks are:
- Simplified routing
- Simple HTTP API system-there are only a handful or character sets you can pass in the browser URL to make your web pages come alive
- Simple Object Relational Mapping (ORM) system built into its models
- A model-database chaining system based on the rule of 'convention over configuration' which if followed will give you a great head start
- The aim is to strip out over-complexity, and hand the reigns of control to the developer as quickly as possible.
HOW TO INSTALL AND START A NEW APPLICATION
In order not to make it sound complicated, we will show you how to install the application and display the welcome page (basically, the 'Hello World' page) first of all, before you can start modifying files and folder names to suit the custom application you are building. You can get the code in two ways; either by cloning/downloading the source code directly from gitHub onto your server root folder and having all the code at your disposal, ready to start building your awesome new application :), or pulling it in via Composer.
Cloning or downloading from GitHub
Here is the Github repository link:
Using Composer
To get your first Dorguzen 'Hello world' page up in minutes, -Open your terminal application and navigate to your server root where you have all your web projects and after initialising Composer in that folder (composer init) run the following command:
composer create-project nolimitmedia/dorguzen
It will create a folder called 'dorguzen' and install the Dorguzen framework for you in it.
The name of the application that it has started you off with is called Dorguzen, so you need to change that to the name of the app you are building. To do so, follow the following steps:
- Start by changing the name of the root folder from 'dorguzen' to yourAppName
- Navigate to settings/Settings.php (a config class file as you can probably guess), and from top to bottom change every instance of 'dorguzen' or 'dorguzApp' to yourAppName. All the settings in this file are pretty self-explanatory and are well commented so you will know what to put under each group just by looking at the notes in there. It contains things like appUrl, appBusinessName, localUrl, liveUrl, localDBCredentials, liveDBCredentials etc etc. You will be using this file a lot, but the most important settings to get you up and running are the layout directory and layout class file and the DB connection stuff Dorguzen needs to know the layout directory path in order to route your view files properly.
- Dorguzen comes with an sql file to start you off with a database. This file is called 'dorguzApp.sql'. Import it into your database using your database client software and it will create a database called 'dorguzApp'. The user credentials Dorguzen expects to use to access this database are found in Settings.php and look as follows:
'localDBcredentials' => [
'username' => 'dorguz',
'pwd' => 'dorguz123',
'db' => 'dorguzApp',
'host' => 'localhost',
'connectionType' => 'mysqli',
'key' => 'takeThisWith@PinchOfSalt'
],
'liveDBcredentials' => [
'username' => 'dorguz',
'pwd' => 'dorguz123',
'db' => 'dorguzApp',
'host' => 'localhost',
'connectionType' => 'mysqli',
'key' => 'takeThisWith@PinchOfSalt'
],
You only need to worry about the following three for now:
- Username: 'dorguz'
- Password: 'dorguz123'
- Database: 'dorguzApp'
These connection credentials are already registered in the Settings.php file so all you have to do is run the query to create the database and tables and then use your database client tool, for example phpMyAdmin to create a user 'dorguz' and and assign it a password 'dorguz123' for the database 'dorguzApp'. Obviously, you can name your database something else and use a different username and password to access it. Just make sure you go into the settings/Settings.php file and change the database settings under the 'SET the local/live DB connection credentials' section to match them. Once that is done you can get rid of the dorguzApp.sql file.
Another essential thing to do in the settings file to get you up and running is to specify the layout folder and layout file to be used, without which your routing and views rendering will fail. So still in the Settings.php file; change the value of the 'layoutDirectory' key to 'yourAppName' and the value of 'defaultLayout' to something like 'yourAppNameLayout'. It will look like so:
layoutDirectory' => 'yourAppName',
'defaultLayout' => 'yourAppNameLayout
You then need to make sure this layout directory and file exist. So, go into the layouts folder and change the name of the directory 'dorguzApp' to 'yourAppName' and then go into that directory and change the name of the layout file 'dorguzAppLayout.php' to 'yourAppNameLayout.php'.
Because you changed the name of the layout directory, do not forget to go into this directory and change the namespace of the files in there to reflect the new namespace of the new name you have given to the layout folder.
The three layout files in this layout directory are 'BlankLayout.php', 'yourAppNameBasicLayout.php' and 'yourAppNameLayout.php'. Go into these files and change their namespaces at the top from namespace layouts\dorguzApp; to namespace layouts\yourAppName; Remember that this is because you changed the name of their parent layout directory to 'yourAppName'.
Finally, you can test to see the Dorguzen welcome page in the browser by typing in your browser the URI of that folder on your server. Mine looks something like this:
localhost:8888/myAppName/
Remember you can change your database credentials to whatever you want and register the new details in Settings.php
ADMIN AUTHENTICATION (Login)
Dorguzen comes with a login feature and one super-admin user set up for you with the following login details:
- Username: '[email protected]'
- Password: 'dorguzen'
The email is not a real email address, so you should change the login details to something more secure once you log in. You can scrap this user login/authentication or add to it if you want to build a user authentication feature in a different way. Once logged in, you have access to a dashboard where you can make a couple of management changes to your application. This is meant to give you an idea of how you could go about building a cool content management system. From this dashboard you are able to change your password, create other users who can log into the system. You can view contact messages sent through your application's contact form. These are messages that would have been emailed to you but are also stored in a database table for your perusal in the admin interface from where you can delete them at your convenience.
You are also able to request to reset your password in case you forgot it and are unable to login.
DORGUZEN FOLDER STRUCTURE
The Dorguzen framework comes with the following directory structure:
appName
-assets
-css (for core system styles mostly)
-fonts
-icons
-images
-js (for core system js mostly)
-controllers
-HomeController.php
-AdminController.php
-FeedbackController.php
-SearchController.php
-css (for custom styles targeting specific views)
-DGZ_library
-DGZ_functions (helper functions-feel free to add yours)
-DGZ_Uploader
-DGZ_views
-DGZExceptionView.php
-ErrorsListView.php
-ExceptionView.php
-NoticeListView.php
-SuccessListView.php
-WarningListView.php
-FPDF
-font
-fpdfBaseController.php
-PDFController.php
-PHPExcel
-PHPExcel
-PHPExcel.php
-DGZ_Application.php
-DGZ_CheckPassword.php
-DGZ_Controller.php
-DGZ_Dates.php
-DGZ_DB_Adapter.php
-DGZ_DB_Singleton.php
-DGZ_Displayable.php
-DGZ_Exception.php
-DGZ_FileUploader.php
-DGZ_Form.php
-DGZ_HtmlView.php
-DGZ_Lang.php
-DGZ_Layout.php
-DGZ_Messenger.php
-DGZ_Notifier.php
-DGZ_Paginator.php
-DGZ_Router.php
-DGZ_SliderEngine.php
-DGZ_Table.php
-DGZ_Text.php
-DGZ_Translator.php
-DGZ_Validate.php
-DGZ_View.php
-docs (optional directory for storing files)
-audios
-blog
-audios
-videos
-videos
-js (for custom scripts targeting specific views)
-lang
-layouts
-admin
-admin_footer.inc.php
-admin_header.inc.php
-adminLayout.php
-html_dependencies_bottom.inc.php
-html_dependencies_top.inc.php
-appName
-appNameBasicLayout.php
-appNameLayout.php
-BlankLayout.php
-footer.inc.php
-header.inc.php
-html_dependencies_bottom.inc.php
-html_dependencies_top.inc.php
-models
-BaseSettings.php
-ContactFormMessage.php
-Users.php
-Password_reset.php
-settings
-Settings.php
-views
-admin
-adminHome.php
-adminUserChangePw.php
-contactMessages_TableView.php
-createUser.php
-editUser.php
-manageContactMessages.php
-manageSettings.php
-manageUsers.php
-resetPw.php
contact.php
home.php
jsValidationPartial.php
login.php
-.htaccess
-Autoloader.php
-index.php
-dorguzenApp.sql
Dorguzen comes with a database dorguzApp which contains the following 4 tables:
baseSettings
contactformmessage
password_reset
users
HOW TO CREATE AND DISPLAY A VIEW FILE
The way Dorguzen displays the home/welcome view is exactly how you would create all your other views. Let's learn by observing how it does that. It is done in the following simple steps:
- First, you create the view file. Give this file the same name as the name of the class in this file. Dorguzen expects this, otherwise you will get a 'class not found' error. So Dorguzen comes with a view file home.php. Inside the file, create the class and have it extend the \DGZ_library\DGZ_HtmlView class (all view files must extend this DGZ_HtmlView class). This view class must have one method in it called show(). This show() method contains all your HTML code. See the contents of home.php below.
<?php
namespace views;
class home extends \DGZ_library\DGZ_HtmlView
{
function show()
{ ?>
<h3>Welcome to the Dorguzen Framework</h3>
<p>
Alright we know you have heard about many PHP development frameworks out there, so the pressure is on. What do we tell you about Dorguzen to
make it stand out?
Well...there are so many points we can make but it is really true what they say; that the proof is in the pudding.</p>
<p>In short, the Dorguzen framework is, Your Rapid Web Development Toolkit
</p>
<?php
}
} ?>
<a href="<?=$this->settings->getFileRootPath()?>home/home">Home page>
Note that coming from the layout file, when linking to the home page it uses an absolute path which is produced by a helper
function getFileRootPath() of the Settings class. The layout class has access to this Settings
class. Most parts of the framework do too, so that the settings you make in your settings file can be available everywhere
in your application. In the link, the 'home' after the getHomePage() means we need the
HomeController to handle this request, and the second 'home' after that means we need the home() method of the HomeController
to handle that request. By the way, if you do not specify this method parameter in the link URL, Dorguzen wil assume you want
the request to be handled by the defaultAction(), a default method that all controllers MUST
have-we will talk more about this when we talk about controllers. For now just bear that in mind.
public function home()
{
$view = \DGZ_library\DGZ_View::getView('home', $this, 'html');
$this->setPageTitle('Home');
$this->setImageSlider(true);
$view->show();
}
Notice that in the getView() method we pass the name of the view file we want to show ('home'), followed by $this, which
is this controller (HomeController) so that the HomeController can be assigned to the home view as it's controller when
it's rendered. Don't worry if this all sounds complicated now. You will grasp it as you get familiar with the code.
Also notice the setPageTitle() method being called on the view file that has been retrieved,
and the setImageSlider() method. These are optional, with one serving to set the title
text for the view file and the other to display the image slider when it is rendered. The image slider will probably only
be used for the home page. Finally, do you remember the show() method of the view which
we said will contain all the HTML code of the view file? Well, you need to call it for the view to be displayed in the
browser.
So there you have it; that's how you create and display a view file. Practice creating another view file of your own, say, an aboutus.php view, then create a link for it in the navigation menu, then create a dedicated controller for it (hint: copy and paste HomeController), and get that link to display the aboutus view file in the browser.
ADDING CUSTOM JS or CSS FILES TO VIEW FILES
In Dorguzen, most core scripts and styles are placed in the assets/css or assets/js directory. These directories are ideal for code that you want to have available all over your application, there is nothing stopping you from placing your own scripts and style sheets there too. Files in these locations should then be pulled into your application (linked to) from your applications's layout file. Here is an example of pulling in Twitter Bootstrap code into an application from the layout
<link href="<?=$this->settings->getFileRootPath()?>assets/css/bootstrap.min.css" rel="stylesheet" type="text/css">
<script src="<?=$this->settings->getFileRootPath()?>assets/js/bootstrap.min.js"></script>
However, there are times when you may want to write and apply scripts or styles to a specific view file or a few files only. In that case it makes sense to be able to just pull those files into a specific view. You can easily do that using the DGZ_HtmlView class's addScript() for adding javaScript files and addStyle() for adding style sheets to specific view files.
With this being said; you can always still pull in files from the core assets/css or assets/js directories, or link to scripts and style sheets on the internet from specific view files. The Dorguzen flow is to guide but never to restrict you.
Add custom JS file to a view file
Just call the the addScript() method of the DGZ_HtmlView class that all view classes extend and pass it a string of the desired javascript, for example addScript('The JS filename') and that script file will be loaded into the view file for you. You need to have the file in the js folder on the root of your Dorguzen application, as that is where Dorguzen will look for the file to load.
Place the following code in your view file, first thing inside the show() method like so:
gallery.php
class gallery extends \DGZ_library\DGZ_HtmlView
{
function show()
{
$this->addScript('general.js');
}
}
Add custom CCS file to a view file
Just call the the addStyle() method of the DGZ_HtmlView class that all view classes extend and pass it a string of the desired CSS file, for example addStyle('The CSS filename') and that css file will be loaded into the view file for you. You need to have the file in the css folder on the root of your Dorguzen application, as that is where Dorguzen will look for the file to load.
Place the following code in your view file, first thing inside the show() method like so:
gallery.php
class gallery extends \DGZ_library\DGZ_HtmlView
{
function show()
{
$this->addStyle('general.css');
}
}
You can pull into individual view files, scripts or stylesheets from the assets/css or assets/js directory, or from the internet too in just the same way.
class gallery extends \DGZ_library\DGZ_HtmlView
{
function show()
{
$this->addStyle('general.css');
$this->addScript('general.js');
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript" src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js?lang=php&skin=sunburst"></script> }
}
WORKING WITH LAYOUT FILES
How Layouts work
There is a layouts folder in which you would have a sub-folder for every new layout that you create. You would have different layouts for different applications you build, or different parts of your site, like the client-facing part of your website, and the admin section exclusively used by you, and, or your collegeues or members or staff. Views are rendered by controllers. You will declare the layout that a view you are about to render in a controller should use by specifying two things; the layout folder (folder in which the target layout is fount) and the name of the layout file to grab and use. You should set a default layout for for your app to use, as most apps tend to use only one layout, and only specify another layout on the fly as you create a view only if that specific view needs a different layout. The default layout can be set in the settings class, found in the settings file which is inside the settings folder. Place the directives inside the array returned by the getSettings() method like so:
public function getSettings()
{
return [
/*
|-------------------------------------------------------
| Layout settings
|-------------------------------------------------------
|
| Determine which layouts to use by default for your views
|
*/
'useFullLayout' => true,
'siteName' => 'appName',
'layoutDirectory' => 'appName',
'defaultLayout' => 'appNameLayout',
The 'appNameLayout' for the defaultLayout refers to the appNameLayout class inside the appNameLayout.php file located in layouts/appName/ directory.
Display a view using a specific layout
As we mentioned above under “How the layouts work”, views are rendered by controllers. To do so, you have to declare two things:
- The layouts folder to use
- The layouts file (class) to use For example:
public function manageBlog()
{
$view = \DGZ_library\DGZ_View::getAdminView('manageBlog', $this, 'html');
$this->setLayoutDirectory('admin');
$this->setLayoutView('adminLayout');
$view->show();
}
This manageBlog() is a method in a controller class that is about to render an existing view. In this case, the layout directory has been specified as the 'admin' layouts/admin directory, and the layouts class (file) to use in this layouts directory is the “adminLayout” class (which will be in the adminLayout.php file). folder.
Examples of specifying layouts and views to show in them $this->setLayoutDirectory('CoolPersonalWebsite'); (In case you want a different directory from the default one) $this->setLayoutView('EmailLayout'); (layout view to use from layout views in that directory) OR $this->setLayoutView('ResponsiveLayout'); $this->setImageSlider(true); (Whether or not to display an image slider in the coming view)OR $view = \DGZ_library\DGZ_View::getAdminView('login', $this, 'html'); $this->setPageTitle('login'); $this->setLayoutDirectory('admin'); $this->setLayoutView('adminLayout'); $view->show();
Display a view with a blank layout
To do that, in your controller before you display a view, just call the setNoLayout() method like so:
public function defaultAction()
{
//If you set no layout view, the default layout will be used
//if you set a layout (like so: setLayoutView('EmailLayout');) make sure that layout file (class) is in the default layout directory
//if you set a default layout folder (like so: $this->setDefaultLayoutDirectory('CoolPersonalWebsite');), make sure you also set the layout file to be used
//in that 'CoolPersonalWebsite' directory.
$view = \DGZ_library\DGZ_View::getView('home', $this, 'html');
//We do not need the regular layout of this app which comes with other page sections like latest blog posts, brands etc for this view
//this is because this view is the intro view for this site which has a video background and a central button to let visitors enter the site.
$this->setNoLayout(); //--------------------------------
$this->setPageTitle('Welcome to Nolimitmedia');
$view->show();
}
VIEW FILES AND REDIRECTION
How to create a view file
Create a php file inside your views folder. Create a class inside this file which MUST have the same name as the name of the file without the .php extension. This class must extend the DGZ_HtmlView class found in the DGZ_library folder Give it the namespace of the views folder. This class should have one method, and it is the show() {} in which all your HTML code will be placed. Here is an example:
You would create a view file portfolio.php inside the views folder which contains the class portfolio
namespace views;
class portfolio extends \DGZ_library\DGZ_HtmlView
{
function show()
{
//All your HTML code for the portfolio view file code goes in here
}
}
Accessing controllers within view files
In Dorguzen every view file is assigned a controller that is responsible for doing things like generating that view when a user requests for it, processing requests from form requests submitted from that view file, passing messages like success or error messages back to the form to give feedback on the request that was being processed etc. This means that to call on the controller of a view, all you have to do is this: $this->controller->someMethodOnTheController();.
But there will be situations when you would want to make use of another controller not related to the current view file. It's simple, above your view class just pull in any controller class you need using the 'use' keyword as you would normally do. Then proceed to instantiate that class and use it in the view file. In the following example in the audio view file, the videoController is pulled in so that video data can be used within this audio view file:
namespace views;
use controllers\VideoController;
class audio extends \DGZ_library\DGZ_HtmlView
{
function show()
{
$video = new VideoController();
...
$allVideoGroups = $video->getAllVideoCategories();
...
}
}
Setting the title of a view file
You generate a title for your web page from within you controller as you render the view file and display it. In the following example; inside a controller, we are about to render a view class called adminHome and therefore before we do so, we establish its title string wich will be placed inside its <title> tags upon creation by using the setPageTitle() method that is available to all controllers.
public function dashboard()
{
$view = \DGZ_library\DGZ_View::getAdminView('adminHome', $this, 'html');
$this->setPageTitle('Admin');
$this->setLayoutDirectory('admin');
$this->setLayoutView('adminLayout');
$view->show();
}
Redirect a user to a different view
This can be done in three ways
- Using the header() function in PHP
- Using the DGZ_View class's getView() method that we have seen before, which retrieves the view file you pass to it and then when you call its show() method, it displays the view. Note that there are two of these methods; getView() and getAdminView(). The one gets the given view file from views/ while the other gets it from the views/admin directory respectively. The views/admin is where administrator view files are kept just to separate them from regular view files. Having them separate also means you can enforce extra access security restrictions on that folder.
- Using the awesome redirect() method of DGZ_controller which takes the name of a controller and the method on it to send the request to, and an array of parameters to pass as query strings if needed.
1) Using the header() function in PHP
Redirection to view files is done from inside your controller. Here is an example of how you would redirect to a view file named manageUsers using the header() function of PHP.
if ($updated)
{
header('Location: Admin/manageUsers');
exit();
}
2) Using the DGZ_View/getView()/DGZ_View/getAdminView() methods
Here is an example of how you would redirect to a view file named manageUsers using the getView() static method of Dorguzen's DGZ_View class.
$view = \DGZ_library\DGZ_View::getView('contact', $this, 'html');
$view->show();
OR
$view = \DGZ_library\DGZ_View::getAdminView('manageUsers', $this, 'html');
$view->show();
As seen in the example, you have to first of all grab the file or rather the view object, and pass it the name of the view file. Then call the show() method on that view file (class) to actually display its contents. This show() method can be used to pass data which will become available inside that view class (file).
3) Using the controller redirect() method
Controllers have a very handy redirect helper function called redirect(). It takes three arguments,
- The controller name to receive the request (string) written in its short form without the 'Controller' word just as you would submit it to the browser URL e.g. 'home' for the 'HomeController'.
- The method of the controller to handle the request (string)
- The arguments to be passed to the method (an array) if there are any
For example; you would redirect to the galleryController's show() method passing it an album ID from within a controller like so:
$this->redirect('gallery','show', ['albumName' => 'fun', 'albumId' => 13]);
redirect() will format that request nicely, converting the array of URL parameters into a legal query string and redirect the user to the following URL:
http:appName/gallery/show?albumName=fun&albumId;=13
It is much easier to use the redirect() method because not only does it format your URL parameters and creates the URL for you,
it will also make resolve for you any issues relating to the common
You can even pass notification messages to the view with redirect() like so: $this->addSuccess('Welcome Admin, long time!', 'Hey'); $this->redirect('admin','dashboard'); exit();
But hey...that is what we were going to talk about next :)
Redirecting to a view and passing data to it
Here is how you can redirect the user to a view file and pass data to be available in that view.
$userId = $_GET['userId'];
$user = new \Users();
$userForEdit = $user->getUserById($userId);
$view = \DGZ_library\DGZ_View::getAdminView('editUser', $this, 'html');
$view->show($userForEdit, $userId);
What is happening here is this; data is being fetched about a given user, then the view file to display that data is grabbed. That view file is editUser.php and the user's data is passed into it through its show() method, together with the user id ($userId) as the second parameter. These will then be available for use inside that view file. For example, it could be used to display that user's details in a form so they can be edited.
Redirecting to a view and passing a message to it
This message flow is passed down from the controller to the view file associated with it. The message is set at the same time as creating the view file,. As a matter of fact, this happens just before you display the view file. Let's get right into it; use the addErrors() method available to all controller classes to pass an error to a view file. The first parameter is a string of the message you want displayed on the view file when it is displayed. There is a second, optional string parameter which is the heading of the message, if you want it to have a heading, for example, you may want to stress on the urgency of the message by using this to display something like 'Watch out!' or 'Sorry!', or 'Oops!'...you get what i mean...? Here is how you should do it:
$this->addErrors($errors);
header('Location: Admin/createUser');
OR
$this->addErrors($fail);
$view = \DGZ_library\DGZ_View::getAdminView('editUser', $this, 'html');
$view->show($userForEdit, $userId);
You can also display success messages using the addSuccess() method Here is how you should do it:
if ($updated)
{
$this->addSuccess('The user was successfully updated!', 'Hooray');
header('Location: Admin/manageUsers');
exit();
}
So you can send four types of messages to the view file. Here they are:
- Error messages
- Success messages
- Warning messages
- Notice messages
Each one is styled with a color code. The errors message will be displayed in red, the success will be in green, warnings will be in orange, and notices will be in yellow.
CREATING SITE LINKS
Create a link to the home page
You can always use the getHomePage() method or the getFileRootPath() to get the root folder of the application, and then build up directory roots from it in an absolute fashion.
<li><a href="<?=$this->settings->getHomePage()">Home</a></li>
This will lead to the home page like 'loclhost:8888/appname'. However; the following will work just the same:
<li><a href="<?=$this->settings->getFileRootPath()/gallery/showGallery">Image Gallery</a></li>
The getFileRootPath() will lead the user to the very root folder '/' of the application from where you can build your link path. In this case, this links to the GalleryController on the showGallery() method.
Create a link to any page
Use the getHomePage() method like so:
<li><a href='<?=$this->settings->getHomePage()/aboutUs">About Us</a></li>
This will lead to the about us page like 'loclhost:8888/appname/' then the AboutUsController then the aboutUs() method which ultimately grabs and displays the aboutUs view file.'