{"id":17693097,"url":"https://github.com/toolstack/toolstack-wp-utilities","last_synced_at":"2025-03-30T23:13:00.742Z","repository":{"id":27987667,"uuid":"31481631","full_name":"toolstack/ToolStack-WP-Utilities","owner":"toolstack","description":null,"archived":false,"fork":false,"pushed_at":"2020-08-17T18:27:06.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-06T04:41:22.587Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/toolstack.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-01T00:16:20.000Z","updated_at":"2020-08-17T18:27:08.000Z","dependencies_parsed_at":"2022-08-26T11:20:22.606Z","dependency_job_id":null,"html_url":"https://github.com/toolstack/ToolStack-WP-Utilities","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstack%2FToolStack-WP-Utilities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstack%2FToolStack-WP-Utilities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstack%2FToolStack-WP-Utilities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/toolstack%2FToolStack-WP-Utilities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/toolstack","download_url":"https://codeload.github.com/toolstack/ToolStack-WP-Utilities/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246390873,"owners_count":20769478,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-24T13:44:11.643Z","updated_at":"2025-03-30T23:13:00.720Z","avatar_url":"https://github.com/toolstack.png","language":"PHP","readme":"# ToolStack WP Utilities\n\nContributors: Greg Ross\nURI: http://toolstack.com  \nLicense: GPLv2  \n\n## Description ##\n\nA utility class of functions for use in WordPress plugins.  \n\n# License #\n\t\nThis code is released under the GPL v2, see license.txt for details.\n\n## Documentation ##\n\nHave you written a WordPress plugin before?  More than one?  Found yourself rewriting the same code each time you do?\n\nMe to.  So here's a library of functions I found myself rewriting each time, extracted to it's own class and made available for everyone!\n\nAt the moment the library covers several broad catagroies:\n\n- Plugin Options\n- User Options\n- Debugging\n- Options Display\n\nThis list will grow over time.\n\n### Installation ###\n\nThe first thing you need to do is download the library and put it in your plugin directory.  Once you have that done you'll need to include it in your source code.\n\nTo do so, add the following lines:\n\n\tinclude_once( 'ToolStack-WP-Utilities.class.php' );\n\t$TSU = new ToolStack_WP_Utilities_V2_7( 'my_plugin_slug', __FILE__ );\n\t\nThis should be done early in your plugin so you have access to the utilities as soon as possible.\n\nThere are three items to note in the above code:\n\n1. The class name includes the version number.  This is done to avoid version conflicts as others will have included the class in their plugins as well.\n2. 'my_plugin_slug' is used in several places inside the code and should be unique, contain no spaces and not be version dependent.  If it is left blank, the lowercase plugin install directory will be used.\n3. The second parameter should be the plugin's primary file name, this is used to set the plugin_dir and plugin_url variables.  You can leave it blank and it will use the utilities file name, but this may cause unexpected results if the class has already been loaded by another plugin.\n4. $TSU should be replaced with a unique vairable name for your plugin.\n\n### Class creation ###\n\nDuring the class creation there are three things done:\n\n1. The plugin slug is determined.\n2. The plugin_dir and plugin_url public variables are set.\n3. The plugin options are loaded from the WordPress options table.\n\nThe plugin slug is used as the key name for the options for the plugin.\n\n### Plugin Options ###\n\nWordPress has a built in set of functions for handling options (get_option, update_option, etc.) and they work well.  However once you get beyond a certain point, the number of options in a plugin can become unwieldly with the format that WordPress gives you.\n\nInstead, I (like many other plugin authors) use a single option for my plugins which stores an array.  Managing this array can be cumbersome and so the ToolStack WP Utilities implements several functions to simplify the process:\n\n- load_options()\n- get_option( $option, $default )\n- update_option( $option, $value ) \n- store_option( $option, $value ) \n- save_options()\n- isset_option()\n\nThe first three mimic the built in WordPress functions and are drop in replacements, so you can simply add $TSU-\u003e to the front of the WordPress functions and everything will work as expected.\n\nThe difference is that instead of saving the option as a unqiue option in the WordPress options table, the option will be stored as the key name or an array stored as the plugin slug.\n\nFor example, if you use the WordPress function like this:\n\n\tupdate_option( 'my_plugin_setting_one', true );\n\tupdate_option( 'my_plugin_setting_two', false );\n\t\nYou would have a two rows in the wp_options table one with the option name being 'my_plugin_setting_one' and the second with the option name bieng 'my_plugin_setting_two'.\n\nUsing the library instead:\n\n\t$TSU-\u003eupdate_option( 'setting_one', true );\n\t$TSU-\u003eupdate_option( 'setting_two', false );\n\nYou will have a single row in the WordPress options table with the option name being 'my_plugin_slug' (from when you created the $TSU object), the option value will be an array with two items, setting_one and setting_two.\n\nThe last three functions provide additional functionality:\n\n- store_option(): update_option() will immediately write out the new array to the database, however if your updating a lot of settings sequentially you may not want to do this so store_option() will update the value in memory but not write it to the database.\n- save_options(): Used in conjunction with store_option(), once you are ready, save_options() will write out the plugin options to the database.\n- isset_option(): Direct access to the options array is not a good idea so there needs to be a way to tell if an option has been set.  This function will return work just like isset() but for the assoiated option name.\n\n### User Options ###\n\nWordPress has some built in functions for handling user settings just like it does for global options and it has the same issues with them as well.\n\nThis set of functions takes the same approach as the plugin option for user options:\n\n- set_user_id( $id )\n- load_user_options( $user_id )\n- get_user_option( $option, $default )\n- update_user_option( $option, $value ) \n- get_the_author_meta( $option, $user_id )\n- update_user_meta( $user_id, $option, $default )\n- store_user_option( $option, $value ) \n- save_user_options() \n- isset_user_option( $option ) \n\nThe user option code is a little more complex than the plugin option code.  This has a few sources:\n\n- You need to load user options later in your plugin, after the user had been authenticated with WordPress.\n- You may want to load more than one set of user options\n\nThe first two functions handle the loading of user options:\n\n- set_user_id(): This will set the current user to get options for to the passed in WordPress user id.\n- load_user_options(): This will load the user options in to memory.  If no user id is set or passed in, the current user will be the default.\n\nThe next two functions mimic the plugin options functions above:\n\n- get_user_option(): This will retrieve the option setting for the user.\n- update_user_option(): Ths will update the option setting for the user.\n\nThe next two functions are drop in replacements for the WordPress equivalents, but of course use the array instead of individual settings:\n\n- get_the_author_meta( $option, $user_id )\n- update_user_meta( $user_id, $option, $default )\n\nAnd the final three accomplish the same task as their plugin options counterparts, see above for details:\n\n- store_user_option() \n- save_user_options() \n- isset_user_option() \n\n### Debugging ###\n\nOne of the challenges with WordPress is getting good debugging information out of the system, the help out there are several functions available:\n\n- print_r_html( $var, $string )\n- var_dump_html()\n- var_export_html( $var, $string = false )\n- set_line_type( $type )\n- set_debug_log( $file )\n- open_debug_log()\n- write_debug_log( $text )\n- write_debug_log_var( $var )\n- close_debug_log() \n\nThe first three functions mimic the functionality of their PHP counterparts with the exception that they output html formatted text instead of plain text.\n\nThe rest of the functions all relate to writting a debug log for your plugin:\n\n- set_line_type(): By default the library uses Unix style line terminiation (\\n), but you can set it to anything you want with this function.\n- set_debug_log( $file ): By default the debug log will be stored in sys_get_temp_dir() . '/debug.txt'.  This lets you set a different location and filename.\n- open_debug_log(): You probably don't need to ever call this function as the first call to any of the writing functions will call this function for you.  However if for some reason you do, this will open the debug log for appending.\n- write_debug_log( $text ): Write out a line of text to the debug log, it will be formated as: [YYYY-MM-DD HH:MM:SS] Text\n- write_debug_log_var( $var ): Write out a variable to the debug log, this will indent it correctly to align past the timestamp.\n- close_debug_log(): Another function you probably won't use as the debug log is closed when the class is destroyed.\n\n### Options Display ###\n\nA common task in plugins is to display a series of options in a table.  Hand coding the html is doable and on frequently used pages probably even preferable, but kind of a pain, so this funciton automates the task:\n\n- generate_options_table( $options )\n\nAt the moment supported option types are:\n\n- Title: An H3 formatted row that spans the entire table.\n- Description: A span value above the setting with the \"description\" class.\n- Boolean: A checkbox.\n- Image: An image link (same as text at the moment).\n- Hidden: This adds a hidden input tag.\n- Select: A select with options.\n- Static: A static text line.\n- Text: A text box, either a simple one line input or a text area.\n\n$options is an array or arrays as follows:\n\n\ttype: They type (all lower case). \n\tdesc: The description to display to the left of the field.\n\tsize: The size (width) of the field.\n\tsetting: The setting to set as the default value.\n\toption_list: For select's this is the option list, this is a single text line that will be placed between the \u003cselect\u003e and \u003c/select\u003e tags.\n\theight: For text fields only, this will use a textarea if set to a value greater than 1.\n\tpost: for text fields this will display some extra html/text after the input box (for showing defaults, etc.).\n\nSome examples\n\t\n\t$options['id'] \t\t\t\t= array( 'type' =\u003e 'static', 'desc' =\u003e 'Player ID', 'size' =\u003e 10, 'setting' =\u003e 'Greg' );\n\t$options['email']\t\t\t= array( 'type' =\u003e 'text', 'desc' =\u003e 'E-Mail', 'setting' =\u003e $user_email) );\n\t$options['hidden']\t\t\t= array( 'type' =\u003e 'bool', 'desc' =\u003e 'Hidden', 'setting' =\u003e $hidden) );\n\n\t$TSU-\u003egenerate_options_table( $options );\n\n## Frequently Asked Questions ##\n\n# None #\n\nTo be completed.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolstack%2Ftoolstack-wp-utilities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoolstack%2Ftoolstack-wp-utilities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoolstack%2Ftoolstack-wp-utilities/lists"}