phpFoX

Classes

We will now go over the most used classes. We have listed the classes in order of its importance and by the frequency it is used.

Our main class is phpfox.class.php and can be found in the lib folder:

/include/library/phpfox/phpfox/

This class holds only static methods and is the most used class as it is what we use to connect to all libraries and modules. Below you will find the most common methods we use.

run()

We execute the script using the static method run(). If you check the /index.php file you will find the following:

Phpfox::run();

This calls the run() method and this is where all the magic happens.

getLib()

We discussed this method a little earlier and it is what we use to call other libraries.

getService()

We use this method to call a module service. More information regarding what a module service is and does will be mentioned later on. For the time being the method to call them is as follows:

Phpfox::getService('blog');

This would then require the following class and initiate the object

/module/blog/include/service/blog.class.php

To call a method from that class you could do:

Phpfox::getService('blog')->getBlogs();

This will then call the getBlogs() method. However if you are in a for loop or you plan to use the object more then once it might be a good idea to do the following:

$oServiceBlog = Phpfox::getService('blog');
$oServiceBlog->getBlogs();
$oServiceBlog->displayBlogs();

You may noticed we created the variable $oServiceBlog. It is important to prefix this variable with $oService so other developers know that this variable is an object and it is part of a service class. The variable ended with Blog and this will be easy to understand that the service class was blog.

If you were to get another class within the blog service folder you could do the following

Phpfox::getService('blog.process');

This would then require the following class and initiate the object

/module/blog/include/service/process.class.php

/module/blog/include/service/process/process.class.php

Similar to how libs get included the script will try to find the correct service file for you. Remember to name the variable connected with the service with the same name of the service being called. So with the above example the variable should be $oServiceBlogProcess.

getT()

It is the method used to get a database table name with the prefix specifically used for a site. It is very important to use this method with all database interactions which require the table name. You must use this method as sites have different prefixes and if you use the default prefix or none at all when you develop, this will cause severe problems for those that will use your module in the future. This method only has one parameter and that is the name of the database table. Here is an example of how it is used:

Phpfox::getLib('phpfox.database')->select('user_name')
       ->from(Phpfox::getT('user'))
       ->execute('getRows');

As you can see from the query above we used this method to get the table name user.

getUserId()

This method will retrieve the user_id for the current user that is logged in. This is useful when inserting or updating data for a specific user as many tables require the users user_id, which is what connects many tables to the user table. An example is:

Phpfox::getLib('phpfox.database')->update(Phpfox::getT('user'), array('email' => $aVals['email']), 'user_id = ' . Phpfox::getUserId());

This database query will update the users email and it does a check on the user_id, which you can see at the end. This method does not have any parameters and it will return 0 if a user is not logged in.

getUserBy()

This method retrieve specific data for the user that is logged in. Much like the getUserId() method, this method uses the first and only parameter to return the field we need. The supported fields that are returned are session_hash, id_hash, captcha_hash, user_id, server_id, user_id, user_name, user_image, password, password_salt, user_group_id and hide_tip. There are many more fields that could be returned from the user table, however these are the only ones we need on every page. So if we wanted to get the user name for the user that is logged in we could do the following:

Phpfox::getUserBy('user_name');

This will then return their user name.

isUser()

This is useful if you are creating a page that only allows members access to it. If for example you have created a new page and you only want members to view this page you could add the following:

if (!Phpfox::isUser())
{
	exit('Need to be logged in!');
}

If a user is not logged in the script will exit and output the following on a blank white page:

Need to be logged in!

If you have properly created a phpFox controller, which you will learn shortly:

if (!Phpfox::isUser())
{
	return Phpfox_Error::display('Need to be logged in!');
}

This will then use the phpFox template and display the message on the site instead of a blank white page. These 2 options are good but the best way to exit a controller that does not allow access to guests is to simply send them to the login page, which will also automatically redirect them back to the last page they visited thus making it a lot more user friendly. In order to do this you can add this instead:

Phpfox::isUser(true);

You may have noticed that this method did not require an if statement and was only one line of code. We simply used the first parameter, which when set to true (bool) it will redirect the user if they are not logged in.

getUserParam()

We have two types of settings that control how many of the features function. Some of these settings are global and anything changed from those settings will effect all users, however there is another setting group which controls settings for a specific user group. Since phpFox2 supports numerous user groups you can specify exactly how a user group should behave. In order to get the value for a specific setting that controls how a user group behalves we use the method getUserParam. From the name you can understand that we will be getting a users parameter. The return value could be Strings, Arrays, Integers or Boolean. It really depends on the setting itself and what sort of information it holds. The most common return value is boolean and it returns either true or false. Lets take for example the Guest user group. Lets say we do not want them to view blogs and the variable name for this setting is blog.can_wiew_blogs (Note that the variable name can be found in the AdminCP and is defined by the one that created the setting). You can then do the following:

if (!Phpfox::getUserParam('blog.can_wiew_blogs'))
{
	return Phpfox_Error::display('Not allowed to view blogs!');
}

From the example above you can see we used the first parameter for this method to identify which setting we would like returned. If it returned false we returned the script with an error message which will output the message:

Not allowed to view blogs!

If you do not want to display an error message and simply redirect them to the generic page that informs them that the feature they are trying to view/use is only allowed for certain user groups you can do the following:

Phpfox::getUserParam('blog.can_wiew_blogs', true);

As you can see we did not need an if statement any longer and we did everything in one line by adding a true (bool) to the 2nd parameter. Note that if the site allows subscriptions it will display a page guiding the user to upgrade their membership and if they are not logged in it will auto redirect to the login page.

Just like how other params work we always identify a param with what module it belongs to and in this case it would be the blog module.

isAdminPanel()

It may come up that you need to identify if a page you are viewing is being viewed from the AdminCP. This is very rare as this is usually required in the core source code, but in case you need such a function this will return a boolean true or false with the latter confirming that its not currently being viewed from the AdminCP.

getPhrase()

phpFox2 has multilingual support and because of this it is very important to use the Language Package. More detailed information regarding the language package will be looked over later however getPhrase() is the method we use to return a phrase from the current language package that is being used. If for example we have a phrase with the variable name user.user_not_logged_in and the phrase value was

You are not logged in!

In order to display the phrases value we can call this method from anywhere in the script by doing the following:

Phpfox::getPhrase('user.user_not_logged_in')

There are some phrases that have values that need to be replaced by new values. For example if we had the following phrase with the variable name user.welcome_back_user:

Hello, {user_name}. Welcome back!

Since each user has a different user name we need PHP to identify what the user name is and since phrases are stored in a language package and mass distributed we would need to create a system to allow certain words to be replaced with PHP variables. Using the above example you can replace {user_name} with the user name for the current user logged in by doing the following:

Phpfox::getPhrase('user.welcome_back_user', array('user_name' => Phpfox::getUserBy('user_name')))

Notice we added the following:

array('user_name' => Phpfox::getUserBy('user_name'))

Since we use an array you can replace as many strings as you need as long as they are surrounded by { and }.

getParam()

Similar to the method getUserParam() this method returns a global setting. These settings are found in

AdminCP >> Settings >> Manage Settings.

If for example we had a variable name core.site_title which holds the value for the sites name we could get this value by doing the following:

Phpfox::getParam('core.site_title')

addMessage()

You may find that you need to notify a user with a quick message at times. It requires extra work if you do this via the template so adding a message with the method addMessage is rather easy as it requires only one parameter and that is the actual message you want to pass. Note that this message will be displayed after you have called the method and its mostly used when sending the user to another page or refreshing the page after a posted form. To display this message on top of the main content under the main menu (depending on the template being used) you can do the following:

Phpfox::addMessage('Your blog has been added.');

This will then display the message:

Your blog has been added.

Note when redirecting users which you will learn how to do shortly has a parameter which you can pass a messages with thus leaving this method obsolete in many instances.

setCookie()

Cookies are really yummy and you can set them using this method. We allow 3 parameters with the first being the name of the cookie. The 2nd being the value of the cookie and the 3rd being how long the cookie should last. Note that 0 will expire after the user closes their browser and -1 will destroy the cookie. Here is an example of how to set a cookie:

Phpfox::setCookie('cookie_name', 'cookie_value');

From the example you can see we did not add a 3rd parameter as it defaults to 0.

getCookie()

In order to return the value of the cookie we us the method getCookie(). There is only one parameter and that is the first one which is used to identify the cookies name. Here is a working exmaple:

Phpfox::getCookie('cookie_name');

Cache

Class file: /include/library/phpfox/cache/cache.class.php

With phpFox2 we have focused greatly on caching a lot of the data that is being viewed but not constantly updated or the need to display live information not required. If we come across data that has the possibility of being cached we make sure we cache it and follow up on updating the cached data once it needs to be updated. We provide support for 3 different methods of caching. File, Memcache and APC. We recommend using both APC or Memcache, however flat file caching is the commonly used method as the other 2 requires configuring your server. Most of the data we cache is what we pull out from the database. Since pulling loads of information from the database can be very costly with memory consumption and overall performance of the script there are methods to help with this and caching is one of the most effective methods. The supported storage engines can be found in the folder:

/include/library/phpfox/cache/storage/

By default we automatically use the file storage engine. If using the file storage engine cached files are stored in flat files in the folder:

/file/cache/

The cache folder needs to be writable, however the file folder does not. All cached files have a check at the beginning of the file to make sure no direct access can be done. During development you can see the file names of the cached files, however during a live environment all cached files have an MD5() hashed name with a unique salt.

You can cache Strings, Integers, Boolean values or Arrays. You cannot store objects, sessions or sensitive information. Here is a working example of how to cache data being pulled from the database:

$oCache = Phpfox::getLib('phpfox.cache');
$sCachedId = $oCache->set('module');		
if (!($aModules = $oCache->get($sCachedId)))
{
	$aModules = Phpfox::getLib('phpfox.database')->select('m.module_id, m.name')
		->from(Phpfox::getT('module'), 'm')
		->join(Phpfox::getT('product'), 'p', 'm.product_id = p.product_id AND p.is_active = 1')
		->where('m.is_active = 1')
		->order('m.name')
		->execute('getRows');
 
	$oCache->save($sCachedId, $aModules);
}

Now lets dissect the above example line by line.

First we call the cache object.

$oCache = Phpfox::getLib('phpfox.cache');

Next we set the unique name of the cache file to module. Make sure to pick a unique name that is related to what is being stored. In most cases we try to use the database table name. This method will return the unique cache id which we created the variable $sCachedId.

$sCachedId = $oCache->set('module');

Next we do an if statement to make sure not to run the query within the statement as that would be a waste of resources since the data is already cached.

if (!($aModules = $oCache->get($sCachedId)))

If the data is not cached then inside the if statement we first run an SQL query.

$aModules = Phpfox::getLib('phpfox.database')->select('m.module_id, m.name')
		->from(Phpfox::getT('module'), 'm')
		->join(Phpfox::getT('product'), 'p', 'm.product_id = p.product_id AND p.is_active = 1')
		->where('m.is_active = 1')
		->order('m.name')
		->execute('getRows');

Once we ran the query we save the data using the save method. Remember for the first parameter you must add the unique cache id which you created a variable for with the set method. The 2nd parameter is what is used to store the data which in this case was an array.

$oCache->save($sCachedId, $aModules);

After the if statement, if you wanted to get all the modules which is what we pulled from the database you can use the variable $aModules which is what we created with the get method and if not cached it was then created by the SQL query. So the entire script would look like this:

$oCache = Phpfox::getLib('phpfox.cache');
$sCachedId = $oCache->set('module');		
if (!($aModules = $oCache->get($sCachedId)))
{
	$aModules = Phpfox::getLib('phpfox.database')->select('m.module_id, m.name')
		->from(Phpfox::getT('module'), 'm')
		->join(Phpfox::getT('product'), 'p', 'm.product_id = p.product_id AND p.is_active = 1')
		->where('m.is_active = 1')
		->order('m.name')
		->execute('getRows');
 
	$oCache->save($sCachedId, $aModules);
}
 
foreach ($aModules as $aModule)
{
	echo $aModule['name'];
}

set()

This method is used to create a unique name of the cache file. This must be a name that only uses characters from a-z and must be lowercase and cannot contain any other characters other then the underscore _. Here are some wrong and right examples:

Wrong

cacheName
another name
new-name

Right

cache_name
another_name
new_name

There is only one parameter and that is the name of file we plan to cache. Here is a working example:

$sCachedId = Phpfox::getLib('phpfox.cache')->set('module');

This method will return a unique string id.

get()

Use the get method to return the cached value. If the data has not yet been cached it will return a Boolean false. This method has 2 parameters with the first being the unique cache id which you created with the method set. The 2nd is an optional parameter and that is used if you want to limit how long the cached data can be cached before it has to be re-cached. Here is a working example without a time limit:

$aModules = Phpfox::getLib('phpfox.cache')->get($sCachedId);

Make sure to create a return variable otherwise you will not be able to retrieve your cached data which we created with the variable $aModules. Here is an example using this method with a time limit:

$aModules = Phpfox::getLib('phpfox.cache')->get($sCachedId, 15);

Notice we added a 15 for the 2nd parameter which stands for 15 minutes before the data has to be re-cached.

save()

You can save your data with the save method. This method has 2 parameters with the first being the unique cache id you got from the set method and the other the data we are going to cache. You can cache Strings, Integers, Boolean and Arrays. Here is a working example:

Phpfox::getLib('phpfox.cache')->save($sCachedId, $aModules);

Your cache connection is automatically closed once you have saved the data so there is no need to use the close method.

close()

You can close the cache connection you have open which was created with the set method. This method has one parameter which needs to pass the unique cache id.

remove()

Once you have cached data without a time limit then it will not get updated until you clear the cache which can be done with the remove method. This method provides the ability to remove cached data based on the name, sub string of a name or all of the cached data.

name

Pass the name of the unique ID you created earlier with the set method. So far we have used the name module as our unique cache name so using this as an example you can remove this cache file by doing the following:

Phpfox::getLib('phpfox.cache')->remove('module');

sub string

Pass the sub string of a name you created earlier with the set method. For example we cache several types of language arrays which use the prefix language_. So instead of removing these one by one we can do a sub string remove like so:

Phpfox::getLib('phpfox.cache')->remove('language', 'substr');

From the above example you can see we now used the 2nd parameter to pass the command we need to run which in this case was substr.

all

If you want to clear all the cached data you can do the following:

Phpfox::getLib('phpfox.cache')->remove();

This will remove every cached item.

isCached()

The isCached method is used to check if a file is cached. We don't use this method in public calls mainly because the method get has this method built in to it so you would end up running it twice and thus wasting resources. However, there are times when we must use this when trying to simply check if something is cached without the need to get it and if this is the case you can do the following:

if (!Phpfox::getLib('phpfox.cache')->isCached($sCacheId))
{
      // Add stuff we need to cache.
}

With the above example you can see we used an if statement to check if a cache was set for the ID $sCacheId. It will return a Boolean true or false with the latter identifying that the data was not cached.

You can also check if a file has passed a certain time limit you have set which is handy to automatically update data without having to manually remove it. You can do this with the following method:

if (!Phpfox::getLib('phpfox.cache')->isCached($sCacheId, 15))
{
      // Add stuff we need to cache.
}

We now added a 15 to the 2nd parameter which checks if the data is older then 15 minutes and it will return a Boolean false otherwise true if under or on the 15 minute mark.

Request

Class path: /include/library/phpfox/request/request.class.php

In order to get information from users we must understand the requests they are sending and to do this we use the Request class. Requests can be sent via a URL string or a form that is being posted.

get()

To get a request either from a URL string ($_GET) or passed via a form ($_POST and/or $_FILES) you can use the get method.

URL String ($_GET)

Getting from a URL string is a little different from the conventional method that would look something like this:

index.php?action=blog&id=1

Since we have a special way of creating short URLs that are easy to read and both user friendly the above would end up as:

index.php?do=/action_blog/id_1/

This example does not use the short URL method but you can get the idea of how to pass requests via a URL string. If you have short URLs setup it would look like this:

/action_blog/id_1/

Now to get the value of action the conventional method would be:

$_GET['action']

With phpFox2 you can get the value for action by using the following method:

Phpfox::getLib('phpfox.request')->get('action')

Usually its better to create a variable for the object since you will probably use the request object more then once. Here is an example:

$oRequest = Phpfox::getLib('phpfox.request');
$oRequest->get('action');
$oRequest->get('id');

So why use our method instead of the conventional method? The reason for this is since we provide a special way to create short URLs this is the best way to pass values via a URL string and all data being passed is parsed before you get the value so its safe before you even use it. Another problem we face with the conventional method is PHPs Magic Quotes, which will be removed with PHP6. Using this method will fix this problem and if a server has this feature enabled or disabled it will function the same way. Another benefit is since we code in strict conditions you won't have to check if a request has been set thus adding more work for you to check each request with isset(). If a request has not been set because it was not passed via the URL the method will return a Boolean false and if you were to pass a 2nd parameter it will return that value as the default value. For example if we did not pass the action request via the URL and we wanted the variable that will be set for this request to have a default value you can do the following:

$sAction = Phpfox::getLib('phpfox.request')->get('action', 'blog');

You will notice in the 2nd parameter we added blog and this method will return the string value blog if the action request was not set.

Form ($_POST)

Everything that applies to the URL String method of getting requests applies to this method other then the way it is passed. Since the URL String method uses the URL to pass requests the form method passes it via a form. For example if we had the following form:

<form method="post" action="index.php">
     <input type="text" name="user_name" />
     <input type="text" name="email" />
</form>

If you were to post the above form the requests would then be user_name and email. This works much like using the conventional method:

echo $_POST['user_name'];

Instead we use:

echo Phpfox::getLib('phpfox.request')->get('user_name');

getInt()

The method getInt works identical to the get method other then the fact that it only allows integers to be passed. Meaning if you were to pass a string or array it will default the value to 0. If an integer was passed it will then allow it and pass it to you.

getArray()

The getArray method works somewhat identical to that of the get method other then the fact that it only allows arrays to be passed. This is something we never use with the URL String method of passing requests. This is generally used with forms. Notice that most of our forms are built around the array val[] and as a rule if building a module or add-on for phpFox2 and if you are going to be passing more the one request via a form it must use the val[] array. Here is a wrong and right example of how a form should look when passing requests:

Wrong

<form method="post" action="index.php">
    <input type="text" name="user_name" />
    <input type="text" name="email" />
</form>

Right

<form method="post" action="index.php">
    <input type="text" name="val[user_name]" />
    <input type="text" name="val[email]" />
</form>

In order to get this request when being passed is to use the getArray method like so:

$aVals = Phpfox::getLib('phpfox.request')->get('val');

The variable we created $aVals will hold the array value for val[] so to echo the user_name and email you could do the following:

echo $aVals['user_name'];
echo $aVals['email'];

Note that it is important to name the variable $aVals for requests you are retrieving via a posted form and if the form uses the val[] method. This way we all know that $aVals is a variable that is holding data that is being passed by a form.

getServer()

Instead of using $_SERVER[] we use our own method getServer(). The reason for this is some server environments might not have a variable you are looking for which will lead to a ugly PHP notice which we don't want to have. Plus we have added some of our own server variables. Note that you can call anything via this method if its supported by $_SERVER[] and we will return it if it exists.

Below we have added some of our own variables that might be useful.

SERVER_NAME

Instead of using the default SERVER_NAME' we check if HTTP_X_FORWARDED_HOST is set because of our Server Load Balancing feature this needs to return the correct server. If HTTP_X_FORWARDED_HOST is not set then it will return SERVER_NAME as normal.

HTTP_HOST

Instead of using the default HTTP_HOST' we check if HTTP_X_FORWARDED_HOST is set because of our Server Load Balancing feature this needs to return the correct server. If HTTP_X_FORWARDED_HOST is not set then it will return HTTP_HOST as normal.

REMOTE_ADDR

Instead of using the default REMOTE_ADDR we try to find and return the users IP, which we try to find if they are hiding behind a proxy.

PHPFOX_SERVER_ID

If you have the Server Load Balancing feature enabled this is a variable we use to find out what server the user is currently on so we can use that information for benefits of the Server Load Balancing feature.

getBrowser()

It will return the browser that the user is using but will return it in a very short format such as

Firefox 3

IE 7

send()

At times we may need to send information to another server and at the same time retrieve the information from that server depending on the parameters we have sent. To do this you can use the send method. This method supports curl (POST & GET), file_get_contents (GET) and fsockopen (POST & GET). We use curl by default however some servers do not have support for this so we then try file_get_contents and for our last resport we use fsockopen.

This method has 3 parameters with only the first being required and is the full path to where you will be sending the request. The 2nd parameter is optional and is setup to allow an array of requests you plan to pass. These will end up as POST or GET requests depending on the 3rd parameter. For the 3rd parameter which is also optional is used to identify how you want to send the request and this can be POST or GET and defaults to POST if this parameter is left empty.

Here is a working example:

Phpfox::getLib('phpfox.request')->send('http://api.phpfox.com/', array(
	'foo' => 'bar',
	'var' => 'value'
));

Once the other server gets this request it can for example echo the following requests that were sent:

echo $_POST['foo'];
echo "<br />";
echo $_POST['var'];

This output will be:

bar
value

Since we did not create a variable or echo the call from our side we won't see anything, however the other server will get the request and can handle the information without the user even knowing. If you want to return the value simply create a variable for the call like so:

$sRequest = Phpfox::getLib('phpfox.request')->send('http://api.phpfox.com/', array(
	'foo' => 'bar',
	'var' => 'value'
));

You could then use the variable $sRequest and if you were to echo it you would see the following output:

bar
value

Previous Chapter: Coding Guidelines | Next Chapter: Products

Retrieved from "http://wiki.phpfox.com/guide/V2/Libraries"

Home » V2 » Libraries

Contents

Classes

Phpfox

run()

getLib()

getService()

getT()

getUserId()

getUserBy()

isUser()

getUserParam()

isAdminPanel()

getPhrase()

getParam()

addMessage()

setCookie()

getCookie()

Cache

set()

get()

save()

close()

remove()

name

sub string

all

isCached()

Request

get()

URL String ($_GET)

Form ($_POST)

getInt()

getArray()

getServer()

SERVER_NAME

HTTP_HOST

REMOTE_ADDR

PHPFOX_SERVER_ID

getBrowser()

send()