Difference between revisions of "Libraries Organization"

Jump to: navigation, search
(lib.php)
(Structure)
Line 6: Line 6:
 
= Structure =
 
= Structure =
  
== file location ==
+
There are several standard locations for library code in Moodle.  
*if you are writing a module (like workshop) => mod/folder/lib.php and mod/folder/locallib.php
 
*if you are writing something more general and there is a folder in relation (like comments, user, group,...) => folder/lib.php
 
*if you are writing something more general and there is no folder in relation => lib/namelib.php
 
  
== file content structure ==
+
==Simple core library==
=== lib.php ===
 
It contains code that can be called all over Moodle core.<br/>
 
#Some devs continues to write xxx/lib.php or lib/xxxlib.php with procedural functions.<br/>
 
#Some devs did some work (committed, working on, in specs) with xxx/lib.php or lib/xxxlib.php being a class.<br/>
 
  
=== locallib.php ===
+
If the widget feature is a very simple core librray with no GUI scripts (like formslib) then:
It contains code specific to the module.<br/>
 
You should write it the best you can => no recommandation yet<br/>
 
We can see a tendency that new module locallib.php will likely contain class when refactored locallib.php will likely be a procedural functions... <br/>
 
  
=== externallib.php ===
+
  * lib/widgetlib.php
It contains code that can be called by external applications. The functions are not supposed to be called by our core scripts.<br/>
+
 
The functions include capability check.<br/>
+
Any supporting files for this library can go in lib/widget/*  This directory should not contain any GUI scripts and no files that are directly included.
 +
 
 +
 
 +
==Complex core library or plugin module==
 +
 
 +
If the feature has some GUI scripts then it should have its own directory (eg like blog, comment, mod/forum, local/widget etc) and then this is always applies:
 +
 
 +
    * widget/locallib.php - for functions and classes that will only be used by scripts in widget directory. Generally there will be no capability checks in these functions.
 +
    * widget/lib.php - the main library file for the module containing functions that are either required by core code (eg forum_cron()), or simply being made available to other Moodle code (eg comment/lib.php).  Generally there will be no capability checks in these functions.
 +
    * widget/externallib.php - for functions and classes implementing external interface for use by third-party systems like web services, and may also be used by other modules in Moodle. These functions are a very stable API and implement full capability checking.
  
 
= Refatoring of old code =  
 
= Refatoring of old code =  

Revision as of 09:53, 15 March 2010

Moodle 2.0


This document has for goal to defined a libraries structure to avoid to end up with a mess of functions everywhere into Moodle.

We suggest that we split library functions into two files, one lib.php that contains all library functions that can be called by external applications and one locallib.php that contains all functions that are internal to Moodle core.

Structure

There are several standard locations for library code in Moodle.

Simple core library

If the widget feature is a very simple core librray with no GUI scripts (like formslib) then:

 * lib/widgetlib.php

Any supporting files for this library can go in lib/widget/* This directory should not contain any GUI scripts and no files that are directly included.


Complex core library or plugin module

If the feature has some GUI scripts then it should have its own directory (eg like blog, comment, mod/forum, local/widget etc) and then this is always applies:

   * widget/locallib.php - for functions and classes that will only be used by scripts in widget directory. Generally there will be no capability checks in these functions.
   * widget/lib.php - the main library file for the module containing functions that are either required by core code (eg forum_cron()), or simply being made available to other Moodle code (eg comment/lib.php).  Generally there will be no capability checks in these functions.
   * widget/externallib.php - for functions and classes implementing external interface for use by third-party systems like web services, and may also be used by other modules in Moodle. These functions are a very stable API and implement full capability checking.

Refatoring of old code

Groups

currently in group/lib.php

  • groups_add_member($grouporid, $userorid)
  • groups_remove_member($grouporid, $userorid)
  • groups_create_group($data, $editform=false, $editoroptions=null)
  • groups_create_grouping($data, $editoroptions=null)
  • groups_update_group($data, $editform=false)
  • groups_update_grouping($data, $editoroptions=null)
  • groups_delete_group($grouporid)
  • groups_delete_grouping($groupingorid)
  • groups_delete_group_members($courseid, $userid=0, $showfeedback=false)
  • groups_delete_groupings_groups($courseid, $showfeedback=false)
  • groups_delete_groups($courseid, $showfeedback=false)
  • groups_delete_groupings($courseid, $showfeedback=false)
  • groups_get_possible_roles($context)
  • groups_get_potential_members($courseid, $roleid = null, $orderby = 'lastname,firstname')
  • groups_parse_name($format, $groupnumber)
  • groups_assign_grouping($groupingid, $groupid)
  • groups_unassign_grouping($groupingid, $groupid)
  • groups_get_members_by_role($groupid, $courseid, $fields='u.*', $sort='u.lastname ASC', $extrawheretest=, $whereparams=array())
  • groups_calculate_role_people($rs, $context)

currently in lib/grouplib.php

  • groups_group_exists($groupid)
  • groups_get_group_name($groupid)
  • groups_get_grouping_name($groupingid)
  • groups_get_group_by_name($courseid, $name)
  • groups_get_grouping_by_name($courseid, $name)
  • groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)
  • groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)
  • groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*')
  • groups_get_user_groups($courseid, $userid=0)
  • groups_get_all_groupings($courseid)
  • groups_is_member($groupid, $userid=null)
  • groups_has_membership($cm, $userid=null)
  • groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')
  • groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')
  • groups_get_course_groupmode($course)
  • groups_get_activity_groupmode($cm, $course=null)
  • groups_print_course_menu($course, $urlroot, $return=false)
  • groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)
  • groups_get_course_group($course, $update=false)
  • groups_get_activity_group($cm, $update=false)
  • groups_get_activity_allowed_groups($cm,$userid=0)
  • groups_course_module_visible($cm, $userid=null)

New group/lib.php

groups_add_member($grouporid, $userorid)
groups_remove_member($grouporid, $userorid)
groups_create_group($data, $editform=false, $editoroptions=null)
groups_create_grouping($data, $editoroptions=null)
groups_update_group($data, $editform=false)
groups_update_grouping($data, $editoroptions=null)
groups_delete_group($grouporid)
groups_delete_grouping($groupingorid)
groups_delete_group_members($courseid, $userid=0, $showfeedback=false)
groups_delete_groupings_groups($courseid, $showfeedback=false)
groups_delete_groups($courseid, $showfeedback=false)
groups_delete_groupings($courseid, $showfeedback=false)
groups_assign_grouping($groupingid, $groupid)
groups_unassign_grouping($groupingid, $groupid)
groups_get_members_by_role($groupid, $courseid, $fields='u.*', $sort='u.lastname ASC', $extrawheretest=, $whereparams=array())
groups_group_exists($groupid)
groups_get_group_name($groupid)
groups_get_grouping_name($groupingid)
groups_get_group_by_name($courseid, $name)
groups_get_grouping_by_name($courseid, $name)
groups_get_group($groupid, $fields='*', $strictness=IGNORE_MISSING)
groups_get_grouping($groupingid, $fields='*', $strictness=IGNORE_MISSING)
groups_get_all_groups($courseid, $userid=0, $groupingid=0, $fields='g.*')
groups_get_user_groups($courseid, $userid=0)
groups_get_all_groupings($courseid)
groups_is_member($groupid, $userid=null)
groups_has_membership($cm, $userid=null)
groups_get_members($groupid, $fields='u.*', $sort='lastname ASC')
groups_get_grouping_members($groupingid, $fields='u.*', $sort='lastname ASC')
groups_get_course_groupmode($course)
groups_get_activity_groupmode($cm, $course=null)
groups_get_course_group($course, $update=false)
groups_get_activity_group($cm, $update=false)
groups_get_activity_allowed_groups($cm,$userid=0)
groups_print_course_menu($course, $urlroot, $return=false)
groups_print_activity_menu($cm, $urlroot, $return=false, $hideallparticipants=false)
groups_course_module_visible($cm, $userid=null)

New group/locallib.php

groups_get_possible_roles($context)
groups_get_potential_members($courseid, $roleid = null, $orderby = 'lastname,firstname')
groups_parse_name($format, $groupnumber)
groups_calculate_role_people($rs, $context)

Users

Currently in lib/datalib.php

  • get_users($get=true, $search=, $confirmed=false, array $exceptions=null, $sort='firstname ASC', $firstinitial=, $lastinitial=, $page=, $recordsperpage=, $fields='*', $extraselect=, array $extraparams=null) New for triage
  • get_users_confirmed()New for triage
  • get_users_listing($sort='lastaccess', $dir='ASC', $page=0, $recordsperpage=0, $search=, $firstinitial=, $lastinitial=, $extraselect=, array $extraparams=null)New for triage
  • search_users($courseid, $groupid, $searchtext, $sort=, array $exceptions=null)New for triage
  • user_accesstime_log($courseid=0)New for triage
  • user_can_create_courses()New for triage

Currently in user/profile/lib.php

  • profile_user_record($userid) New for triage
  • profile_load_data(&$user)New for triage

Currently in lib/moodlelib.php

authenticate_user_login($username, $password)
calculate_user_dst_table($from_year = NULL, $to_year = NULL, $strtimezone = NULL)
check_user_preferences_loaded($time = null)
complete_user_login($user, $setcookie=true)
create_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null)
create_user_record($username, $password, $auth='manual')
delete_user($user)
get_complete_user_data($field, $value, $mnethostid=null)
get_user_directories($only_non_empty=true, $legacy=false)
get_user_fieldnames()
get_user_preferences($name=NULL, $default=NULL, $otheruserid=NULL)
get_user_timezone($tz = 99)
get_user_timezone_offset($tz = 99)
get_users_from_config($value, $capability)
guest_user()
hash_internal_user_password($password)
is_restored_user($username)
isguestuser($user=NULL)
isloggedin()
make_user_directory($userid, $test=false)
mark_user_preferences_changed($userid)
set_user_preference($name, $value, $otheruserid=NULL)
set_user_preferences($prefarray, $otheruserid=NULL)
truncate_userinfo($info)
unset_user_preference($name, $otheruserid=NULL)
update_internal_user_password(&$user, $password)
update_user_login_times()
update_user_record($username, $authplugin)
user_not_fully_set_up($user)
user_preference_allow_ajax_update($name, $paramtype)
userdate($date, $format = , $timezone = 99, $fixday = true)
usergetdate($time, $timezone=99)
usergetmidnight($date, $timezone=99)
usertime($date, $timezone=99)
usertimezone($timezone=99)
validate_internal_user_password(&$user, $password)

Move to lib/deprecatedlib.php

  • create_user_record($username, $password, $auth='manual')
  • update_user_record($username, $authplugin)
  • get_complete_user_data($field, $value, $mnethostid=null)

New user/lib.php

  • user_create_user($user)
  • user_delete_user($user)
  • user_update_user($user)
  • user_get_user($user)
  • get_user_preferences($name=NULL, $default=NULL, $otheruserid=NULL)
  • set_user_preference($name, $value, $otheruserid=NULL)
  • set_user_preferences($prefarray, $otheruserid=NULL)
  • unset_user_preference($name, $otheruserid=NULL)
  • guest_user()
  • isguestuser($user=NULL)
  • isloggedin()
  • is_restored_user($username)
  • complete_user_login($user, $setcookie=true)

New user/locallib.php

authenticate_user_login($username, $password)
check_user_preferences_loaded($time = null)
create_user_key($script, $userid, $instance=null, $iprestriction=null, $validuntil=null)
get_user_directories($only_non_empty=true, $legacy=false)
get_user_fieldnames()
get_users_from_config($value, $capability)
hash_internal_user_password($password)
make_user_directory($userid, $test=false)
mark_user_preferences_changed($userid)
truncate_userinfo($info)
update_internal_user_password(&$user, $password)
update_user_login_times()
user_not_fully_set_up($user)
user_preference_allow_ajax_update($name, $paramtype)
validate_internal_user_password(&$user, $password)


New lib/timelib.php

userdate($date, $format = , $timezone = 99, $fixday = true)
usergetdate($time, $timezone=99)
usergetmidnight($date, $timezone=99)
usertime($date, $timezone=99)
usertimezone($timezone=99)
calculate_user_dst_table($from_year = NULL, $to_year = NULL, $strtimezone = NULL)
get_user_timezone($tz = 99)
get_user_timezone_offset($tz = 99)