header

Ciro PHP Framework

Ciro is a MVC PHP Framework to kickstart projects rapidly, it's designed to be simple, configurable, modular, decoupled, extensible and lightweight to make it easier to build better and easily maintained PHP code.

Out of the box Ciro comes with :

Namespaced PSR-4 structure
Single Entry Point PHP App
Pretty Urls Support
Default Routes
Custom Routes
Views Layouts
Alerts & Flash Messages
Custom Error Pages
Exceptions & Errors Handler with logging
Database helper classes for Mysqli, PDO, and MongoDB
Composer's autoloading
for Views, default template comes with
- Bootstrap 4
- Jquery 3.2.1
- Font Awesome 5

Ciro comes with a template project with a simple authentication system to kickstart developing for you project or prototype.

Online example of the framework template project: https://ciro-framework.herokuapp.com

Index

Requirements
Kickstart Installation
Template Project
Documentation
License

Requirements

PHP 5.6 or greater.
- (PHP 7.0+ if you're using MongoDB helper class)
Apache Web Server or equivalent with mod rewrite support.

Kickstart Installation

Download Ciro PHP Framework
Download & install XAMPP with PHP 5.6+ (7.0+ Recommended) from Here.
Copy Ciro PHP Framework folder contents to C:\xampp\htdocs for windows or /Applications/XAMPP/xamppfiles/htdocs for mac.
OR Configure XAMPP's Apache's httpd.conf Directory root to Ciro's Directory, see instructions: Here.
Open XAMPP and start both Apache and Mysql.
Go to localhost and start developing!

To Use the pre-made Login/Register, and you're using SQL (not Mongo) you must create the database and tables in SQL.
- Go to http://localhost/phpmyadmin and execute the query in sql_database_script.sql that exists in the root directory.
To Use the pre-made Login/Register, and you want to be using MongoDB you must install mongodb extension and MongoDB PHP Library using composer, instructions Here. also replace Models/UserRepository.php with Models\.disabled.mongo.userrepository.class.php to use the MongoDB version.

Template Project

The Framework comes with a blank template project contains a Homepage and a simple extensible User's Register/Login/View with 3 variants of 'User Repository' depending on your Database and extension of choice.
- Mysqli version for MySql.
- PDO Version for PDO supported RDBMS(s).
- MongoDB version (php 7.0+).

All configurable via the config files.

Online preview of the framework template project: https://ciro-framework.herokuapp.com

homepage

Documentation

1- Project Structure

The Project Structure follows namespaced PSR-4 specifications.

+---Config              <- Contains Configurations Files.
+---Controllers         <- Contains a Dir for each Route each contains this Route's Controllers.  
+---Core                <- Contains Core Classes for the framework
+---Logs                <- Contains Logs created by the scripts (e.g Exception Handler logs)
+---Models              <- Contains Models (can be sub-directoried using namespaces using PSR-4 specs. 
+---Utilities           <- Contains Utility Classes. 
+---Vendor              <- Composer's Vendor Dir, contains autoloader code and third-party packeges.        
+---Views               <- Contains Views, a Dir for each route, each contains a Dir for each Controller.
|   +---_FullMessages     <- Contains Full Messages HTML designs.
|   +---_Layouts          <- Contains Layouts       
+---Webroot             <- Public Dir contains the single point of entry of the program, and all public assets.

2- Routing

2.1 Default Route

In Ciro a default URL route has the following structure:

http://example.io/{route}/{controller}/{action}/{param1?}/{param2?}/...

This url resolves to the method {action} of controller {controller} in namespace controllers/{route} so in PHP OOP notation corresponds to:

App\Controllers\{route}\{controller} -> {action}

In configuration Config/config.php, you can specify A 'default_route' so if a url doesn't contain a route, the program will route according to default route. by default the 'default_route' is 'Web'. So, a typical URL using default route will have the following structure:

http://example.io/{controller}/{action}/{param1?}/{param2?}/...

so in PHP OOP notation corresponds to:

App\Controllers\Web\{controller} -> {action}

Another example:

                                        for $id
http://example.io/{controller}/{action}/{param1}
http://example.io/  Product   /  View  /  6800

if the Url doesn't specify {action}, the program to route to the 'default_action' specified in 'Config/config.php'.
if the Url doesn't specify {controller}, the program to route to the 'default_controller' specified in 'Config/config.php'.
to add a new route and access it using default routing, you must add it in Config/config.php Routing table.

Passing Params to Controllers

Given this url for example:

                                        for $id   $color
http://example.io/{controller}/{action}/{param1}/{param2}
http://example.io/  Product   /  View  /  6800  /  red

Params are accessible inside the Controller's method via $this -> params[0..*] array, for example $this->params[0] holds the value of {param1} in the url above.
Another way to access params inside the Controller's method is by adding arguments to the controller's method itself. using the same example above, if ProductController -> View is defined like this:
```
class ProductController extends WebController {
    public function view($id, $color = 'white'){
        /* controller's method code here */
    }
}
```

$id will have the value of {param1}, $color will have the value of {param2} and so on...

Notice that if {param2} wasn't in the URL, $color will use the default value specified, however if {param1} wasn't in the URL, the Program is going to render a 404: Not Found Message because $id has no default value specified in the controller's method.

2.2 Custom Routes

Custom Routes give you the possibility to specify a URL with a specific pattern that if matched the URL is routed to the specified {route}\{controller}::{action} with the proper specified params.
Custom Routes can be Enabled/Disabled in Config/config.php.

You can specify a custom route for every REST HTTP Verb e.g( GET, POST, PUT, DELETE, etc ) or specify a custom route for All possible HTTP verbs using:

// for GET requests
Route::get($uri, $route, $controller, $action);

// same for POST, PUT, DELETE, etc requests
Route::post(), Route::put(), Route::delete(), Route::patch(), Route::options();

// for ALL requests
Route::all();

Custom Routes are defined in /Config/routes.php.
```
Route::get('custom/route/{id}/{name}/{language?}','Web', 'Home', 'CustomRouteAction');
```
Any URL that matches custom/route/{id}/{name}/{language?} will be routed to: Route: Web Controller: Home Action: CustomRouteAction.

Passing params using custom routes:

Params should be surrounded by curly braces { name }, optional params should have a '?' at the end of their names { optinoalParam? }.
Params are accessible inside the Controller's method via $this -> params[0..*] array and are ordered respectively to the order of them in the URL.
- in the above example,$this -> param[0]corresponds to {id}, $this -> param[1] corresponds to {name}, etc
If Controller's method has params defined, params are passed to this method ordered respectively to the order of them in the URL.

A Controller's Method of a custom route should be defined as follows:

class HomeController extends WebController {
    public function CustomRouteAction($id, $name, $language = 'default'){
        /* controller's method code here */
    }
}

Note in the above example: {language?} is an optional param, optional params should have a '?' at the end of their names, and should have a default value in the Controller's method, otherwise if the param is missing, the program will render a 404: Not Found Message because an optional param was not given and has no default value.

General Pattern Routing:

When setting a custom route, you can put a variable param in the target route, controller or action to create a more 'general' custom route.

Example:

Route::get('custom/{var_controller}/pattern/{action}/{param1}','Web', '{var_controller}', '{action}');

Any URL that matches custom/{var_controller}/pattern/{action}/{param1}

will be routed to: Route: Web, **Controller: `{var_co

Ciro

Install / Use

README