uxie/uxie

Uxie a light MVC Framework

What is Uxie:

Uxie is a PHP MVC Framework., _(*1)

Features:

- Perfect MVC environment.

- Box (Command Line Tool).

- Deployable with docker.

- DataBase Migration (phinx).

- Security (secured against SQL injection, XSS, CSRF).

- IOC (Inversion of control) Container.

- Router (REST).

- Authentication.

- Middlewares.

- Mutual Templating Engines (Blade & Pug):

- ORM Model.

- Visitors Data Recorder.

- Request handler & validator.

- Automatic Exception handling.

- Errors / Exceptions logger.

- Built-in functions (Helpers).

- Multi langauge support.

Documentation:

Installing:

Using Composer:, _(*2)

  composer create-project uxie/uxie <path>

Using Docker:, _(*3)

  Docker-compose up --build

Routing:

All routes are defined in : App/Routes.php, _(*4)

Available Methods:

GET, POST, PUT, PATCH, DELETE, _(*5)

To use PUT, PATCH, DELETE methods your form method must be 'POST' inside the form you must put: <input type='hidden' name='_method' value="PUT'> csrf_method('PUT') will echo this automatically., _(*6)

Basic routes examples:

$route->get('', function() {
  view('index');
});
// passing variables
$route->get('user/{$name}', function($name) {
  view('welcom', ['name' => $name]);
});

$route->put('update', 'Controller@update');

$route->patch('update', 'Controller@update');

$route->delete('delete', 'Controller@delete');

Execute methods from a controller:

$route->post('test', 'Controller@method');

Resource method which contains: (index, create, store, show, edit, update and delete) same as Laravel.

$route->resource('user', 'UserController');

Add a collection of routes with a prefix:

$route->group('user', function($route) {
    $route->get('profile', function() {
        echo 'Profile';
    });
    $route->post('store', 'Controller@method');
});

Passing data via URL:

in routes file :, _(*7)

$route->get('profile/{$name}/update', 'Controller@update');

in Controller :, _(*8)

public function update($name)
{
    echo $name;
}

How to use $_POST values (this can apply to PUT PATCH DELETE methods also):

in routes file :, _(*9)

 $route->post('user/store', 'UserController@store');

in UserController.php :, _(*10)

...
use Request\Request as Request;
...
public function store(Request $request)
{
  $name = $request->name;
  // equivalent to $_POST['name'];
}

Authentication:

Authentication will validate your users login automatically, _(*11)

Login:

  use Authenticator\Auth;

  if (Auth::attempt(['table', 'name' => $inputName, 'password' => $inputPassword)) {
    echo 'success';
  }

  // in case of second field required to validate for example e-mail & user-name:

  if (Auth::attempt(['table', 'name' => $inputName, 'password' => $inputPassword, 'email' => $inputEmail])) {
    echo 'success';
  }

Check if user loged in:

  if (Auth::check())
  {
    echo 'success';
  }
  // in case you want to check a user value from database row:

  if (Auth::check(['name' => 'someone'])
  {
    echo " i'm someone";
  }

Logout a user:

  Auth::logout();

Hashing:

you need to hash a password before storing it in database, _(*12)

  $password = Auth::hash($password);

User data:

To access user data stored in database for example age, email or anything else :, _(*13)

  $email = Auth::user()->email;

Middlewares

to use middlewares you need to add middleware() method to your route call example:, _(*14)

$route->get('profile/user', 'controller@show')->middleware('MiddlewereTest');

you can add a late middleware just add true argument to middleware() method:, _(*15)

  $route->get('profile', 'controller@index')->middleware('MiddlewareTest, true);

All middlewares are defined in './Middlewares' folder., _(*16)

A middleware must contain a construct method:, _(*17)

namespace Middleware;

class Middlewaretest
{
    public function __construct()
    {
        echo 'test middleware';
    }
}

Middleware collections & short names:

To add a collection of middlewares or a short-name to a route you must define the collection in 'App/ServiceProviders/MiddlewaresProviders.php':, _(*18)

private $middlewaresProvider = [
        'auth' => 'authenticateUsers',
        'collection' => [
            'myMiddleware',
            'TestMiddleware',
            'OtherMiddleware',
        ];
    ];

To use collections and short names:, _(*19)

// 'auth' short name example:
$route->get('user', 'controller@method')->middleware('auth');

// 'collection' example:
$route->get('link', 'controller@method')->middleware('collection');

Security ( against SQL injection, XSS, CSRF):

SQL injection:

Uxie is secured against both first and second order sql injection attacks., _(*20)

XSS:

Both Uxie templating engine escape html+js when printing data., _(*21)

CSRF:

Uxie comes with built in feature that protect against CSRF when using ('POST','PATCH','PUT','DELETE') methods, So every form should contain: csrf_field(), _(*22)

Mutual Templating Engine (Blade & Pug):

Important Notes:

• All views must be inside 'App/Views' folder.

How to use it:

Use helper function view(string $view, array $variables):, _(*23)

view('YourView', ['data' => $data, 'name' => 'MyName']);

// To use Pug view use:
pugView(string $view, array $data);

// to use Blade view use:
bladeView(string $view, array $data);

How to Chose wich Templating engine to use:

To change Templating engine you should edit .env file, _(*24)

Engine = Blade
# or
Engine = Pug

IOC Container:

uxie comes with a IOC container that resolves all of your classes dependencies and their dependencies and so on to use it :, _(*25)

// instead of this:
$myClass = new \Namespace\MyClass( new Class1(), new Class2( new Class3()));

// you can use this:
$myClass = container()->build('\Namespace\MyClass');

// if you have some arguments
// instead of this:
$myClass = new \Namespace\MyClass('argument1', 'argument2');

// use this
container()->build('\Namespace\Myclass', ['argument1', 'argument2']);

container()->get('MyClass')->someMethod();
// or this:
contaienr()->MyClass->someMethod();

IOC Service Provider:

Service provider located in App/Services.php It contains aliases and sevices that should be loaded when the application start:, _(*26)

        'ServiceLocators' => [
            'Router'     => \Router\Router::class,
            'Kernel'     => \Kernel\Kernel::class,
            'Compiler'   => \Kernel\Compiler\Compiler::class,
            'Middleware' => \App\Middleware\Middleware::class,
            'Dotenv'     => \Dotenv\Dotenv::class,
            'Auth'       => \Authenticator\Auth::class,
        ],

        'ServiceProviders' => [
            Jenssegers\Blade\Blade::class,
        ],

The global $container:

the container()function is global in the framework (can be used every where, it contains all the objects created by the IOC container),, _(*27)

container()->build('someclass');
container()->someClass->someMethod();

Uxie Model:

how to use it:, _(*28)

use Model/Model;

Insert data:, _(*29)

Model\table::insert([
  'value1' => $value1,
  'value2' => $value2,
])->save();

Retrieve data:, _(*30)

$data = Model\table::select()->where('name', '=', 'user')->limit(10)->get();

Retrieve single row:, _(*31)

$user = Model\table::find('name', 'MyName');

Soft delete : by default uxie migration add a softdelete column to the table softdelete method will change the value of softdelete column NOTE: select won't return any soft deleted rows, _(*32)

  Model\table::delete()->where('id' , '=', $id)->save();

to hard delete a row use hardDelete method. plenty of other methods such as limit(), orderBy(), groupBy(), count(), join, update and delete. simple example:, _(*33)

Model\table::select()->where('name', '=', 'user')->or('name', '=', 'other-user')->orderBy('date')->get();

Visitors Statistics:

It's a built-in middleware that record each user data and store it in a database table, Data such as ip, browser, os, PreviousUrl, CurrentUrl, date, and memory usage, _(*34)

Request & validator:

It's a built-in Request handler :, _(*35)

// you must add 'csrf_field()' to the HTML form to protect against CSRF
public function store(Request $request)
{
  echo $request->name;  
}

Validation:

Available validation methods : required(), length($min, $max), email(), isip(), isint(), isfloat(), url(), unique($model, $column), equals($input, $value) To validate POST inputs:, _(*36)

public function store(Request $request)
{
  $request->validate($request->name, 'Name Field')->required()->length(10, 30);
  $request->validate($request->email, 'Your Email')->required()->length(5, 40)->email();
  var_dump($request->getErrors());
}

the above example will return error messages in this form:, _(*37)

[
    [
        'Name Field Length must be bettwen 10 and 30',
        'Name Field is Required',
        'Your Email is not a valid email',
        'Your Email Length must be bettwen 5 and 40',
    ]
]

All Error messages teamplates are defined in multiple 'resources/languages/validation.php' to make theme so easy to modify., _(*38)

Exception handler:

Uxie comes with a built-in exceptions handler that will handle thrown exceptions / errors automatically., _(*39)

Errors logger:

All errors/exceptions thrown during runtime will be logged in log/All_errors.log with information about error such as file, line, code and error-Message., _(*40)

Helpers:

Helpers are functions available to use everywhere inside the framework such as view(), session(), redirect(), route(), url().
All function are listed in App/helpers., _(*41)

examples:, _(*42)

url('profile/user');
// returns http(s)://domain.com/profile/user

route('profile/user');
// redirect to http(s)://domain.com/profile/user

redirect('https://google.com');
// redirects to url entred (google.com)

view('my-view', ['variable' => $variable, 'name' => 'amine']);
// show a view with passed variables

session('id');
// returns $_SESSION['id']

session('id', '87669');
// set new session ( $_SESSION['id'] = '87669'

unsetSession('id');
// delete session

cookie('name', 'amine', time()+3600);
// set new cookie

cookie('name', 'amine');
//set new cookie without-time

cookie('name');
// returns cookie $_COOKIE['name'];

csrf_field();
// echo something like this <input type='hidden' name='_token' value='l2465431sd534sd'>

csrf_token();
// returns csrf token value

method_field(string $method);
// echo something like <input type='hidden' name='_method' value="$method'>

container();
// returns the global IOC container

Box (Command Line Tool):

Box is a command line tool to create Controllers, models & middlewares templates for example:, _(*43)

// to create a controller:
php box Controller TestC

// to create resourceful controller
php box Controller TestC -r

// to create a Model
php box Model TestC

// to create a Middleware
php box Middleware TestC

DataBase Migration:

All migration files located in '/Migrations', _(*44)

It's based on phinx migration to create a migration pass this command:, _(*45)

php phinx create MyMigration

To Migrate existing migration files:, _(*46)

php phinx migrate

Multi langauge support

• All languages files in 'resources/languages'
• By default uxie language is 'en' which means english

How to modify and add languages :

for example to edit validation messages you need to modify 'resources/languages/validations.php' ($$ represent the field name):, _(*47)

    'english' => [
        'length'   => '$$ Length must be bettwen $$ and $$',
        'required' => '$$ Is Required',
        'email'    => '$$ Must be a valide Email',
        'url'      => '$$ Must be a valide URL',
        'isint'    => '$$ Must be of type integer',
        'isfloat'  => '$$ Must be of type float',
        'isip'     => '$$ Must be a valide IP',
    ],

    'francais' => [
        'length'   => '$$ Doit etre entre $$ et $$',
        'required' => '$$ Est un Champ obligatoire',
        'email'    => '$$ Doit etre un e-mail',
        'url'      => '$$ Doit etre un URL valide',
        'isint'    => '$$ Doit etre de type entier',
        'isfloat'  => '$$ Doit etre de type float',
        'isip'     => '$$ Doit etre un IP valide',
    ],

How to set & get teh current language :

Uxie default language is 'english' To set a language use 'langauge(string $lang)' function example:, _(*48)

  // this will set language to 'francais'
  langauge('francais')

To get current language just use 'language()', _(*49)

  echo language();
  // should echo 'english'

how to use translation :

use translation(string $langFile) to get a language file content ($langFile is the file inside resources/langauges folder example:, _(*50)

    $translation = translation('Validations');
    var_dump($translation);
    // this should dispaly an array:
    // 'english'  => [ ....],
    // 'francais' => [ ....]