phacil-framework

A super easy PHP Framework for web development!

Requirements

• PHP 5.3+
• OPCache PHP Extension
• HTTP Web Server (Apache 2.4+ recomended)

Structure

Folder	Description
Controller	Contains the structure and files of controllers code
Model	Contais directories and files for the model code
View	Contains the template files
Cache	Full writable default cache storage
public_html	Contains the index.php and .htaccess Apache file. All your access public files stay here, like CSS, JavaScript, etc.
System	Most important folder of this framework. Contains the libraries, classes and anothers features to improve correct working for the Web App.
Logs	Contais debug and error logs
config.php	File with contains all basic configurations for the Web App, like DB connection, mail config, directory config, etc.

Get started!

Copy or clone this repository in your computer/server and edit the config.php file. See below the Config File Basic Options.

Hello World! sample

This is a simple Hello World! for this framework.

1. In controller folder, create a folder called common and create a file called home.php.
2. Edit controller/common/home.php like that.

<?php

class ControllerCommonHome extends Controller {
    public function index() {
   	 $this->data['variable'] = "Hello World!";

   	 $this->out();
    }
}

3. Now create a folder insede view called default and a subfolder called common and a file home.twig.
4. Edit the view/default/common/home.twig like this.

<h1>{{ variable }}</h1>

5. Edit the constants HTTP_URL and DIR_APPLICATION in file config.php. Edit others DIR_* constants path if necessary.

<?php

define('HTTP_URL', 'http://phacil.local/');
define('HTTPS_URL', HTTP_URL);
define('HTTP_IMAGE', HTTP_URL);

define('USE_DB_CONFIG', false);

define('DEBUG', true);

$configs = array('PatternSiteTitle'=>' - ExacTI phacil',
   			 'config_mail_protocol'=>'smtp',
   			 'config_error_display' => 1,
   			 'config_template' => "default",
   			 'config_error_filename'=> 'error.log');

//App folders
define('DIR_APPLICATION', '/Applications/MAMP/htdocs/phacil/');
define('DIR_LOGS', DIR_APPLICATION.'logs/');
define('DIR_PUBLIC', DIR_APPLICATION.'public_html/');
define('DIR_SYSTEM', DIR_APPLICATION.'system/');
define('DIR_IMAGE', DIR_APPLICATION.'public_html/imagens/');
define('DIR_TEMPLATE', DIR_APPLICATION.'view/');
define('DIR_CACHE', DIR_APPLICATION.'cache/');

6. Access your web app in your favorite browser and enjoy this magnific Hello World!

Explanation

All routes are a mapping class with extends the primary Controller class. In a simple term, the class name in controller is ControllerFolderFilename.

class ControllerFolderFile extends Controller { }

The public function named index() is a default function to generate the page.

public function index() { }

Array $this->data receives in array format the variables to send to template, in this sample called variable with the string Hello World!.

In the last we finish with a simple $this->out(); to indicate the output and process template file. It's a automated mechanism to link this controller with the respective viewer.

The viewer in this sample is a twig template format (Twig page). ExacTI Phacil Framework permits to use varius PHP template engines, like Twig, Mustache, Dwoo and Smarty.

Config file Parameters

A simple description of default constants configurations in config.php file.

Constant	Type	Description	Required
HTTP_URL	string	Contains the URL for this WEB APP	Yes
HTTPS_URL	string	Same this HTTP_URL, but in SSL format
HTTP_IMAGE	string	The image URL
CDN	string	CDN URL to use for static content
DB_CONFIG	boolean	Permit to use configurations direct in database. Requires database instalattion. Values: true or false.	Yes
DEBUG	boolean	Indicate the debug mode.	Yes
$configs	array	No-SQL configs
DIR_APPLICATION	string	Absolute path to application folder	Yes
DIR_LOGS	string	Path to log folder
DIR_PUBLIC	string	Path to the public folder. This directory is a directory to configure in your HTTP server.	Yes
DIR_SYSTEM	string	System directory	Yes
DIR_IMAGE	string	Directory to store images used by Image library.
DIR_TEMPLATE	string	Directory with templates folder	Yes
DIR_CACHE	string	Directory to storage the generated caches.	Yes
DB_DRIVER	string	Driver to connect a database source
DB_HOSTNAME	string	Database host
DB_USERNAME	string	Username to connect a database
DB_PASSWORD	string	Database password
DB_DATABASE	string	Database name
SQL_CACHE	boolean	Use the SQL Select cache system

Template Engines Support

This framework supports this PHP templates engines:

• TPL (basic template with PHP and HTML);
• Twig;
• Mustache;
• Dwoo;
• Smarty.

To use a determined template engine, just create a file with name of engine in extension, for sample, if you like to use a Twig, the template file is demo.twig, if desire the Mustache template, use demo.mustache extension file. The ExacTI Phacil Framework allows to use varius template engines in the same project.

Easy made functions

This framework is very focused in agile, secutiry and reutilizable code in PHP. Contains a very utily functions we see in the next section.

Database

To execute a query:

$variable = $this->db->query("SELECT * FROM mundo");

Withou SQL Cache (if enabled):

$variable = $this->db->query("SELECT * FROM mundo", false);

Escape values to more security (no SQL injection issue): $this->db->escape($value)

To get this rows: $variable->rows;

Get one row: $variable->row;

Number of rows: $variable->num_rows;

Sample:

<?php 
class ModelDemoSample extends Model {
    public $data = array();

    public function dataSample ($code) {
  	  $variable = $this->db->query("SELECT * FROM settings WHERE code = '". $this->db->escape($code). "'");

  	  $this->data['rows'] = $variable->rows;
  	  $this->data['totalRecords'] = $variable->num_rows;

  	  return $this->data;
    }
}

Document easy made

Use the especial Document class to manipulate easily informations about your final HTML.

To call a document class, use $this->document inside Controller.

To add a CSS: $this->document->addStyle($href, $rel = 'stylesheet', $media = 'screen', $minify = true);

To add a JavaScript: $this->document->addScript($script, $sort = '0', $minify = true);

Facebook Metatag: $this->document->addFBMeta($property, $content = '');

Document HTML Title: $this->document->setTitle($title);

Page description: $this->document->setDescription($description);

Sample:

<?php
class ControllerCommonHome extends Controller {
    public function index() {
 	   $this->document->addStyle('pipoca.css');
    }
}

Classes and functions

This framework have a lot of utilities and accepts much more in system folder with autoload format.

To show all classes

Execute a Classes() class in one Controller.

$cla = new Classes();

var_dump($cla->classes());

To show all classes and functions registereds

Execute a Classes() class and call functions() in one Controller.

$cla = new Classes('HTML');

var_dump($cla->functions());

Note: The HTML parameter is the output in HTML style. Is optional.

Loaders

In this framework, loaders is a simple way to get resources to use in your PHP code. Is very intuitive and requirew few steps.

For sample, to load a model, is just $this->load->model('folder/file'); and to use is $this->model_folder_file->object();, like this sample:

<?php
class ControllerSampleUse extends Controller {
    public function index() {
   	 $this->load->model('data/json');
   	 $this->data['totalData'] = $this->model_data_json->total();

   	 $this->out();
    }
}

You can use loaders to:

• Controllers;
• Models;
• Librarys;
• Configs;
• Databases;
• Languages.

Models

This framework is totally MVC (Model, View and Controller) based. The models is just like the controllers and uses the same structure, with a different folder.

To create a model, put in the models folder a directory and file with the code.

<?php

class ModelFolderFile extends Model {
    public function SayMyName() {
   	 return "Heisenberg";
    }
}

Constructs

In same cases we need to add a __construct in a class to better code practices. To call a constructs in controllers and models, use:

public function __construct($registry)
  {
  	parent::__construct($registry);
  	
  	// YOUR CODE HERE AFTER THIS LINE!
  }

Requests and Sessions

To use a magic request system, you just need to call a $this->request method. For sample, to obtain a POST value, use $this->request->post['field'] to get the post value with security. For a $_SERVER predefined variables, use $this->request->server['VALUE'] and $this->request->get() for $_GET values. The advantages to use this requests instead the predefined variables of PHP is more the more security, upgradable and unicode values.

Sessions

Sessions is a little different method, you can define and use with $this->session->data['name'].

Special controller parameters

Parameter	Type	Description
$this->template	string	Specify manualy the path to template
$this->twig	array	Create Twig aditional functions. Eg.: $this->twig = array('base64' => function($str) { return base64_encode($str); });
$this->children	array	Load in variable other renders of web app. Th childrens footer and header is default loaded when uses $this->out() output. To load without this defaults childrens, use $this->out(false).
$this->redirect($url)	string	Create a header to redirect to another page.

Routes

The ExacTI Phacil Framework is a simple router base to create a simple and consistent web navigation.

Withou SEO URL, we invoke a page with route get parameter when contains a scheme folder/file of controller, like this: http://example.com/index.php?route=folder/file.

In a sample case, we have this controller:

<?php
class ControllerFolderFile extends Controller {
    public function index() {
   	 echo "Index";
    }
    public function another() {
   	 echo $this->foo($this->request->get['p']);
    }
    private function foo($parameter) {
   	 return ($parameter != 0) ? "another" : "other";
    }
}

If we access index.php?route=folder/file we see the "Index" message. But, like a tree, if we access index.php?route=folder/file/another obtains the another function code, with "other" message.

Multiple Get parameters is simple and we can define normaly, eg.: index.php?route=folder/file/another&p=2 to print "another" message.

Private and protected functions is only for internal use, if we tried to access index.php?route=folder/file/foo, the framework return 404 HTTP error.

SEO URL

If you need a beautiful URL for SEO or other optimizations, you can use the url_alias database table. Is very simple and "translate" the routes in URL.

Imagine this SQL table called url_alias:

url_alias_id	query	get	keyword
1	contact/contato		contact
2	webservice/sitemap		sitemap

With the url_alias, the access to route http://example.com/index.php?route=contact/contato and http://example.com/contact is the same!(and very prety!).

Links

We have a function to create a strict and dinamic links automatic: $this->url->link($route, $args = '', $connection = 'NONSSL'). Is a simple function to generate internal links with correct URL encode.

In sample of this table above, if we have this code:

echo $this->url->link('contact/contato');

We get this URL in output: http://example.com/contact

But if you don't have a route in url_alias table, returns the complete route.

echo $this->url->link('catalog/products');

Return this URL in output: http://example.com/index.php?route=catalog/products

With extra GET paramethers:

$fields = array('foo' => 'bar');
echo $this->url->link('contact/contato', $fields);
echo $this->url->link('contact/contato/place', $fields);

We get this URL in output with GET paramethers:

http://example.com/contact?foo=bar

http://example.com/index.php?route=contact/contato/place&foo=bar

License

This project is manteined for ExacTI IT Solutions with GPLv3 license.