Untitled Documentation
Contents
Installation
There a few ways to install Untitled. We'll go into detail about them below., (*1)
Download the source
- Head over to the releases page: https://github.com/Coly010/Untitled/releases
- Click the Download link for the zipped source code.
- Choose a folder to download to.
- Find the downloaded file and unzip it.
- Start developing your app!
Install via composer
You can also install via composer, however it is not recommended as there is a few additional steps needed to get it to work., (*2)
- If you do not have composer installed check here: https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx
- Run the following command
composer require coly010/untitled
- Now navigate into
vendor/coly010/untitled
- Copy the contents of the folder to your app's root.
- Start developing your app!
Quick Start Guide
Making web apps has become an integral part of the tech industry, and we all want
to find an easier way to start from scratch, every time we have a new project., (*3)
That's where Untitled comes in. It streamlines the process of setting up a web
app by doing a lot of the start up work for you. All you need to do is create your
pages and you are good to go! Untitled comes shipped with Twig,
a powerful template engine designed for PHP. It helps separate view logic from app logic., (*4)
Below we'll discuss quickly how to use Untitled for your own projects!, (*5)
Understanding Untitled Workflow
Untitled has a slightly different workflow than you may be used to with different
PHP frameworks., (*6)
Untitled focuses on the pages in your web app. For every page your web app has
you simply create a new Page object to represent it. However, Untitled needs to
match the requested URI to your pages. This is where one of the most powerful features
of Untitled comes in: Routes., (*7)
Each of your Page objects contains an array of Route objects. When creating a Route
object you need to set the URI that the Route will handle. Once you have your Route
objects set up you simply add them to your Page object. Untitled takes care of the
rest., (*8)
DataProcess objects are used if you need to perform any logic associated with a Route.
Say for example you have a login form and you need to validate the form data, you would
create a DataProcess to perform this logic. You then link the DataProcess to the Route
object., (*9)
Twig comes shipped and integrated into Untitled and is
the set method for rendering pages. In your Route object you set the file path to
the html file associated with the Route., (*10)
Create Your First Page
You should take note of the following directory structure for your application:, (*11)
- Application
- Cache
- Config
- DataProcesses
- Pages
- PageName
- Routes
- Views
This directory structure keeps your application code well structured and easy to find., (*12)
For every page you wish to create, always create a directory in the Pages directory
with the name the name of your Page., (*13)
Ok, let's walk through the creation of our first page. Now, most websites have an
About page so lets start there., (*14)
First, create a new folder in the Pages folder and call it About. Now, in the
About folder, create another folder called Routes. It's time now to create the
page.
Create a new PHP file and name it About_Page.php. Notice the _Page suffix. This
helps Untitled discover the pages in your app. It is a requirement to have this
for the framework to work.
Open About_Page.php and type the following:, (*15)
<?php
namespace Application\Pages\About\About_Page;
use Untitled\PageBuilder\Page;
use Application\Pages\About\Routes\About_Route;
class About_Page extends Page {
public function __construct(){
parent::__construct();
$this->AddRoute(new About_Route());
}
}
Now you may see some errors if you are using an IDE. We're going to fix that now.
Go into the Routes folder in your About folder and create a new file called
About_Route.php.
Open About_Route.php and type the following:, (*16)
<?php
namespace Application\Pages\About\Routes\About_Route;
use Untitled\PageBuilder\Route;
class About_Route extends Route {
public function __construct(){
parent::__construct();
$this->Request = "about";
$this->RenderView = true;
$this->ViewFilePath = "About/about.html";
}
public function RunDataProcess(){}
}
As Route is an abstract class we must implement the method RunDataProcess().
The final step to finish your page is create the html file that is associated with
the About page. Go to your Views folder and create a new folder called About.
In this About folder create a new file called about.html.
Open about.html and type the following:, (*17)
<html>
<head>
<title>Example</title>
</head>
<body>
About
This is your about page, (*18)
</body>
</html>
And voila, when someone visits your website at url: http://yoursite.com/about
Untitled will create the page and display it., (*19)
Let's get some View Data!
Rendering a basic page based on a URI is all well and good, but sometimes you need
to process a bit of logic to go with it. Sometimes you have calculations to make or
data to retrieve from a database to help generate content for your page., (*20)
Untitled has a solution for this! And that solution comes in the form of
DataProcesses! A DataProcess in its simplest form is an empty class you can create
to process this logic. Untitled comes with a simple wrapper for PDO for MySQL that you may
find helpful. If not you can always just access the PDO object directly with, (*21)
$db = new Database()->Connect();
$db = $db->DB;
Let's go through an example of how this could work with the About page we created above.
Lets assume that there is a table in the database called content with two columns,
page and content. In this table there is a record that contains the content for
the About page. We need to retrieve this content to display it when a user navigates
to the About page.
Please Note: the following will not work for you unless you create the appropriate
database table with a record. You will also need to change the Database_Config.php
file to match your Database Credentials., (*22)
To do this, create a new file in the DataProcesses folder called About_DataProcess.php.
Open About_DataProcess.php and type the following:, (*23)
<?php
namespace Application\DataProcesses;
use Untitled\PageBuilder\DataProcess;
class About_DataProcess extends DataProcess {
public function __construct(){
parent::__construct();
}
public function RetrieveContent(){
$this->db->Run("SELECT * FROM content WHERE page = :page", [":page" => "about"]);
$content = $this->db->Fetch()['content'];
return $content;
}
}
Next, open About_Route.php (which can be found in Pages/About/Routes).
Add use Application\DataProcesses\About_DataProcess; statement below use Untitled\PageBuilder\Route;
Change the constructor to match the following:, (*24)
public function __construct(){
parent::__construct();
$this->Request = "about";
$this->RenderView = true;
$this->ViewFilePath = "About/about.html";
$this->DataProcess = new About_DataProcess();
}
Now, change public function RunDataProcess(){} to:, (*25)
public function RunDataProcess(){
$this->ViewData = ["content" => $this->DataProcess->RetrieveContent()];
}
It will retrieve the content from the database and pass it to the View Data. This
view data should always be an array and is sent to Twig to pass into the view file.
Therefore in our about.html we can now do the following:, (*26)
<html>
<head>
<title>Example</title>
</head>
<body>
<h2>About</h2>
{{ content }}
</body>
</html>
This will then load the content from the database straight onto the page. Simples., (*27)
Walkthrough
Below you will find more information on different parts of Untitled., (*28)
Set Configuration
There is some configuration options you may need to change to allow your web app
to work. You can find these config files in the Application/Config folder.
By default you should see three files:, (*29)
Application_Config.php
Database_Config.php
Twig_Config.php
If you open Application_Config.php, you will see the following:, (*30)
<?php
namespace Application\Config;
class Application_Config
{
public static $PAGES_DIR = "Application/Pages";
public static $DATA_PROCESSES_DIR = "Application/DataProcesses";
public static $VIEWS_DIR = "Application/Views";
}
$PAGES_DIR represents the relative path to the folder your Pages will be stored
in.
$DATA_PROCESSES_DIR represents the relative path to the folder your DataProcesses will
be stored in.
$VIEWS_DIR represents the relative path to the folder your Views will be stored in.
By default, if you use the folder structure that comes with the source, you should not need
to edit any of these variables., (*31)
If you open Database_Config.php, you will see the following:, (*32)
<?php
namespace Application\Config;
class Database_Config
{
/**
* @var string Database Server host
*/
public static $HOST = "localhost";
/**
* @var string Database name to connect to
*/
public static $DBNAME = "";
/**
* @var string Username for the database
*/
public static $USER = "";
/**
* @var string Password for the associated username
*/
public static $PASS = "";
}
$HOST represents where the MySQL server is hosted. By default, this is normally
localhost.
$DBNAME represents the name of database you wish to use.
$USER represents the username linked to the database.
$PASS represents the password for the associated username., (*33)
Twig_Config.php stores some config for Twig.
If you open Twig_Config.php, you will see the following:, (*34)
<?php
namespace Application\Config;
class Twig_Config
{
/**
* @var string Path to the templates
*/
public static $TEMPLATE_PATH = "Application/Views";
/**
* @var string Path to the cache directory
*/
public static $CACHE_PATH = "Application/Cache";
}
$TEMPLATE_PATH represents the path to the views your application will use.
$CACHE_PATH represents the path to the folder Twig will use to cache your views.
You may run into some issues with this, normally it's due to Twig needing write
permissions for that folder. See here for more information., (*35)
Pages
Pages are the backbone to Untitled. They represent each page that your application
will have. If you think about your web app, you can break it down to having one page,
but with multiple views. Think about it., (*36)
Say you have forums. It should be one page, with
the appropriate content on it, depending if someone is looking at a thread, a post, a category.
A user clicks on a thread, they are still looking at the forum page, but it's showing them that
specific thread, rather than a list of them. But they are still looking at the forum page!, (*37)
Untitled accommodates this way of thinking. It lets the developer create the pages
they need. Routes are then used to decide what view should be showing on that page.
See below for a full reference of Page., (*38)
| Reference |
Description |
$Routes |
public Route[] An array of routes associated with the Page
|
$Twig |
public TwigEnvironment TwigEnvironment, see docs here
|
$RequestType |
public string The request type, normally GET or POST |
$RequestString |
public string The requested URI |
$FoundRoute |
public Route The Route object that was found to match the requested URI |
AddRoute($Route) |
public Add a Route object to the $Routes array. |
GetRouteRequestStrings() |
public Return an array of strings split between GET or POST from the $Routes array. |
SearchRoutes($Request) |
public Search $Routes to find a matching URI string. |
ProcessFoundRoute() |
public Process the found route and either render the page or return the data as a json string |
InitialiseTwig() |
private Initialise the Twig Environment |
Routes
Routes are complementary to Pages. Without Routes, Pages wouldn't work. They are needed
to match requested URI's and show the correct view to match the URI. But Routes do more,
they also provide a way for the developer to link a DataProcess to a specific Route
which allows the developer to split app logic based on the requested URI., (*39)
All Route objects must implement the RunDataProcess method, which is called automatically
by Untitled to execute any app logic associated with that Route., (*40)
Routes have another feature which can come in useful in a number of different situations.
Complex Routes allow a developer to accept parameters straight from the URI. To do this,
the developer needs to know where in the URI each of these arguments will occur., (*41)
Take a simple search feature that you are building for your web app. A lot of the
times, developers simply use GET requests to handle search features. To do the same
in Untitled, you simply create a URI like /search/search_term and then you
would create an appropriate Route like this:, (*42)
<?php
namespace Application\Pages\Search\Routes;
use Untitled\PageBuilder\Route;
use Application\DataProcess\Search_DataProcess;
class Search_Route extends Route {
public function __construct(){
parent::__construct();
$this->ComplexRoute = true;
$this->Request = "search/%VAR%"
$this->RenderView = true;
$this->ViewFilePath = "Search/results.html";
$this->DataProcess = new Search_DataProcess();
}
public function RunDataProcess(){
$this->ViewData = ["search_result" => $this->DataProcess->DoSearch($this->Params[0])];
}
}
Anywhere in the URI that the developer expects an argument, they should use %VAR%
when setting the $Request of the Route. You could even have something crazy like
$this->Request = /search/%VAR%/filesonly/%VAR%/limit/%VAR%/page/%VAR%.
Untitled will simply find the arguments in the URI and add them, one by one to
the $Params array in the Route., (*43)
See below for a full reference of Route:, (*44)
| Reference |
Description |
$ComplexRoute |
public bool Set whether the Route is complex |
$Params |
public mixed[] An array of parameters Untitled has found in the URI |
$Request |
public string The URI the Route is associated with |
$DataProcess |
public DataProcess The DataProcess associated with the Route
|
$RenderView |
public bool Set whether the Route should display a view or return JSON data |
$ViewFilePath |
public string The file path to the view file that should be displayed |
$ViewData |
public mixed[] An array of data to pass to the view file |
RunDataProcess() |
public abstract A method to be implemented by the developer to run app logic |
ProcessRoute() |
public Called by Untitled when building the Page to execute RunDataProcess()
|
DataProcesses
A DataProcess is basically an empty class with a reference to the Database wrapper,
that is extended and used by the developer to store any app logic relating to a specific
Page or Route. If a particular Page has many Route objects, then the developer
may create multiple DataProcess objects to accommodate this and to keep app logic
clean and well maintained. If the database config has not been set, the $db will
also not be set., (*45)
See below for a full reference of DataProcess:, (*46)
| Reference |
Description |
$db |
public Database Database object that the DataProcess can use to query the database |
Additional Library References
Untitled comes shipped with some additional libraries that may aid a developer
in the creation of their web app. See below for their full references., (*47)
Database
The Database is simply a wrapper built for the built in PDO object for MySQL
databases., (*48)
| Reference |
Description |
$DB |
public PDO PDO Object |
$LastQuery |
public string The previous SQL query that was run |
$CurrentQuery |
public string The current SQL query being run |
$PreviousParams |
public mixed[] The previous parameters that were used |
$CurrentParams |
public mixed[] The current parameters that were used |
$CurrentStmt |
public PDOStatement The current PDOStatement object |
$CurrentResult |
public mixed[] The current result set |
$AffectedRows |
public int The number of affected rows |
$NumRows |
public int The number of rows counted |
$InsertId |
public int The ID of the previously inserted row |
Connect() |
public Creates the connection to the database |
Query($query) |
public Runs a given SQL query and returns a PDOStatement object |
Prepare($query) |
public Prepares a SQL query to be executed and returns a PDOStatement object |
Execute($params = []) |
public Executes the prepared statement with the given parameters and returns a PDOStatement object |
Run($sql, $params) |
public Combines the Prepare() and Execute() methods in one and returns a PDOStatement object |
Fetch($FetchType = \PDO::FETCH_BOTH) |
public Returns the result set from the executed query |
FetchAll($FetchType = \PDO::FETCH_BOTH) |
public Returns the all the rows in the result set from the executed query |
NumRows() |
public Returns the value of $NumRows
|
AffectedRows() |
public Returns the value of $AffectedRows
|
InsertId() |
public Returns the value of $InsertId
|
The Input library is a simple class with static methods for accessing the
PHP $_POST and $_GET arrays., (*49)
| Reference |
Description |
Get($key) |
public static mixed Returns the value of $_GET[$key] if it exists, if not returns false. |
Post($key) |
public static mixed Returns the value of $_POST[$key] if it exists, if not returns false. |
Sanitiser
The Sanitiser class comes with some static methods to help the developer sanitise inputs
from the user., (*50)
| Reference |
Description |
Int($value) |
public static int Sanitises and returns a integer value |
Number($value) |
public static float Sanitises and returns a float value |
String($value) |
public static string Sanitises and returns a string value |
Email($value) |
public static string Sanitises a string for email and returns a string value |
Url($value) |
public static string Sanitises a string for url and returns a string value |
Validator
The Validator class comes with some static methods to help the developer validate inputs
from the user., (*51)
| Reference |
Description |
BetweenRange($value, $min, $max) |
public static bool Check if value is between a range |
LettersOnly($value) |
public static bool Check if the string is letters only |
Email($value) |
public static bool Check if string is a valid email address |
Url($value) |
public static bool Check if string is valid URL |
NotEmpty($value) |
public static bool Check if string is not empty |
LengthLessThan($value, $limit) |
public static bool Check if length of string is less than limit |
LengthGreaterThan($value, $limit) |
public static bool Check if length of string is greater than limit |
GreaterThan($value, $limit) |
public static bool Check if value is greater than limit |
LessThan($value, $limit) |
public static bool Check if value is less than limit |
Session
The Session class comes with some static methods to help the developer work with
sessions., (*52)
| Reference |
Description |
Start() |
public static Starts the session |
Add($key, $item) |
public static Add a key value pair to the session array |
Remove($key) |
public static Remove a key value pair from the session array |
Get($key) |
public static Get a value from the session array |
Regenerate() |
public static Regenerate the session |
Destroy() |
public static Destroy the current session |
ULogger
The ULogger is a very basic class with some static methods to help the developer if
they need log anything when debugging their app. It outputs the log in HTML, (*53)
| Reference |
Description |
$Header |
public static string Log heading |
$LogBody |
public static string Log body |
SetLogHeader($header) |
public static Sets the log header |
AddToLog($text) |
public static Appends text to the log |
ShowLog() |
public static Shows the current log |
Log($header, $text) |
public static Quick logging method, sets variables and shows log |
Credits
Untitled
Developed by Colum Ferry.
Copyright © 2017 Colum Ferry
Released under the BSD-3-Clause License, (*54)
Twig
Copyright © 2017 SensioLabs
Released under the BSD-3-Clause License
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE., (*55)
Wallogit.com
