ResourceSpace software design principles

Coding standards: Coding standards v1.2

ResourceSpace software design principles

Contributing to the base code

Intellectual property
Security in ResourceSpace: Access control

Cross-Site Request Forgery (CSRF)

Injection
Developer reference: Project structure

Database schema

Fixed list fields

Debugging ResourceSpace

Writing your own plugins

Context help links

Custom fields ("user" defined)

Query caching
Database: Table: activity_log

Table: annotation

Table: annotation_node

Table: collection

Table: collection_keyword

Table: collection_log

Table: collection_resource

Table: collection_savedsearch

Table: comment

Table: daily_stat

Table: dash_tile

Table: dynamic_tree_node

Table: external_access_keys

Table: filter

Table: filter_rule

Table: filter_rule_node

Table: ip_lockout

Table: job_queue

Table: keyword

Table: keyword_related

Table: mail_log

Table: message

Table: node

Table: node_keyword

Table: plugins

Table: preview_size

Table: report

Table: report_periodic_emails

Table: report_periodic_emails_unsubscribe

Table: request

Table: research_request

Table: resource

Table: resource_alt_files

Table: resource_custom_access

Table: resource_data

Table: resource_dimensions

Table: resource_keyword

Table: resource_log

Table: resource_node

Table: resource_related

Table: resource_type

Table: resource_type_field

Table: search_log

Table: site_text

Table: slideshow

Table: sysvars

Table: user

Table: user_collection

Table: user_dash_tile

Table: user_message

Table: user_preferences

Table: user_rating

Table: user_report

Table: user_userlist

Table: usergroup

Table: usergroup_collection

Table: usergroup_dash_tile
Action functions: get_user_actions()

get_editable_resource_sql()
Admin functions: update_resource_type_field_order()

update_resource_type_order()
Ajax functions: ajax_permission_denied()

ajax_send_response()

ajax_send_text_response()

ajax_response_ok()

ajax_response_fail()

ajax_response_ok_no_data()

ajax_unauthorized()

ajax_build_message()
Annotation functions: getAnnotation()

getAnnotations()

getResourceAnnotationsCount()

getResourceAnnotations()

getAnnotoriousResourceAnnotations()

annotationEditable()

getAnnotationTags()

deleteAnnotation()

createAnnotation()

updateAnnotation()

addAnnotationNodes()

prepareTags()
API functions: iiif_error()

get_api_key()

check_api_key()

execute_api_call()

iiif_get_canvases()

iiif_get_thumbnail()

iiif_get_image()
Collections functions: get_user_collections()

get_collection()

get_collection_resources()

get_collection_resources_with_data()

add_resource_to_collection()

remove_resource_from_collection()

collection_writeable()

collection_readable()

set_user_collection()

create_collection()

delete_collection()

refresh_collection_frame()

search_public_collections()

do_collections_search()

add_collection()

remove_collection()

index_collection()

save_collection()

get_max_theme_levels()

get_theme_headers()

themes_comparator()

collections_comparator()

collections_comparator_desc()

get_themes()

get_smart_theme_headers()

get_smart_themes_nodes()

email_collection()

generate_collection_access_key()

get_saved_searches()

add_saved_search()

remove_saved_search()

add_smart_collection()

get_search_title()

add_saved_search_items()

allow_multi_edit()

save_themename()

get_theme_image()

swap_collection_order()

update_collection_order()

get_collection_resource_comment()

save_collection_resource_comment()

relate_to_collection()

get_mycollection_name()

get_collection_comments()

send_collection_feedback()

copy_collection()

collection_is_research_request()

add_to_collection_link()

remove_from_collection_link()

change_collection_link()

get_collection_external_access()

delete_collection_access_key()

collection_log()

get_collection_log()

get_collection_videocount()

collection_max_access()

collection_min_access()

collection_set_public()

collection_set_private()

collection_set_themes()

remove_all_resources_from_collection()

get_home_page_promoted_collections()

get_featured_collection_resources()

is_collection_approved()

get_featured_collection_categ_sub_fcs()

edit_collection_external_access()

generate_featured_collection_image_urls()

show_hide_collection()

update_collection_parent()

get_session_collections()

get_featured_collections()

update_collection_user()

featured_collections_permissions_filter_sql()

compile_collection_actions()

featured_collection_check_access_control()

makeFilenameUnique()

order_featured_collections_by_hasresources()

new_featured_collection_form()

get_featured_collection_categories()

get_last_resource_edit()

is_featured_collection_category()

GetThemesFromRequest()

is_featured_collection_category_by_children()

collection_download_get_archive_file()

validate_collection_parent()

collection_download_use_original_filenames_when_downloading()

get_featured_collection_category_branch_by_leaf()

collection_download_process_text_file()

process_posted_featured_collection_categories()

collection_download_log_resource_ready()

get_featured_collection_ref_by_name()

update_zip_progress_file()

allow_collection_share()

collection_download_process_data_only_types()

allow_featured_collection_share()

collection_download_process_summary_notes()

filter_featured_collections_by_root()

collection_download_process_csv_metadata_file()

get_featured_collections_by_resources()

collection_download_process_command_to_file()

can_delete_featured_collection()

collection_download_process_collection_download_name()

collection_download_process_archive_command()

collection_download_clean_temp_files()

collection_cleanup_inaccessible_resources()

relate_all_collection()

update_collection_type()

get_user_selection_collection()

delete_old_collections()

order_featured_collections()

strip_prefix_chars()

allow_upload_to_collection()

get_all_featured_collections()

compute_featured_collections_acess_control()

compute_featured_collections_access_control()

cleanup_anonymous_collections()
Comment functions: comments_submit()

comments_show()

validateAnonymousComment()

validateComment()

validateAnonymousFlag()

validateFlag()

submitForm()
Config functions: validate_field()

render_select_option()

render_bool_option()

render_text_option()

set_config_option()

get_config_option()

get_config_option_users()

get_config_options()

process_config_options()

config_clean()

config_html()

config_add_html()

config_text_input()

config_add_text_input()

config_file_input()

config_colouroverride_input()

config_add_file_input()

config_single_select()

config_add_single_select()

config_boolean_select()

config_add_boolean_select()

config_checkbox_select()

config_add_checkbox_select()

config_add_colouroverride_input()

config_add_single_ftype_select()

config_single_ftype_select()

config_generate_AutoSaveConfigOption_function()

config_process_file_input()

config_generate_html()

config_merge_non_image_types()

get_header_image()

config_register_core_fieldvars()
CSV export functions: generateResourcesMetadataCSV()

generateNodesExport()
Dash functions: existing_dash_tile()

dash_tile_featured_collection_get_resources()

create_dash_tile()

update_dash_tile()

delete_dash_tile()

revoke_all_users_flag_cascade_delete()

append_default_position()

reorder_default_dash()

update_default_dash_tile_order()

get_tile()

all_user_dash_tile_active()

existing_tile()

cleanup_dash_tiles()

checkTileConfig()

checkConfigCustomHomePanels()

get_alluser_available_tiles()

get_default_dash()

deleteDefaultDashTile()

updateDashTileOrder()

get_managed_dash()

add_usergroup_dash_tile()

append_usergroup_position()

reorder_usergroup_dash()

update_usergroup_dash_tile_order()

build_usergroup_dash()

get_tile_user_groups()

get_usergroup_available_tiles()

get_usergroup_tile()

add_user_dash_tile()

get_user_tile()

create_new_user_dash()

update_user_dash_tile_order()

delete_user_dash_tile()

empty_user_dash()

reorder_user_dash()

append_user_position()

get_user_available_tiles()

get_user_dash()

deleteDashTile()

render_delete_dialog_JS()

parse_dashtile_link()

build_dash_tile_list()

allow_tile_colour_change()

render_dash_tile_colour_chooser()

update_tile_preview_colour()

get_tile_custom_style()

delete_usergroup_dash_tile()

allowPromotedResources()

render_upgrade_available_tile()

generate_dash_tile_toolbar()
Debug functions: check_debug_log_override()

create_debug_log_override()

debug_function_call()
Encryption functions: rsEncrypt()

rsDecrypt()
Facial recognition functions: initFacialRecognition()

prepareFaceImage()

faceRecognizerPredict()
File functions: safe_file_name()

generateUserFilenameUID()

isPathWhitelisted()

get_checksum()
General functions: escape_command_args()

run_command()

run_external()

error_alert()

xml_entities()

get_xml_entity_at_index_0()

sanitize_char()

format_display_field()

format_string_more_link()

sortmulti()

draw_performance_footer()

sql_affected_rows()

get_imagemagick_path()

get_utility_path()

get_executable_path()

truncate_cache_arrays()

txt2html()

is_html()

rs_setcookie()

get_editable_states()

validate_html()

generateURL()

tail()

move_array_element()

emptyiszero()

array_column()

get_slideshow_files_data()

form_value_display()

job_queue_add()

job_queue_update()

job_queue_delete()

job_queue_get_jobs()

job_queue_run_job()

user_set_usergroup()

generateSecureKey()

IsModal()

generateCSRFToken()

ResolveKB()

isValidCSRFToken()

generateFormToken()

generateAjaxToken()

enforcePostRequest()

findDuplicates()

is_resourcespace_upgrade_available()

get_recent_users()

check_script_last_ran()

trim_filename()

count_errors()

search_array_by_keyvalue()

bypass_permissions()

set_sysvar()

get_sysvar()

hook()

strip_tags_and_attributes()

show_pagetime()

get_debug_log_dir()

debug()

rcRmdir()

job_queue_get_job()

daily_stat()

job_queue_purge()

pagename()

text()

get_section_list()

resolve_user_agent()

get_ip()

get_inner_html_from_tag()

array_flip_by_value_key()

reshape_array_by_value_keys()

permission_j()

permission_negative_j()

cleanup_files()

is_int_loose()

ip_matches()

getval()

getvalescaped()

getuid()

escape_check()

unescape()

escape_check_array_values()

nicedate()

redirect()

trim_spaces()

trim_array()

tidylist()

tidy_trim()

average_length()

get_stats_activity_types()

get_stats_years()

newlines()

get_all_site_text()

get_site_text()

check_site_text_custom()

save_site_text()

string_similar()

formatfilesize()

filesize2bytes()

get_mime_type()

send_mail()

send_mail_phpmailer()

log_mail()

rs_quoted_printable_encode()

rs_quoted_printable_encode_subject()

pager()

send_statistics()

remove_extension()

verify_extension()

get_allowed_extensions()

get_allowed_extensions_by_type()

getAbsolutePath()

getFolderContents()

mb_basename()

strip_extension()

is_process_lock()

set_process_lock()

clear_process_lock()

filesize_unlimited()

strip_leading_comma()

convert()

get_temp_dir()

convert_path_to_url()
Language functions: lang_or_i18n_get_translated()

i18n_get_translated()

i18n_get_collection_name()

i18n_get_indexable()

i18n_get_translations()

str_replace_formatted_placeholder()

ucfirstletter()

ucfirstletter_callback()

normalize_keyword()

remove_accents()

seems_utf8()

http_get_preferred_language()

setLanguage()
Log functions: log_activity()

logScript()

resource_log_last_rows()

get_activity_log()

get_user_downloads()

log_node_changes()

log_search_event()
Login functions: perform_login()

generate_session_hash()

set_login_cookies()
Message functions: message_get()

message_add()

message_remove()

message_seen()

message_unseen()

message_seen_all()

message_purge()

message_send_unread_emails()

message_remove_related()

message_user_remove()

system_notification()
Migration functions: migrate_resource_type_field_check()

migrate_category_tree_to_nodes()

populate_resource_nodes()

migrate_filter()

random_char()

validateDatetime()

mix_date()

mix_text()

alter_data()

mix_url()

mix_filename()

mix_email()

safe_export()

get_export_tables()

edit_filter_to_restype_permission()
Node functions: compute_node_branch_path()

compute_nodes_by_parent()

get_resource_nodes_batch()

get_nodes_by_refs()

process_node_search_syntax_to_names()

set_node()

delete_node()

delete_nodes_for_resource_type_field()

get_node()

get_nodes()

is_parent_node()

get_tree_node_level()

get_root_node_by_leaf()

reorder_node()

reorder_nodes()

render_new_node_record()

get_node_order_by()

draw_tree_node_table()

node_field_options_override()

add_node_keyword()

remove_node_keyword()

remove_all_node_keyword_mappings()

check_node_indexed()

add_node_keyword_mappings()

remove_node_keyword_mappings()

add_resource_nodes()

add_resource_nodes_multi()

get_resource_nodes()

delete_resource_nodes()

delete_resource_nodes_multi()

delete_all_resource_nodes()

copy_resource_nodes()

get_nodes_from_keywords()

update_resource_node_hitcount()

copy_resource_type_field_nodes()

get_parent_nodes()

get_nodes_count()

extract_node_options()

get_node_by_name()

get_node_id()

node_name_comparator()

node_orderby_comparator()

get_node_elements()

get_node_tree()

get_tree_strings()
PDF functions: get_pdf_template_path()

generate_pdf()

get_template_path()

process_template()

process_if_statements()

resolve_pdf_language()

get_pdf_templates()
Plugin functions: config_multi_archive_select()

config_add_multi_archive_select()

activate_plugin()

deactivate_plugin()

purge_plugin_config()

get_plugin_yaml()

config_json_encode()

config_encode()

get_plugin_config()

set_plugin_config()

is_plugin_activated()

handle_rsc_upload()

display_rsc_upload()

config_gen_setup_post()

config_gen_setup_html()

config_section_header()

config_add_section_header()

config_add_text_list_input()

config_multi_select()

config_add_multi_select()

config_single_user_select()

config_add_single_user_select()

config_multi_user_select()

config_add_multi_user_select()

config_single_group_select()

config_add_single_group_select()

config_multi_group_select()

config_add_multi_group_select()

config_multi_ftype_select()

config_add_multi_ftype_select()

config_single_rtype_select()

config_add_single_rtype_select()

config_multi_rtype_select()

config_add_multi_rtype_select()

config_db_single_select()

config_add_db_single_select()

config_db_multi_select()

config_add_db_multi_select()

config_add_hidden()

config_text_field()

config_userselect_field()

config_field_select()

config_boolean_field()

config_custom_select_multi()

config_custom_select()

get_plugin_css()

plugin_activate_for_setup()

include_plugin_config()

register_plugin_language()

get_plugin_path()

register_plugin()
Render functions: render_trash()

render_browse_bar()

generate_browse_bar_item()

render_help_link()

render_question_div()

render_custom_fields()

render_selected_resources_counter()

render_edit_selected_btn()

render_clear_selected_btn()

render_selected_collection_actions()

render_user_collection_select()

render_csrf_data_attributes()

check_display_condition()

has_browsebar()

display_upload_options()

display_field_data()

render_resource_lock_link()

EditNav()

SaveAndClearButtons()

UpdateResultOrder()

display_size_option()

show_upgrade_in_progress()

render_audio_download_link()

render_table()

render_array_in_table_cells()

render_new_featured_collection_cta()

render_featured_collection_category_selector()

render_featured_collections()

render_featured_collection()

DrawOption()

render_featured_collections_category_permissions()

render_top_page_error_style()

render_search_field()

render_sort_order()

render_dropdown_option()

render_actions()

render_user_group_multi_select()

render_user_group_select()

render_user_group_checkbox_select()

render_text_question()

render_split_text_question()

render_dropdown_question()

render_access_key_tr()

is_field_displayed()

display_multilingual_text_field()

display_field()

render_date_range_field()

renderBreadcrumbs()

renderCallToActionTile()

renderSocialMediaShareLinksForUrl()

renderLockButton()

render_resource_image()

calculate_image_display()

render_share_options()

render_field_selector_question()

render_filter_bar_button()

render_upload_here_button()
Reporting functions: get_report_name()

get_reports()

do_report()

create_periodic_email()

send_periodic_report_emails()

delete_periodic_report()

unsubscribe_user_from_periodic_report()

get_translated_activity_type()
Request functions: get_request()

get_user_requests()

save_request()

get_requests()

email_collection_request()

managed_collection_request()

email_resource_request()

get_valid_custom_fields()

gen_custom_fields_html_props()

process_custom_fields_submission()
Research functions: send_research_request()

get_research_requests()

get_research_request()

save_research_request()

get_research_request_collection()

set_research_collection()
Slideshow functions: set_slideshow()

delete_slideshow()

reorder_slideshow_images()

get_slideshow_image_file_path()
Theme permission functions: getThemePathPerms()
User functions: check_password()

resolve_users()

check_access_key()

check_access_key_collection()

make_username()

get_registration_selectable_usergroups()

open_access_to_user()

open_access_to_group()

resolve_open_access()

remove_access_to_user()

user_email_exists()

resolve_user_emails()

create_password_reset_key()

get_rs_session_id()

get_notification_users()

verify_antispam()

check_share_password()

get_users_from_permission_lookup()

offset_user_local_timezone()

checkPermission_anonymoususer()

checkPermission_dashadmin()

checkPermission_dashuser()

checkPermission_dashmanage()

checkPermission_dashcreate()

checkperm()

checkperm_user_edit()

internal_share_access()

validate_user()

setup_user()

get_users()

get_users_with_permission()

get_user_by_email()

get_user_by_username()

get_usergroups()

get_usergroup()

get_user()

save_user()

email_user_welcome()

email_reset_link()

auto_create_user_account()

email_user_request()

new_user()

get_active_users()

change_password()

make_password()

bulk_mail()

get_user_log()

resolve_userlist_groups()

resolve_userlist_groups_smart()

remove_groups_smart_from_userlist()
Video functions: get_video_resolution()
Database functions: sql_is_null_or_eq_val()

sql_null_or_val()

errorhandler()

db_use_multiple_connection_modes()

db_set_connection_mode()

db_get_connection_mode()

db_clear_connection_mode()

sql_connect()

db_begin_transaction()

sql_query_prepared()

db_end_transaction()

db_rollback_transaction()

sql_query()

sql_value()

sql_array()

sql_insert_id()

get_query_cache_location()

clear_query_cache()

check_db_structs()

CheckDBStruct()

sql_limit()
Metadata functions: check_order_by_in_table_joins()

runFitsForFile()

getFitsMetadataFieldValue()

extractFitsMetadata()

check_date_format()

check_date_parts()

check_view_display_condition()

update_fieldx()
Resource functions: get_resource_path()

get_resource_data()

put_resource_data()

create_resource()

update_hitcount()

save_resource_data()

set_resource_defaults()

save_resource_data_multi()

append_field_value()

remove_keyword_mappings()

remove_keyword_from_resource()

add_keyword_mappings()

add_keyword_to_resource()

remove_all_keyword_mappings_for_field()

update_field()

()

email_resource()

delete_resource()

get_resource_type_field()

get_resource_field_data()

get_resource_field_data_batch()

get_resource_types()

get_resource_top_keywords()

clear_resource_data()

get_max_resource_ref()

get_resource_ref_range()

copy_resource()

resource_log()

get_resource_log()

get_resource_type_name()

get_resource_custom_access()

get_resource_custom_access_users_usergroups()

save_resource_custom_access()

get_custom_access()

get_themes_by_resource()

update_resource_type()

relate_to_array()

get_exiftool_fields()

createTempFile()

stripMetadata()

write_metadata()

delete_exif_tmpfile()

update_resource()

import_resource()

get_alternative_files()

add_alternative_file()

delete_alternative_file()

get_alternative_file()

save_alternative_file()

user_rating_save()

process_notify_user_contributed_submitted()

notify_user_contributed_submitted()

notify_user_contributed_unsubmitted()

get_field()

get_field_options_with_stats()

save_field_options()

get_resources_matching_keyword()

get_keyword_from_option()

add_field_option()

get_resource_access()

get_custom_access_user()

edit_resource_external_access()

get_resource_data_batch()

resource_download_allowed()

get_edit_access()

filter_match()

log_diff()

get_metadata_templates()

get_resource_collections()

download_summary()

check_use_watermark()

autocomplete_blank_fields()

get_resource_files()

reindex_resource()

get_page_count()

update_disk_usage()

update_disk_usage_cron()

get_total_disk_usage()

overquota()

notify_user_resources_approved()

get_original_imagesize()

generate_resource_access_key()

get_resource_external_access()

delete_resource_access_key()

resource_type_config_override()

update_archive_status()

delete_resources_in_collection()

update_related_resource()

can_share_resource()

delete_resource_custom_access_usergroups()

truncate_join_field_value()

get_video_snapshots()

resource_file_readonly()

delete_resource_custom_user_access()

get_video_info()

copyAllDataToResource()

copyResourceDataValues()

copy_locked_data()

copy_locked_fields()

copyRelatedResources()

process_edit_form()

update_timestamp()

get_extension()

get_last_resource_edit_array()

get_default_archive_state()

save_original_file_as_alternative()

replace_resource_file()

get_resource_all_image_sizes()

sanitize_date_field_input()

download_link_generate_key()

download_link_check_key()

filter_check()

update_resource_keyword_hitcount()

copy_hitcount_to_live()

get_image_sizes()

get_preview_quality()

get_related_resources()

get_field_options()

get_data_by_field()

get_resources_by_resource_data_value()

get_all_image_sizes()

image_size_restricted_access()

get_fields()

get_hidden_indexed_fields()

get_category_tree_fields()

get_OR_fields()

get_nopreview_icon()

purchase_set_size()

payment_set_complete()

get_indexed_resource_type_fields()

get_resource_type_fields()

notify_resource_change()

add_verbatim_keywords()

metadata_field_edit_access()

get_download_filename()

get_resource_type_from_extension()

canSeePreviewTools()

checkPreviewToolsOptionUniqueness()

alt_is_ffmpeg_alternative()

create_resource_type_field()

metadata_field_view_access()

get_workflow_states()

delete_resource_type_field()

tab_names()

get_resource_table_joins()

update_resource_lock()

get_resource_lock_message()
Search functions: get_search_default_restypes()

get_selectedtypes()

render_advanced_search_buttons()

resolve_soundex()

suggest_refinement()

get_advanced_search_fields()

get_advanced_search_collection_fields()

search_form_to_search_query()

refine_searchstring()

compile_search_actions()

search_filter()

search_special()

resolve_nodes_from_string()

rebuild_specific_field_search_from_node()

search_get_previews()

get_upload_here_selected_nodes()

get_default_search_states()

get_filter_sql()

split_keywords()

cleanse_string()

resolve_keyword()

add_partial_index()

highlightkeywords()

str_highlight()

sorthighlights()

get_suggested_keywords()

get_related_keywords()

get_grouped_related_keywords()

save_related_keywords()

get_simple_search_fields()

get_fields_for_search_display()

get_filters()

get_filter()

get_filter_rules()

get_filter_rule()

save_filter()

save_filter_rule()

delete_filter()

delete_filter_rule()

copy_filter()

update_search_from_request()

ResourceSpace software design principles

When developing ResourceSpace core and plugins please always consider the below principals.

The existing codebase doesn't always adhere to these principals - the contributions from many different developers over the years have meant a mix of coding styles - but the important thing is that we're always moving in the right direction by refactoring as we see fit and peer reviewing new code.

KISS

"Keep It Simple Stupid". A design principle noted by the U.S. Navy in 1960. Don't implement a complex solution when a simple one will suffice. Likewise, don't introduce new technology when reuse of existing technology within the software will suffice. You might be itching to try out a new library, PHP feature, programming paradigm, etc. but in most cases you'll just be adding a steeper learning curve for new developers and making the software more complex to support.

Do one thing and do it well

In the same vein as KISS above. A UNIX design philosophy that for ResourceSpace applies to functions, pages and scripts. We should avoid having a multi-purpose page/function. A series of smaller dedicated and focussed functions/pages are preferable to a large and complex one.

It's far easier to debug a small function with minimal inputs than a 1000+ line behemoth.

YAGNI

"You Aren't Going to Need It!". This refers to the tendency of programmers to add in placeholders, stubs, etc. to build groundwork for future functionality. In the majority of cases this additional development will never happen, usually because the functionality developed was good enough for the majority of use cases. Extra code that's not needed just adds to the "technical debt" of the project, making it more complex to support.

If it's not needed, don't build it.

DRY

"Don't Repeat Yourself". If your code has sections that are identical or very similar to each other the chances are you're doing something wrong. Break it out to a function and handle the differences via parameters.

Duplication is another way to add technical debt. Future changes must now be made in several places rather than just one, and the code is larger and more complex to support.

We set a low threshold for this - even repeating the same block twice means we should break it out to a function (or use a loop or other structure) to avoid duplication entirely.

Knowledge Base