v1.1.0

Traillamp

A lightweight, easy to use, MVC Framework for Php

What's New in V1.1.0

• Better Url routing
• Support for additional request types
• Better error handling
• Robust Templating Engine
• Middlewares
• Additional Console Commands
• Support for all web servers
• Additional utilities
• Migration Schemas
• Flexible Models

Documentation

Installation

• Repository

Clone this directory using either git commands or download zip file

• Composer

Run the following command to install Traillamp via composer

    composer require etorojah/traillamp

Find the traillamp folder in the composer vendor folder
Move to final destination and rename.

Usage

For local development, Any server environment application like Xampp, Lamp or Laragon can run Traillamp.
First configure environment variables in app/env/.env file and then launch the application

.env file Parameters

• APP_KEY: A unique application identifier.
• APP_NAME: Your application/API name.
• APP_VERSION: Your application or API version.
• DATABASE_HOST: Your database connection host, defaults to localhost.
• DATABASE_USER: Your database connection username, default is root.
• DATABASE_PASSWORD: Your database connection password.
• DATABASE_NAME: The database name .
• ENCRYPTION_KEY: A random string used as key for encryption/decryption.
• MAIL_HOST: Mail host.
• MAIL_PORT: Port to be used to send mails from the application.
• MAIL_USERNAME: Mail username.
• MAIL_PASSWORD: Mail username password.
• MAIL_SENTFROM: Describes Mail sources e.g The Traillamp Support Desk.
• SUBDOMAIN: When true, development server is set up for subdomains or folder paths (https://example.com/traillamp/, https://traillamp.example.com, http://localhost/traillamp)

If you are deploying the contents directly to the server root(htdocs,www,public_html), set this value to false.

Folder structure

• console.exe: Run Traillamp console commands with the console executable.
• app: Contains all resources to be worked with.
• app/controllers/: Application controllers are found here.
• app/env/: .env file is located here. Holds environment variables.
• app/errors/: Holds the error log file for error logging and reference purposes.
• app/middlewares/: Application middlewares are found here.
• app/migrations/: Holds Database migration schema files.
• app/models/: Application Models are found here.
• app/public/: Contains files referenced in views such as style sheetes, scripts and other files.
• app/routes/: Holds all route and routing files.
• app/server/: Default application codebase is stored here. Editing any file here may break your application.
• app/utilities/: Holds Mailing utility files.
• app/views/: View subfolders and files are found here

Routing

• Basic Routing

All route files are found in app/routes/ directory.
A simple route without a middleware can be written as follows.

   $router::get("/", "WelcomeController@main");

The first parameter is the relative route path or url

The second parameter is the Controller name and the controller method separated by an @ sign.

Routes can also be called with function callbacks. Eg

     $router::get("/", function(){
        echo "ok";
    });

Routes can be called with Middleware specified for the route as the third parameter.
A simple route with a middleware can be written as follows.

   $router::get("/", "WelcomeController@main", "WelcomeMiddlewarre@main");

Or with a function using,

    $router::get("/", "WelcomeController@main", function(){
        echo "ok";
        return true;
    });

Remember to use the appropriate request method in your routes file.

• Parameterized routes

Routes with parameters are specified with the parameter names in curly brackets.

  $router::get("/about/{name}", "Controller@Main");

Thus visiting https://url/about/Etorojah will call the Main method in the Controller class with the name parameter assigned the value Etorojah.

Multiple parameters are supported. To get the values of the parameters simply use

    $this->parameter 

example

    echo $this->name;

in the Middleware or Controller method.

A maximum of 4 parameters can be passed to a callback function.

You should use Controller/Middleware class methods for routes with more than 4 parameters.

You can pass parameters to Controller/Middleware callback functions as shown below:

    $router::get("/about/{name}", "WelcomeController@main", function($name){
        echo $name;
        return true;
    });

• Supported Requests

• GET

• POST

• PUT

• PATCH

• HEAD

• DELETE

• Multiple route files

To create a route file, simply run the command below in the Traillamp console

    create router-file <filename>

example

    create router-file admin_routes

Controllers

Controllers form the backbone of your application. Controllers are found in the app/controllers/ directory.

All Controllers inherit the default class Controller's properties and methods in Controller.php file.

• Creating a Controller

To create a Controller, run the following command on the Traillamp console

    create controller <name>

example

    create controller Test

The above creates a Test.php Controller file in the app/controllers/ directory.

Controller file name and classnames must be the same.

You can now add the created controller to any route of your choice.

• Default Properties and Methods

The request property holds request parameters(array) for the given route and request type.
This can be used to get form values and other request parameters.

Example, using a route with a POST request which handles a form:

    $name = $this->request["name"];

The method property holds the request type which may be useful in a code block.
Example

    $name = $this->method;
    //returns POST for a POST request method etc

The files property holds the files sent as a request parameter to that route.
Example

    $file = $this->files["photo"];
    

As shown earlier, route parameters can also be gotten using $this->parameter in controllers and middlewares.

• Inherited Methods

Inherited methods can be accessed from any Controller which extends the Parent Controller class.

They are listed below:

Rendering a View: view(view, parameters)

To render a view, use the inherited class method view which carries two parameters,

• view: string, name of the view(without file extension) .

• parameters: array, values to pass to view templating engine.

The 'parameters' parameter is optional.
Example:

• Without parameters:

    $this->view("welcome");

    //subfolder view
    $this->view("includes.header");

The above renders a view welcome.lamp found in the app/views directory and header.lamp found in app/views/includes/ subdirectory.

• With parameters

    $this->view("profile", ["name" => "John", "email" => "john@site.io"]);
    

The parameters are passed to the templating engine and can be used in the view file.

Redirects: redirect(route)

To redirect to another route, use the inherited class method redirect which carries one parameter,

• route: string, relative valid url route.
  Example

    $this->redirect("/about/me");
    

Encryption: encrypt(text)

To encrypt plain text, use the inherited class method encrypt which carries one parameter,

• text: string, lain text to encrypt.
  Example

    $hash = $this->encrypt("I am Batman");
    echo $hash;
   

Decryption: decrypt(hash)

To encrypt plain text, use the inherited class method decrypt which carries one parameter,

• text: string, lain text to encrypt
  Example

    $hash = $this->encrypt("I am Batman");
    $text = $this->decrypt($hash);
    echo $text;
    //returns I am Batman
    

Remember to set environment variable, ENCRYPTION_KEY

Sending Mails: sendMail(email, subject, message)

To send mails, use the inherited class method sendMail which carries three parameters,

• email: string, valid email address.
• subject: string, subject of the message.
• message: string, message body.
  Example

    sendMail("john@site.io", "Greetings", "Hello to you");

Remember to set all mail environment variables.

Load Models: loadModel(model)

To load and get database model results, use the inherited class method loadModel which carries one parameter,

• model, string, in the format Class@method
  Example

    $result = loadModel('Users@get_users');

Remember to always return model results in model methods.

Middlewares

Middlewares are found in the app/middlewares/ directory.

All middlewares inherit the default Middleware class methods.
Middlewares can be used for authentication and much more

• Creating Middlewares

To create a Middleware, run the following command on the Traillamp console

    create middleware <name>

example

    create middleware Test

The above creates a Test.php Middleware file in the app/middlewares/ directory.

Middlewares file name and classnames must be the same.

You can now add the created middleware to any route of your choice.

• Default Properties and Methods

Middlewares have same default properties as those in Controllers(See Controllers above).

• Inherited Methods

Inherited methods can be accessed from any Middleware which extends the Parent Middleware class.

Middlewares h...