WebFiori Framework Tutorials - 1 - Introduction

WebFiori Framework Version 2.0.0

Hello everyone. Today is a big day for me. The reason for that is version 2.0.0 of WebFiori Framework was just released.

This release is considered as a major release since it is a whole refactor of version 1.0 of the framework. For more information about this release, you can check GitHub Repo of the project.

If you don't know what is WebFiori framework, it is a web development framework which was built in top of PHP language. The framework makes it easy for web developers to build simple web applications. For more information about the project, chech this page: https://webfiori.com/learn/introduction

Apache NetBeans IDE Setup for PHP Development #4

The forth video on a set of videos that explains how to setup Apache NetBeans IDE for PHP development.

Apache NetBeans IDE Setup for PHP Development #3

The third video on a set of videos that explains how to setup Apache NetBeans IDE for PHP development.

Apache NetBeans IDE Setup for PHP Development #2

The second video on a set of videos that explains how to setup Apache NetBeans IDE for PHP development.

Apache NetBeans IDE Setup for PHP Development #1

The first video on a set of videos that explains how to setup Apache NetBeans IDE for PHP development.

What I Have Learned Today: Using PHP Through Command Line Interface (CLI)

One of the things that I was interested in is how some PHP frameworks can be used from command line interface to execute PHP code and commands. Some of the tools that I have used are composer and PHPUnit and both can be used from command line. For that reason, I started to think about adding this feature to WebFiori Framework.

After few attempts and failures, I managed to add basic support for running the framework from command line. You can see from the following picture that running the framework from CMD is working without problems.

There are few things that I had to do in order to add support for running the framework from the command line. The things are the following:

• Checking if main script file is loaded using command line using the method php_sapi_name().
• Initializing some $_SERVER and $_ENV variables as they are not initialized if PHP script is accessed through command line.
• Getting command line arguments using the constant $_SERVER['argv'].

For the last two steps, I created new class to handle the two tasks. The name of the class is CLI.php After doing that, I have only changed few lines of code in main class to redirect user to use CLI as shown in the following picture.

WebFiori, New Web Development Framework

WebFiori Framework is new web development framework which was built in top of PHP scripting language. It was designed from scratch to provide the developer with needed tools to setup new website or create a very complex web application using minimum tools.

Basic features (Taken from official website):

• Theming and the ability to create multiple UIs for the same web page using any CSS or JavaScript framework.
• Support for routing that makes the ability of creating search-engine-friendly links an easy task.
• Creation of web APIs that supports JSON, data filtering and validation.
• Basic support for MySQL schema and query building.
• Lightweight. The total size of framework core files is less than 3 megabytes.
• Access management by assigning system user a set of privileges.
• The ability to create and manage multiple sessions at once.
• Support for creating and sending nice-looking emails in a simple way by using SMTP protocol.
• Autoloading of user defined classes.
• The ability to create automatic tasks and let them run in specific time using CRON.
• Support for logging of system events.
• Well-defined file upload and file handling sub-system.

The project is currently hosted in my personal website and it can be accessed through the URL: https://programmingacademia.com/webfiori . You can find more information about the project there.

Another thing is that the project is open source and is licensed under MIT license. You can grab the source code of the framework from my GitHub repo at https://github.com/usernane/webfiori.

Your Contribution is Appreciated

One of the things that I need your help in is your feedback (Negative or positive). You can help me by trying the framework your self and provide me with your feedback. You check https://programmingacademia.com/webfiori/learn to get started.

Another thing is that you might find hundreds of issues in the source code of the framework since I'm not an experienced PHP developer (Design issues, Security issues, Bad practices, etc...). What you can possibly do is to review the source code and report any issue that you might find regarding how things are done.

Also, if you need any help regarding how to use the framework or you are just interested, please join telegram group using the following link: https://t.me/webfiori

Thank you for your time.

JsonX APIs

Note: This library is now part of WebFiori Framework. Updated API Docs can be found at https://programmingacademia.com/webfiori/docs/jsonx/.

This page contain APIs descriptions of the library JsonX, A library that can be used to create JSON strings in PHP. The library consist of two files only, JsonX.php and JsonI.php. The first file contains the class 'JsonX' which is the core component. The other file contains an interface which can be implemented by other classes to create a custom JSON strings.

Basic Usage Example

The next lines of code shows how to use the library in very simple way.

<?php
include 'JsonX.php';
include 'JsonI.php';

//create new instance of JsonX
$json = new JsonX();

//add attributes to JSON object.
$json->add('a-string', 'This is a string.');
$json->add('a-number', 44);
$json->add('a-boolean', FALSE);
$json->add('null-value', NULL);

//send Json object as response
header('content-type:application/json');
echo $json;

• Class JsonX Constants
  • TYPES
  • SPECIAL_CHARS
  • SPECIAL_CHARS_ESC
• Class JsonX Functions
  • add()
  • addNumber()
  • addBoolean()
  • addString()
  • addArray()
  • addObject()
  • get()
  • hasKey()
  • escapeJSONSpecialChars()
• Interface JsonI Functions
  • toJSON()

Class JsonX

Version: 1.2

Author: Ibrahim BinAlshikh

const TYPES

• Type: Array
• Description: An array of supported JOSN data types. The array has 7 values: 'integer', 'string', 'double', 'boolean', 'NULL' and 'object'.
• Since: 1.0

const SPECIAL_CHARS

• Type: Array
• Description: An array which contains JSON special characters that can be a part of a string. The array has the following characters: \\, /, ", \t, \r, \n and \f.
• Since: 1.0

const SPECIAL_CHARS_ESC

'

• Type: Array
• Description: An array which contains escaped JSON special characters that can be a part of a string.
• Since: 1.0

public function add($key, $value, $options=array())

Adds a new value to include in the generated JSON string.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value".
• $value:
  • Type: mixed
  • Description: The value of the key. It can be an integer, a double, a string, an array or an object. If NULL is given, the method will set the value at the given key to 'null'.
• $options: [Optional]
  • Type: Array
  • Description: An associative array of options. Currently, the array has the following options:
    • string-as-boolean: A boolean value. If set to TRUE and the given string represents a boolean value (like 'yes' or 'no'), the string will be added as a boolean value. Default is FALSE.
    • array-as-object: A boolean value. If set to TRUE, the array will be added as an object. Default is FALSE.

Returns:

• boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.1

public function addNumber($key, $value)

Adds a number to include in the generated JSON string.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
• $value:
  • Type: integer | double
  • Description: The number which will be added. Note that if the given number is INF or NAN, The method will add them as a string.

Returns:

• boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addBoolean($key, $value)

Adds a boolean value (true or false) to include in the generated JSON string.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
• $value: [Optional]
  • Type: boolean
  • Description: TRUE or FALSE. If not specified, The default will be TRUE.

Returns:

• boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addString($key, $value, $asBoolean)

Adds a string to include in the generated JSON string.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
• $value:
  • Type: string
  • Description: The value of the string. Note that if the given string is one of the following and the parameter $asBoolean is set to TRUE, it will be converted into boolean (case insensitive).
    • yes => TRUE
    • no => FALSE
    • y => TRUE
    • n => FALSE
    • t => TRUE
    • f => FALSE
    • true => TRUE
    • false => FALSE
    • on => TRUE
    • off => FALSE
    • ok => TRUE
• $asBoolean: [Optional]
  • Type: boolean
  • Description: If set to TRUE and the string represents a boolean value, then the string will be added as a boolean. Default is FALSE.

Returns:

• boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addArray($key, $value, $asObject)

Adds an array to include in the generated JSON string.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value"
• $value:
  • Type: Array
  • Description: The array that will be added. If the given array is indexed array, all values will be added as single entity (e.g. [1, 2, 3]). If the array is associative, the values of the array will be added as objects.
• $asObject: [Optional]
  • Type:
  • Description: If this parameter is set to TRUE, the array will be added as an object in JSON string. Default is FALSE.

Returns:

• boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function addObject($key, $value)

Adds a PHP object to include in the generated JSON string.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the given value will be stored in. Usually called the "name" of the "value">
• $value:
  • Type: JsonI | Object
  • Description: The parameter can be a PHP object or an object that implements the interface 'JsonI'. If the object does not implement the interface 'JsonI', then the function will try to extract object information based on its public functions and the generated JSON will be on the format {"prop-0":"something","prop-1":"something else","prop-n":"xxx"}.

Returns:

• boolean: TRUE if the value is set. If the given value or key is invalid, the function will return FALSE.

Since: 1.0

public function get($key)

Returns a string that represents the value at the given key.

Parameters:

• $key:
  • Type: string
  • Description: The name of the attribute that the value is stored in. Usually called the "name" of the "value"

Returns:

• string | NULL: A string that represents the value at the given key. If the key does not exists, the function will return NULL.

Since: 1.2

public function hasKey($key)

Checks if a key is exist or not.

Parameters:

• $key:
  • Type: string
  • Description: The name of the key. Usually called the "name".

Returns:

• boolean: The function will return TRUE if the key exists. FALSE if not.

Since: 1.2

public static function escapeJSONSpecialChars($str)

Escape JSON special characters from a string.

Parameters:

• $str:
  • Type: string
  • Description: A value of one of JSON object properties. If it is NULL,the method will return empty string.

Returns:

• string: The same string with JSON special characters escaped.

Since: 1.0

Interface JsonI

Version: 1.0

Author: Ibrahim BinAlshikh

public function toJSON()

This function can be implemented by any class that will be added as an attribute to any JsonX instance.It is used to customize the generated JSON string.

Parameters:

• NONE

Returns:

• JsonX: An instance of JsonX

Since: 1.0

JavaScript: AJAX Request

Introduction

In the previous post, we have talked about the basic idea behind AJAX. Before we continue with how to create a fully functional AJAX request, we need to understand some properties and methods of the XMLHttpRequest class. At minimum, we have to worry about the following:
 

• The property XMLHttpRequest.onreadystatechange
• The method XMLHttpRequest.open()
• The method XMLHttpRequest.send()

There are other properties that we will use when we need them.

The property "XMLHttpRequest.onreadystatechange"

The value of this property is set to a function. The function will handle the event that will be fired when the value of the property "XMLHttpRequest.readyState" is changed. There are 5 values that the property can have. We will come to them later when we start talking about handling response.

The method "XMLHttpRequest.open()"

The method "open()" is used to initialize the request. This method can accept 4 parameters at most, two of them is a must and the others are optional.

//The first two must be provided
XMLHttpRequest.open(requestMethod,requestedURL,userName,password);

The request method is a string. The most common values of this field are the following:

Method	When to use
GET	Used to retrieve data such as files
POST	This method is used to submit data to the server. Usually it causes some changes on the state of the server.
HEAD	We use this method to get the response headers only.

The method "XMLHttpRequest.send()"

This method is used to send the request. It takes one parameter which is the content that we would like to send on the body of the request. We only need to provide the body content only if we will use the method 'POST'.

AJAX Request Example 1

Suppose that the URL of our server is "https://mysite.com" and suppose that on the server we have the directory "/posts" and inside that directory we have a file named "getPost.php". The file "getPost.php" will return a post based on its ID. The ID must be provided as query string. What we will do is to build a method that has the ID of the post as parameter. The method then display the result of the response.

function getPost(id){
    //get the post that has the given id
    var query = '?id='+id;
    var url = 'https://mysite.com/posts/getPost.php';
    var xmlhttpReq = new XMLHttpRequest();
    xmlhttpReq.open('GET', url+query, true);
    xmlhttpReq.onreadystatechange = function () {
    //display response result. we will do that on the next post
    }
xmlhttpReq.send();
}

Since we are using PHP, the file "getPost.php" might have something like this:

if($SERVER['REQUEST_METHOD'] == 'GET'){
    if(isset($_GET['id'])){
        $postID = $_GET['id'];
        //get the post from the database
        //and send it back using 'echo' command.
    }
    else{
        //the id parmeter is messing
        http_response_code(422);
    }
}
else{
    //method is not GET
    http_response_code(405);
}


AJAX Request Example 2

In this example, we want to implement a basic login system. We will be using the same URL in the previous example. But this time, we will be assume that we have another file. The file will be "login.php" that is located in the main directory of the server. Usually, the request method "POST" is used in such as situation. In this example, the username and password must be sent in the Request body since we are using "POST".

function login(username,password){
    var requestBody = 'username='+username+'&password='+password;
    var url = 'https://mysite.com/login.php';
    var xmlhttpReq = new XMLHttpRequest();
    xmlhttpReq.open('POST', url, true);
    //we must set this header to send data on the body
    xmlhttpReq.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    xmlhttpReq.onreadystatechange = function (){
        //display response result. we will do that on the next post
    }
    //sending the login string with the request body
    xmlhttpReq.send(requestBody);
}

The file "login.php" might have something like this:

if($SERVER['REQUEST_METHOD'] == 'POST'){
    if(isset($_POST['username'])){
        $username = $_POST['username'];
        if(isset($_POST['password'])){
            $password = $_POST['password'];
            //check database for the login info
        }
        else{
            //password is messing
            http_response_code(422);
        }
    }
    else{
        //Username is messing
        http_response_code(422);
    }
}
else{
    //method is not POST
    http_response_code(405);
}


In the next post, we will be learning how to handle the response that the server will give back after the request.