API for plug-ins development

<< Click to Display Table of Contents >>

Navigation:  For developers >

API for plug-ins development

This API is designed for the development of plug-ins that are compatible with older and future versions of the script. If you use the API to retrieve data from the database, you can be assured that the code will work in future versions. It makes the work and adaptation of the code easier in new versions. Also, when using the API you do not need to write your own function to retrieve data, there is no need to connect and declare classes for work with the database. Simply connect the file API, and start using it functions, all the rest it takes upon itself.

 

To use the API in a plug-in, you have to include it:

 

include ('engine/api/api.class.php');

 

In this case, you do not need to think about whether there is a connection to the database or not, are the necessary classes connected or not. This code can be used in files of DLE script and in other scripts that are not related to DLE. It allows you to organize standardized integrations of DLE script with other scripts. Such as forums.

 

List of API fuctions:

 

$dle_api->take_user_by_id( int $id [, string $select_list] );

Gets an array of information about the user by his ID. The optional parameter $select_list points to a list of database fields to be obtained, or * for all. Returns an array of information about the user or false if the user is not found.

 

$dle_api->take_user_by_name( string $name [, string $select_list]);

Gets an array of information about the user by his login. The optional parameter $select_list points to a list of database fields to be obtained, or * for all. Returns an array of information about the user or false if the user is not found.

 

$dle_api->take_user_by_email( string $email [, string $select_list]);

Gets an array of information about the user by his e-mail. The optional parameter $select_list points to a list of database fields to be obtained, or * for all. Returns an array of information about the user or false if the user is not found.

 

$dle_api->take_users_by_group( int $group_id [, string $select_list [, int $limit]]);

Gets an array of information about users by the user group. The optional parameter $select_list points to a list of database fields to be obtained. The optional parameter $limit indicates the limit of the number of return users. Returns an array of information about the user or false if the user is not found.

 

$dle_api->take_users_by_ip( string $ip, [, bool $like [, string $select_list [, int $limit]]]);

Getting a list of users by IP, the second parameter $like indicates whether to use an exact or inexact matching for the search. The optional parameter $select_list points to a list of database fields to be obtained. The optional parameter $limit indicates the limit of the number of return users. Returns an array of information about the user or false if the user is not found.

 

$dle_api->change_user_name( int $user_id, string $new_name);

Changing the user's login. user_id is ID of the user who's login should be replaced. new_name is a new user's login. Return values: true if completed successfully, false if the new name is already taken by another user.

 

$dle_api->change_user_pass( int $user_id, string $new_pass);

Changing the user's password. user_id is ID of the user who's password should be replaced. new_pass is a new user's password.

 

$dle_api->change_user_email( int $user_id, string $new_email);

Changing the user's e-mail. user_id is ID of the user who's e-mail should be replaced. new_email is a new user's e-mail. Return values: 1 - completed successfully, -1 - this e-mail is already taken, -2 - incorrect e-mail.

 

$dle_api->change_user_group( int $user_id, int $new_group);

Changing the user's group. user_id is ID of the user whose group should be changed. new_group is ID of a new user group. Return values: true if completed successfully, false if nonexistent group's ID is specified.

 

$dle_api->external_auth( string $login, string $password);

Log in using login and password. Return values: true - the authorization is successful, false - login or password is not correct.

 

$dle_api->external_register( string $login, string $password, string $email, int $group);

User registration in the database. The following is passed to the function: Login, password, e-mail and a group number where the user must be registered. Return values: 1 - completed successfully, -1 - this login is already taken, -2 - this e-mail is already taken, -3 - incorrect e-mail,  -4 - nonexistent group is specified.

 

$dle_api->send_pm_to_user ( int $user_id, string $subject, string $text, string $from);

Sending a personal message to a user. $user_id - ID of the recipient. $subject - subject of the message. $text - text of the message. $from - sender's login. Return values: 1 - completed successfully, -1 - recipient is not found, 0 - database error.

 

$dle_api->load_table ( string $table [, string $fields [, string $where [, bool $multirow [, int $start [, int $limit [, string $sort [, string $sort_order]]]]]]]);

 

Getting information from a database table.

$table -  table name

$fields - needed fields separated by a comma, or * for all

$where - sampling condition

$multirow - take one row or more

$start -  initial value of sample

$limit - number of entries for sample, 0 - select all

$sort - field, which is used for sorting

$sort_order - sort order

 

Returns an array of data, or false if nothing is found in the database on the specified criteria.

 

$dle_api->save_to_cache ( string $fname, mixed $vars);

Writing data to a cache file. $fname indicates the name of the cache file without its extension. $vars - data to be written to the cache.

 

$dle_api->load_from_cache ( string $fname,  [, int $timeout [, string $type]]);

Reading data from a cache file. $fname indicates the name of the cache file without its extension. Optional parameter $timeout indicates the number of seconds during which the information from cache is considered relevant. If the cache file is outdated, then the function returns false. Optional parameter $type indicates the data type to be stored in cache. If it is not 'text' - then it is considered that array is stored and array of data is returned.

 

$dle_api->clean_cache (  [string $name] );

Deleting the cache. Optional parameter $name indicates a specific file name without the extension that you want to delete.

 

$dle_api->get_cached_files();

Get an array that contain names of cache files.

 

$dle_api->edit_config ( mixed $key,  [, string $new_value]);

Changing and saving the script settings.

 

Parameter $key can be the string or array

              string: The name of the parameter

              array: Associative array of parameters

 

$new_value - value of the parameter. Not used if $key is the array.

 

$dle_api->take_news ( string $cat,  [, string $fields [, int $start [, int $limit [, string $sort [, string $sort_order]]]]]);

 

Getting news

$cat  - news categories separated by commas

$fields - list of received news fields, or * for all

$start  - initial value of the sample

$limit - number of articles for the sample, 0 - select all

$sort - field, which is used for sorting

$sort_order - sort order

 

Returns an associative 2-dimensional array with the news

 

$dle_api->checkGroup ( int $group );

Checks whether this group exists or not. Return values: true if group exists, false if group does not exist.

 

$dle_api->install_admin_module ( string $name, string $title, string $descr, string $icon [, string $perm] );

 

Installation of a third-party plug-in into Administration Panel of the script.

$name -  Namely, it is a .php file from engine/inc/ folder, but without the file extension.

$title - Your plug-in's title.

$descr - Your plug-in's description.

$icon -Contains the name of the icon for your module without its path. The icon must be located in engine/skins/images/ (it is required). Recommended icon size is 70 by 70 pixels.

$perm - Contains information about the groups where this plug-in is allowed.  This field can take the following values: all or ID of groups separated by commas. For example: 1,2,3. If all value is specified, then plug-in will be displayed for all users who have an access to Administration Panel.

 

$dle_api->uninstall_admin_module ( string $name );

Delete third-party plug-in form Administration Panel.

 

$name - name of the module to be removed.

 

$dle_api->change_admin_module_perms ( string $name, string $perm );

Changing user groups that are allowed to see a third-party plug-in in the Administration Panel.

 

$name - Your plug-in's title.

$perm - Contains information about the groups where this plug-in is allowed.  This field can take the following values: all or ID of groups separated by commas. For example: 1,2,3. If all value is specified, then plug-in will be displayed for all users who have an access to Administration Panel.

 

 

Development of the complete API has just begun and currently API has a limited set of functions. We therefore ask everyone who is interested in the development of ths API to visit a specially created thread in the forum and leave your feedback about what new features you would like to see in the new versions. You can help us to create a complete API that covers all the aspects of interaction with the script.