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

Storing Files in Server. File System or Database?

When me and my teammates were building our senior project, we needed to store files in the server. The easiest option for us was to keep the files in server file system and add a link to each file in the database. After graduation, I came across a new concept in database management which is the BLOB. According to MySQL documentation, BLOB stands for Binary Large Object. It is a datatype that is used to store a variable amount of data. Many database administrators use it to store resources files like images or small videos. The reason that I had to learn about the blob is that one of the requirements of developing a web application is to store files in the database rather than using file system.

After a while, one question popped in my mind. Which of the two is better to use? Storing files in server ‘s file system or storing them in the database? As usual, Googling is the best way to find answers for many questions. After searching and reading, I found that many database administrators store files in the database. And some uses file system. This post will go through the two approaches and gives the advantages and the disadvantages of using one of the two.

Storing Files in File System, The Advantages

Speed

If one cares about the speed, file system is the option to go with. The speed of serving multiple files using file system is faster according to many. Also, the speed of creating backups of the files will be much faster than creating a backup of the files while they are stored in the database.

Portability

Using file system to store files will help in portability. This means that if the application will migrate to use different database management system, it will be easy to move the files without any compatibility issues since the database will have only file reference. By storing files in database, the database management system might have an additional layer that wrap the file or alter its structure.

Storing Files in File System, The Disadvantages:

Backup and Recovery

If you are using file system to store files, you will have to create two backups, one for the files in the file system and one for the database. Same thing applies to recovering data. In addition to that, many database management systems come with a utility to create backups automatically. While in file systems, there are no such tool in many cases.

Reference Structure

Usually, files in the server must be accessed using some Kind of a reference if they stored in file system (Usually a URL). If a file or a directory is moved to somewhere else, the structure of the reference will change for sure. In this case, the reference to many files must be updated in the database which might take some time.

Storing Files in Database, The Advantages:

Integrity

One of the biggest advantages is data integrity. This means that any data needed by the application can be accessed from only one place. Also, this means that the information that is related to each other will be in one place. For example, if a company needs to store the pictures of its employees, they will be in the same record of employee information.

Easy to Manage

Since files are in the database, most likely that the management will be performed through the application that will use the files.

Storing Files in Database, The Disadvantages:

Performance

One issue of storing files in database is performance. This issue can be seen when the application needs to fetch many resources from the database. Also, it can be noticed while creating a backup of the database.

No FTP Access

Some prefer to use file system over database storage for this reason. They prefer to mange files using FTP clients instead of using application logic to add, update or remove files.

Configuration

If anyone plan to store very large files in database, sure he might struggle with modifying many settings in the server and the database management system. Myself, I had many issues in building one web application. The files that I was trying to store are video files of size 20 to 30 megabytes in MySQL server using Apache Server with PHP. The first issue was PHP’s upload limit. The second was the global variable max_allowed_packet. I had to update the settings of both till I was able to upload files.

My Opinion

Simply, there is no best option. It depends on your needs. If you thrive for speed and you have very large files to store, go with storing files in file system. For small files (Around 1 to 5 Megabytes), It would be better to go with storing files in a database. There might be other factors that can affect the final decision. So, before deciding, do your homework then select the option that suits your needs.

References:

Most of the information in this page are collected from the following websites. The answers are provided by many people who had different situations in storing files in a server. You can go and read more if you like.

• Stack Exchange: Is it better to store images in a BLOB or just the URL?
• Stack Exchange: Storing large files (~1GB) in MySQL
• Stack Exchange: Is it a bad practice to store large files (10 MB) in a database?

The Basics of Prolog Programming Language

Prolog is a logic programming language that is based on facts and rules. The idea is to create a set of facts related to specific domain. After that, we create rules that can be used to answer questions (or queries). For example, we may create a facts that can be used to identify a human if he is a man or a woman. In top of that, we can add more facts to state that this human is a father or a mother of another human. Once we have the given facts, we can create rules. For example, we can define a rule that can be used to find  the father of another human.


In this post, we will learn the basics of Prolog language in the simplest way. For this purpose, we will be using an online editor that can be used to write Prolog code and test it. The tool is called SWISH and can be fount at http://swish.swi-prolog.org/.

When we open the link, we will see that the page has 3 parts, one for creating new file, one for the output and one for asking questions.

The Layout of The Tool

To start writing Prolog code, simply click 'Program' and the code editor will appear.

Prolog Facts

In order to create Prolog rules, first we have to provide some facts. Suppose that we have 5 humans, one has the name 'john', another one has the name 'sara', another one has the name 'ali' and one has the name 'paul' and the last one with the name 'hannah'. The first facts that we are going to write is to state that a human can be a man or a woman. We can till from the names that 'john' is a man and 'sara' is a woman. Writing such facts in Prolog can be done as follows:


man(john).
man(ali).
man(paul).
woman(sara).
woman(hannah).



In Prolog, a fact is written as follows


fact_name(fact_attrs...).


Every fact we write in Prolog must end with a 'dot', and each fact can have one or more parameters (or attributes). Now that we know how to write facts, let's add more facts to our program. Let's say that 'john' is a father of 'ali', 'paul' and 'hannah'. Also let's say that 'sara' is the mother of 'ali', 'paul' and 'hannah'.


man(john).
man(ali).
man(paul).
woman(sara).
woman(hannah).
father(john,ali).
father(john,paul).
father(john,hannah).
mother(sara,ali).
mother(sara,paul).
mother(sara,hannah).



Once we have the given facts, we can ask questions about them and get answers. For example, we can ask the question 'Is john a man?'. Another question we could ask is 'Who is the mother of ali?'. A question in Prolog is called "query". In the next section, we will learn how to ask questions in Prolog.

Prolog Queries

One of the simplest queries in Prolog are the queries that are applied to the facts. The result of such queries will be either "true" or "false" if all the attributes of the query are known. For example, the result of running a query in one of the first 5 facts with one of the 5 names will be either "true" or "false".

In the example that we will see, we want to know if a person is a man or not. Prolog query has the following basic form: "?- rule_or_fact(vars...)". It is possible to construct more complex queries but we will do it later. For now, let's focus at the basics. The "?-" part is provided by the editor by default. All what we have to do is to write the other part.

In SWISH, we write the query in the place where it says " Your query goes here ...". After writing the query, All what we have to do is to click "run" and the result will appear. Let's give it a try.

As we can see, "ali" is a man since we got "true". Now we want to try something else. Suppose that we would like to get All women. To do that, we have to learn about new concept in Prolog which is variables.

Prolog Variables

A variable in Prolog can be used to answer queries. Variables are passed as an arguments to rules and facts to get specific values. Any parameter that starts with a capital letter is considered as a variable. For example, if we say 'woman(Sara)', 'Sara' is now a variable not an attribute. The  final value of the variable is based on the provided facts and rules. Now, to get all women, we pass a variable to the fact 'woman()'. Prolog will set the value of that variable to the name of the woman.

 As we can see, we have got our first woman. To get the rest, all what we have to do is to click "Next" till the execution is finished.

Now let's try something new. Suppose that we would like to know who is the father of 'ali'. To ask such as query, we write it as 'father(X, ali)'. In this case, 'X' will be equal to the father of 'ali'.

Suppose that we have a person that has unknown father. What will be the value of 'X' in this case? Let's try it. To do that, we will add new man called 'ibrahim' and try to find his father.

Simply we got 'false'. Whenever we try to apply a rule that does not exist, we will get 'false'. Also if we try the rule with a name that does not exist, we will get false. For example, if we try 'father(X, dania)', this will also give false.

New Music Instrumental Uploaded

One of the hings that I enjoy doing in my free time is to compose music using FL Studio 🎶. It is very powerful tool that can be used to create any type of music.

In the last few years (Since I joined KFUPM), I was learning how to use it since music composition is one of my hobbies. The next musical instrumental was composed by me in 2014. It is not that perfect but the final result was good enough for me.

Enjoy listening 😁. use your headsets for better result.

Every one month or two, I will try to upload one instrumental from the ones that I have completed since I started learning FL Studio till today. By the way, I'm still learning 🙂.

Also feel free to listen to the ones that has been already uploaded. I will be more than happy if you give me your feedback on them.