From 1c10119f2bff855e1f2bef097d36a3bcd54a0bd0 Mon Sep 17 00:00:00 2001 From: Christian Wach Date: Wed, 10 Oct 2018 14:47:58 +0100 Subject: [PATCH] Give comments and docblocks some TLC --- civicrm.php | 786 ++++++++++++++++---------- includes/civicrm.basepage.php | 246 ++++---- includes/civicrm.shortcodes.modal.php | 76 +-- includes/civicrm.shortcodes.php | 381 +++++++------ includes/civicrm.users.php | 142 +++-- uninstall.php | 4 +- 6 files changed, 962 insertions(+), 673 deletions(-) diff --git a/civicrm.php b/civicrm.php index 241fd5f..4f2500e 100644 --- a/civicrm.php +++ b/civicrm.php @@ -65,35 +65,35 @@ */ -// this file must not accessed directly +// This file must not accessed directly if ( ! defined( 'ABSPATH' ) ) exit; -// set version here: when it changes, will force JS to reload +// Set version here: when it changes, will force JS to reload define( 'CIVICRM_PLUGIN_VERSION', '4.7' ); -// store reference to this file +// Store reference to this file if (!defined('CIVICRM_PLUGIN_FILE')) { define( 'CIVICRM_PLUGIN_FILE', __FILE__ ); } -// store URL to this plugin's directory +// Store URL to this plugin's directory if (!defined( 'CIVICRM_PLUGIN_URL')) { define( 'CIVICRM_PLUGIN_URL', plugin_dir_url(CIVICRM_PLUGIN_FILE) ); } -// store PATH to this plugin's directory +// Store PATH to this plugin's directory if (!defined( 'CIVICRM_PLUGIN_DIR')) { define( 'CIVICRM_PLUGIN_DIR', plugin_dir_path(CIVICRM_PLUGIN_FILE) ); } -/** +/* * The constant CIVICRM_SETTINGS_PATH is also defined in civicrm.config.php and * may already have been defined there - e.g. by cron or external scripts. */ if ( !defined( 'CIVICRM_SETTINGS_PATH' ) ) { - /** + /* * Test where the settings file exists. * * If the settings file is found in the 4.6 and prior location, use that as @@ -112,55 +112,84 @@ } -// test if Civi is installed +// Test if CiviCRM is installed if ( file_exists( CIVICRM_SETTINGS_PATH ) ) { define( 'CIVICRM_INSTALLED', TRUE ); } else { define( 'CIVICRM_INSTALLED', FALSE ); } -// prevent CiviCRM from rendering its own header +// Prevent CiviCRM from rendering its own header define( 'CIVICRM_UF_HEAD', TRUE ); /** - * Define CiviCRM_For_WordPress Class + * Define CiviCRM_For_WordPress Class. + * + * @since 4.4 */ class CiviCRM_For_WordPress { - /** - * Declare our properties + * Plugin instance. + * + * @since 4.4 + * @access private + * @var object $instance The plugin instance. */ + private static $instance; /** - * @var CiviCRM_For_WordPress + * Plugin context (broad). + * + * @since 4.4 + * @access public + * @var bool $in_wordpress The broad plugin context. */ - private static $instance; - - // plugin context (broad) static $in_wordpress; - // plugin context (specific) + /** + * Plugin context (specific). + * + * @since 4.4 + * @access public + * @var str $context The specific plugin context. + */ static $context; /** - * @var CiviCRM_For_WordPress_Shortcodes + * Shortcodes management object. + * + * @since 4.4 + * @access public + * @var object CiviCRM_For_WordPress_Shortcodes The shortcodes management object. */ public $shortcodes; /** - * @var CiviCRM_For_WordPress_Shortcodes_Modal + * Modal dialog management object. + * + * @since 4.4 + * @access public + * @var object CiviCRM_For_WordPress_Shortcodes_Modal The modal dialog management object. */ public $modal; /** - * @var CiviCRM_For_WordPress_Basepage + * Basepage management object. + * + * @since 4.4 + * @access public + * @var object CiviCRM_For_WordPress_Basepage The basepage management object. */ public $basepage; /** - * @var CiviCRM_For_WordPress_Users + * User management object. + * + * @since 4.4 + * @access public + * @var object CiviCRM_For_WordPress_Users The user management object. */ public $users; @@ -174,39 +203,44 @@ class CiviCRM_For_WordPress { * Getter method which returns the CiviCRM instance and optionally creates one * if it does not already exist. Standard CiviCRM singleton pattern. * - * @return object CiviCRM plugin instance + * @since 4.4 + * + * @return object CiviCRM_For_WordPress The CiviCRM plugin instance. */ public static function singleton() { - // if it doesn't already exist... + // Create instance if it doesn't already exist if ( ! isset( self::$instance ) ) { - - // create it self::$instance = new CiviCRM_For_WordPress; self::$instance->setup_instance(); - } - // return existing instance + // Return instance return self::$instance; } /** - * Dummy instance constructor + * Dummy instance constructor. + * + * @since 4.4 */ function __construct() {} /** - * Dummy magic method to prevent CiviCRM_For_WordPress from being cloned + * Dummy magic method to prevent CiviCRM_For_WordPress from being cloned. + * + * @since 4.4 */ public function __clone() { _doing_it_wrong( __FUNCTION__, __( 'Only one instance of CiviCRM_For_WordPress please', 'civicrm' ), '4.4' ); } /** - * Dummy magic method to prevent CiviCRM_For_WordPress from being unserialized + * Dummy magic method to prevent CiviCRM_For_WordPress from being unserialized. + * + * @since 4.4 */ public function __wakeup() { _doing_it_wrong( __FUNCTION__, __( 'Please do not serialize CiviCRM_For_WordPress', 'civicrm' ), '4.4' ); @@ -214,54 +248,58 @@ public function __wakeup() { /** - * Method that is called only when CiviCRM plugin is activated - * In order for other plugins to be able to interact with Civi's activation, - * we wait until after the activation redirect to perform activation actions + * Plugin activation. + * + * This method is called only when CiviCRM plugin is activated. In order for + * other plugins to be able to interact with Civi's activation, we wait until + * after the activation redirect to perform activation actions. * - * @return void + * @since 4.4 */ public function activate() { - // set a one-time-only option + // Set a one-time-only option add_option( 'civicrm_activation_in_progress', 'true' ); } /** - * Method that runs CiviCRM's plugin activation methods + * Run CiviCRM's plugin activation procedure. * - * @return void + * @since 4.4 */ public function activation() { - // if activating... + // If activating if ( is_admin() && get_option( 'civicrm_activation_in_progress' ) == 'true' ) { - // assign minimum capabilities for all WP roles and create 'anonymous_user' role + // Assign minimum capabilities for all WP roles and create 'anonymous_user' role $this->users->set_wp_user_capabilities(); - // set a one-time-only option to flag that we need to create a basepage - - // it will not update the option once it has been set to another value nor - // create a new option with the same name + /* + * Set a one-time-only option to flag that we need to create a basepage - + * it will not update the option once it has been set to another value nor + * create a new option with the same name. + */ add_option( 'civicrm_activation_create_basepage', 'true' ); - // change option so this method never runs again + // Change option so this method never runs again update_option( 'civicrm_activation_in_progress', 'false' ); } - // if activating and we still haven't created the basepage... + // If activating and we still haven't created the basepage if ( is_admin() && get_option( 'civicrm_activation_create_basepage' ) == 'true' && CIVICRM_INSTALLED ) { - // create basepage + // Create basepage add_action( 'wp_loaded', array( $this, 'create_wp_basepage' ) ); - // change option so this method never runs again + // Change option so this method never runs again update_option( 'civicrm_activation_create_basepage', 'done' ); } @@ -270,15 +308,17 @@ public function activation() { /** - * Method that is called only when CiviCRM plugin is deactivated - * In order for other plugins to be able to interact with Civi's activation, - * we need to remove the option that is set in activate() above + * Plugin deactivation. + * + * This method is called only when CiviCRM plugin is deactivated. In order for + * other plugins to be able to interact with Civi's activation, we need to + * remove any options that are set in activate() above. * - * @return void + * @since 4.4 */ public function deactivate() { - // delete options + // Delete options delete_option( 'civicrm_activation_in_progress' ); delete_option( 'civicrm_activation_create_basepage' ); @@ -286,13 +326,13 @@ public function deactivate() { /** - * Set up the CiviCRM plugin instance + * Set up the CiviCRM plugin instance. * - * @return void + * @since 4.4 */ public function setup_instance() { - // kick out if another instance is being inited + // Kick out if another instance is being inited if ( isset( self::$in_wordpress ) ) { wp_die( __( 'Only one instance of CiviCRM_For_WordPress please', 'civicrm' ) ); } @@ -300,14 +340,16 @@ public function setup_instance() { // Store context $this->civicrm_in_wordpress_set(); - // there is no session handling in WP hence we start it for CiviCRM pages - // except when running via WP-CLI which does not require sessions + /* + * There is no session handling in WP - hence we start it for CiviCRM pages + * except when running via WP-CLI which does not require sessions. + */ if ( empty( session_id() ) && ! ( defined( 'WP_CLI' ) && WP_CLI ) ) { session_start(); } if ( $this->civicrm_in_wordpress() ) { - // this is required for AJAX calls in WordPress admin + // This is required for AJAX calls in WordPress admin $_GET['noheader'] = TRUE; } @@ -315,22 +357,24 @@ public function setup_instance() { $_GET['civicrm_install_type'] = 'wordpress'; } - // get classes and instantiate + // Get classes and instantiate $this->include_files(); - // do plugin activation + // Do plugin activation $this->activation(); - // register all hooks + // Register all hooks $this->register_hooks(); - // notify plugins + // Notify plugins do_action( 'civicrm_instance_loaded' ); } /** + * Set broad CiviCRM context. + * * Setter for determining if CiviCRM is currently being displayed in WordPress. * This becomes true whe CiviCRM is called in the following contexts: * @@ -338,13 +382,13 @@ public function setup_instance() { * (b) when CiviCRM content is being displayed on the front-end via wpBasePage * (c) when an AJAX request is made to CiviCRM * - * It is NOT true when CiviCRM is called via a shortcode + * It is NOT true when CiviCRM is called via a shortcode. * - * @return void + * @since 4.4 */ public function civicrm_in_wordpress_set() { - // store + // Store self::$in_wordpress = ( isset( $_GET['page'] ) && $_GET['page'] == 'CiviCRM' ) ? TRUE : FALSE; } @@ -355,17 +399,28 @@ public function civicrm_in_wordpress_set() { * * @see $this->civicrm_in_wordpress_set() * - * @return bool $in_wordpress True if Civi is displayed in WordPress, false otherwise + * @since 4.4 + * + * @return bool $in_wordpress True if CiviCRM is displayed in WordPress, false otherwise. */ public function civicrm_in_wordpress() { - // already stored + /** + * Allow broad context to be filtered. + * + * @since 4.4 + * + * @param bool $in_wordpress True if CiviCRM is displayed in WordPress, false otherwise. + * @return bool $in_wordpress True if CiviCRM is displayed in WordPress, false otherwise. + */ return apply_filters( 'civicrm_in_wordpress', self::$in_wordpress ); } /** + * Set specific CiviCRM context. + * * Setter for determining how CiviCRM is currently being displayed in WordPress. * This can be one of the following contexts: * @@ -374,36 +429,46 @@ public function civicrm_in_wordpress() { * (c) when a "non-page" request is made to CiviCRM * (d) when CiviCRM is called via a shortcode * - * The following codes correspond to the different contexts + * The following codes correspond to the different contexts: * * (a) 'admin' * (b) 'basepage' * (c) 'nonpage' * (d) 'shortcode' * - * @param string $context - * One of the four context codes above - * @return void + * @since 4.4 + * + * @param string $context One of the four context codes above. */ public function civicrm_context_set( $context ) { - // store + // Store self::$context = $context; } /** + * Get specific CiviCRM context. + * * Getter for determining how CiviCRM is currently being displayed in WordPress. * * @see $this->civicrm_context_set() * - * @return string - * The context in which Civi is displayed in WordPress + * @since 4.4 + * + * @return string The context in which CiviCRM is displayed in WordPress. */ public function civicrm_context_get() { - // already stored + /** + * Allow specific context to be filtered. + * + * @since 4.4 + * + * @param bool $context The existing context in which CiviCRM is displayed in WordPress. + * @return bool $context The modified context in which CiviCRM is displayed in WordPress. + */ return apply_filters( 'civicrm_context', self::$context ); } @@ -415,25 +480,25 @@ public function civicrm_context_get() { /** - * Include files + * Include files. * - * @return void + * @since 4.4 */ public function include_files() { - // include users class + // Include users class include_once CIVICRM_PLUGIN_DIR . 'includes/civicrm.users.php'; $this->users = new CiviCRM_For_WordPress_Users; - // include shortcodes class + // Include shortcodes class include_once CIVICRM_PLUGIN_DIR . 'includes/civicrm.shortcodes.php'; $this->shortcodes = new CiviCRM_For_WordPress_Shortcodes; - // include shortcodes modal dialog class + // Include shortcodes modal dialog class include_once CIVICRM_PLUGIN_DIR . 'includes/civicrm.shortcodes.modal.php'; $this->modal = new CiviCRM_For_WordPress_Shortcodes_Modal; - // include basepage class + // Include basepage class include_once CIVICRM_PLUGIN_DIR . 'includes/civicrm.basepage.php'; $this->basepage = new CiviCRM_For_WordPress_Basepage; @@ -446,34 +511,34 @@ public function include_files() { /** - * Register hooks + * Register hooks. * - * @return void + * @since 4.4 */ public function register_hooks() { - // always add the common hooks + // Always add the common hooks $this->register_hooks_common(); - // when in WordPress admin... + // When in WordPress admin... if ( is_admin() ) { - // set context + // Set context $this->civicrm_context_set( 'admin' ); - // handle WP admin context + // Handle WP admin context $this->register_hooks_admin(); return; } - // go no further if Civi not installed yet + // Go no further if CiviCRM not installed yet if ( ! CIVICRM_INSTALLED ) return; - // when embedded via wpBasePage or AJAX call... + // When embedded via wpBasePage or AJAX call... if ( $this->civicrm_in_wordpress() ) { - /** + /* * Directly output CiviCRM html only in a few cases and skip WP templating: * * (a) when a snippet is set @@ -483,79 +548,79 @@ public function register_hooks() { */ if ( ! $this->is_page_request() ) { - // set context + // Set context $this->civicrm_context_set( 'nonpage' ); - // add core resources for front end + // Add core resources for front end add_action( 'wp', array( $this, 'front_end_page_load' ) ); - // echo all output when WP has been set up but nothing has been rendered + // Wcho all output when WP has been set up but nothing has been rendered add_action( 'wp', array( $this, 'invoke' ) ); return; } - // set context + // Set context $this->civicrm_context_set( 'basepage' ); - // if we get here, we must be in a wpBasePage context + // If we get here, we must be in a wpBasePage context $this->basepage->register_hooks(); return; } - // set context + // Set context $this->civicrm_context_set( 'shortcode' ); - // that leaves us with handling shortcodes, should they exist + // That leaves us with handling shortcodes, should they exist $this->shortcodes->register_hooks(); } /** - * Register hooks that must always be present + * Register hooks that must always be present. * - * @return void + * @since 4.4 */ public function register_hooks_common() { - // use translation files + // Use translation files add_action( 'plugins_loaded', array( $this, 'enable_translation' ) ); - // register user hooks + // Register user hooks $this->users->register_hooks(); } /** - * Register hooks to handle CiviCRM in a WordPress admin context + * Register hooks to handle CiviCRM in a WordPress admin context. * - * @return void + * @since 4.4 */ public function register_hooks_admin() { - // modify the admin menu + // Modify the admin menu add_action( 'admin_menu', array( $this, 'add_menu_items' ) ); - // set page title + // Set page title add_filter( 'admin_title', array( $this, 'set_admin_title' ) ); - // print CiviCRM's header + // Print CiviCRM's header add_action('admin_head', array( $this, 'wp_head' ), 50); - // if settings file does not exist, show notice with link to installer + // If settings file does not exist, show notice with link to installer if ( ! CIVICRM_INSTALLED ) { if ( isset( $_GET['page'] ) && $_GET['page'] == 'civicrm-install' ) { - // register hooks for installer page? + // Register hooks for installer page? } else { - // show notice + // Show notice add_action( 'admin_notices', array( $this, 'show_setup_warning' ) ); } } - // enable shortcode modal + // Enable shortcode modal $this->modal->register_hooks(); } @@ -567,9 +632,11 @@ public function register_hooks_admin() { /** - * Initialize CiviCRM + * Initialize CiviCRM. + * + * @since 4.4 * - * @return bool $success + * @return bool $success True if CiviCRM is initialized, false otherwise. */ public function initialize() { @@ -595,25 +662,25 @@ public function initialize() { exit(); } - // check for settings + // Check for settings if ( ! CIVICRM_INSTALLED ) { $error = FALSE; } elseif ( file_exists( CIVICRM_SETTINGS_PATH) ) { $error = include_once ( CIVICRM_SETTINGS_PATH ); } - // autoload + // Autoload require_once 'CRM/Core/ClassLoader.php'; CRM_Core_ClassLoader::singleton()->register(); - // get ready for problems + // Get ready for problems $installLink = admin_url() . "options-general.php?page=civicrm-install"; $docLinkInstall = "https://wiki.civicrm.org/confluence/display/CRMDOC/Installing+CiviCRM+for+WordPress"; $docLinkTrouble = "https://wiki.civicrm.org/confluence/display/CRMDOC/Installation+and+Upgrades"; $forumLink = "https://civicrm.stackexchange.com/"; - // construct message + // Construct message $errorMsgAdd = sprintf( __( 'Please review the WordPress Installation Guide and the Trouble-shooting page for assistance. If you still need help installing, you can often find solutions to your issue by searching for the error message in the installation support section of the community forum.', 'civicrm' ), $docLinkInstall, @@ -621,7 +688,7 @@ public function initialize() { $forumLink ); - // does install message get used? + // Does install message get used? $installMessage = sprintf( __( 'Click here for fresh install.', 'civicrm' ), $installLink @@ -632,20 +699,20 @@ public function initialize() { return FALSE; } - // access global defined in civicrm.settings.php + // Access global defined in civicrm.settings.php global $civicrm_root; - // this does pretty much all of the civicrm initialization + // This does pretty much all of the civicrm initialization if ( ! file_exists( $civicrm_root . 'CRM/Core/Config.php' ) ) { $error = FALSE; } else { $error = include_once ( 'CRM/Core/Config.php' ); } - // have we got it? + // Have we got it? if ( $error == FALSE ) { - // set static flag + // Set static flag $failure = TRUE; // FIX ME - why? @@ -663,27 +730,26 @@ public function initialize() { "

" . $errorMsgAdd . "

" ); - // won't reach here! + // Won't reach here! return FALSE; } - // set static flag + // Set static flag $initialized = TRUE; - // initialize the system by creating a config object + // Initialize the system by creating a config object $config = CRM_Core_Config::singleton(); - //print_r( $config ); die(); - // sync the logged in user with WP + // Sync the logged in user with WP global $current_user; if ( $current_user ) { - // sync procedure sets session values for logged in users + // Sync procedure sets session values for logged in users require_once 'CRM/Core/BAO/UFMatch.php'; CRM_Core_BAO_UFMatch::synchronize( - $current_user, // user object - FALSE, // do not update + $current_user, // User object + FALSE, // Do not update 'WordPress', // CMS $this->users->get_civicrm_contact_type('Individual') ); @@ -692,10 +758,14 @@ public function initialize() { } - // notify plugins + /** + * Broadcast that CiviCRM is now initialized. + * + * @since 4.4 + */ do_action( 'civicrm_initialized' ); - // success! + // Success! return TRUE; } @@ -707,25 +777,20 @@ public function initialize() { /** - * Load translation files + * Load translation files. + * * A good reference on how to implement translation in WordPress: * http://ottopress.com/2012/internationalization-youre-probably-doing-it-wrong/ * - * @return void + * @since 4.4 */ public function enable_translation() { - // not used, as there are no translations as yet + // Load translations load_plugin_textdomain( - - // unique name - 'civicrm', - - // deprecated argument - FALSE, - - // relative path to directory containing translation files - dirname( plugin_basename( __FILE__ ) ) . '/languages/' + 'civicrm', // Unique name + FALSE, // Deprecated argument + dirname( plugin_basename( __FILE__ ) ) . '/languages/' // Relative path to translation files ); @@ -733,19 +798,20 @@ public function enable_translation() { /** - * Adds menu items to WordPress admin menu - * Callback method for 'admin_menu' hook as set in register_hooks() + * Adds menu items to WordPress admin menu. + * + * Callback method for 'admin_menu' hook as set in register_hooks(). * - * @return void + * @since 4.4 */ public function add_menu_items() { $civilogo = file_get_contents( plugin_dir_path( __FILE__ ) . 'assets/civilogo.svg.b64' ); - // check for settings file + // Check for settings file if ( CIVICRM_INSTALLED ) { - // add top level menu item + // Add top level menu item $menu_page = add_menu_page( __( 'CiviCRM', 'civicrm' ), __( 'CiviCRM', 'civicrm' ), @@ -756,12 +822,12 @@ public function add_menu_items() { apply_filters( 'civicrm_menu_item_position', '3.904981' ) // 3.9 + random digits to reduce risk of conflict ); - // add core resources prior to page load + // Add core resources prior to page load add_action( 'load-' . $menu_page, array( $this, 'admin_page_load' ) ); } else { - // add top level menu item + // Add top level menu item $menu_page = add_menu_page( __( 'CiviCRM Installer', 'civicrm' ), __( 'CiviCRM Installer', 'civicrm' ), @@ -773,7 +839,7 @@ public function add_menu_items() { ); /* - // add scripts and styles like this + // Add scripts and styles like this add_action( 'admin_print_scripts-' . $options_page, array( $this, 'admin_installer_js' ) ); add_action( 'admin_print_styles-' . $options_page, array( $this, 'admin_installer_css' ) ); add_action( 'admin_head-' . $options_page, array( $this, 'admin_installer_head' ), 50 ); @@ -790,9 +856,9 @@ public function add_menu_items() { /** - * Callback method for add_options_page() that runs the CiviCRM installer + * Callback method for add_options_page() that runs the CiviCRM installer. * - * @return void + * @since 4.4 */ public function run_installer() { $civicrmCore = CIVICRM_PLUGIN_DIR . 'civicrm'; @@ -826,7 +892,7 @@ public function run_installer() { } } - // uses CIVICRM_PLUGIN_DIR instead of WP_PLUGIN_DIR + // Uses CIVICRM_PLUGIN_DIR instead of WP_PLUGIN_DIR $installFile = CIVICRM_PLUGIN_DIR . 'civicrm' . DIRECTORY_SEPARATOR . @@ -841,9 +907,9 @@ public function run_installer() { /** - * Callback method for missing settings file in register_hooks() + * Callback method for missing settings file in register_hooks(). * - * @return void + * @since 4.4 */ public function show_setup_warning() { @@ -862,9 +928,9 @@ public function show_setup_warning() { /** - * Create WordPress basepage and save setting + * Create WordPress basepage and save setting. * - * @return void + * @since 4.6 */ public function create_wp_basepage() { @@ -874,34 +940,34 @@ public function create_wp_basepage() { $config = CRM_Core_Config::singleton(); - // bail if we already have a basepage setting + // Bail if we already have a basepage setting if ( !empty( $config->wpBasePage ) ) { return; } - // default page slug, but allow overrides + // Default page slug, but allow overrides $slug = apply_filters( 'civicrm_basepage_slug', 'civicrm' ); - // get existing page with that slug + // Get existing page with that slug $page = get_page_by_path( $slug ); - // does it exist? + // Does it exist? if ( $page ) { - // we already have a basepage + // We already have a basepage $result = $page->ID; } else { - // create the basepage + // Create the basepage $result = $this->create_basepage( $slug ); } - // were we successful? + // Were we successful? if ( $result !== 0 AND !is_wp_error($result) ) { - // get the post object + // Get the post object $post = get_post( $result ); $params = array( @@ -909,7 +975,7 @@ public function create_wp_basepage() { 'wpBasePage' => $post->post_name, ); - // save the setting + // Save the setting civicrm_api3('setting', 'create', $params); } @@ -920,51 +986,53 @@ public function create_wp_basepage() { /** * Create a WordPress page to act as the CiviCRM base page. * - * @param string $slug The unique slug for the page - same as wpBasePage setting - * @return int|WP_Error The page ID on success. The value 0 or WP_Error on failure + * @since 4.6 + * + * @param string $slug The unique slug for the page - same as wpBasePage setting. + * @return int|WP_Error The page ID on success. The value 0 or WP_Error on failure. */ private function create_basepage( $slug ) { - // if multisite, switch to main site + // If multisite, switch to main site if ( is_multisite() && !is_main_site() ) { - // store this site + // Store this site $original_site = get_current_blog_id(); - // switch + // Switch global $current_site; switch_to_blog( $current_site->blog_id ); } - // define basepage + // Define basepage $page = array( 'post_status' => 'publish', 'post_type' => 'page', 'post_parent' => 0, 'comment_status' => 'closed', 'ping_status' => 'closed', - 'to_ping' => '', // quick fix for Windows - 'pinged' => '', // quick fix for Windows - 'post_content_filtered' => '', // quick fix for Windows - 'post_excerpt' => '', // quick fix for Windows + 'to_ping' => '', // Quick fix for Windows + 'pinged' => '', // Quick fix for Windows + 'post_content_filtered' => '', // Quick fix for Windows + 'post_excerpt' => '', // Quick fix for Windows 'menu_order' => 0, 'post_name' => $slug, ); - // default page title, but allow overrides + // Default page title, but allow overrides $page['post_title'] = apply_filters( 'civicrm_basepage_title', __( 'CiviCRM', 'civicrm' ) ); - // default content + // Default content $content = __( 'Do not delete this page. Page content is generated by CiviCRM.', 'civicrm' ); - // set, but allow overrides + // Set, but allow overrides $page['post_content'] = apply_filters( 'civicrm_basepage_content', $content ); - // insert the post into the database + // Insert the post into the database $page_id = wp_insert_post( $page ); - // switch back if we've switched + // Switch back if we've switched if ( isset( $original_site ) ) { restore_current_blog(); } @@ -981,16 +1049,16 @@ private function create_basepage( $slug ) { /** * Perform necessary stuff prior to CiviCRM's admin page being loaded * This needs to be a method because it can then be hooked into WP at the - * right time + * right time. * - * @return void + * @since 4.6 */ public function admin_page_load() { - // add resources for back end + // Add resources for back end $this->add_core_resources( FALSE ); - // check setting for path to wp-load.php + // Check setting for path to wp-load.php $this->add_wpload_setting(); } @@ -1021,7 +1089,7 @@ public function admin_page_load() { * To get the path to wp-load.php, use: * $path = CRM_Core_BAO_Setting::getItem('CiviCRM Preferences', 'wpLoadPhp'); * - * @return void + * @since 4.6.3 */ public function add_wpload_setting() { @@ -1029,20 +1097,20 @@ public function add_wpload_setting() { return; } - // get path to wp-load.php + // Get path to wp-load.php $path = ABSPATH . 'wp-load.php'; - // get the setting, if it exists + // Get the setting, if it exists $setting = CRM_Core_BAO_Setting::getItem('CiviCRM Preferences', 'wpLoadPhp'); - // if we don't have one, create it + // If we don't have one, create it if ( is_null( $setting ) ) { CRM_Core_BAO_Setting::setItem($path, 'CiviCRM Preferences', 'wpLoadPhp'); } - // is it different to the one we've stored? + // Is it different to the one we've stored? if ( $setting !== $path ) { - // yes - set new path (this could be because we've changed server or location) + // Yes - set new path (this could be because we've changed server or location) CRM_Core_BAO_Setting::setItem($path, 'CiviCRM Preferences', 'wpLoadPhp'); } @@ -1052,9 +1120,9 @@ public function add_wpload_setting() { /** * Perform necessary stuff prior to CiviCRM being loaded on the front end * This needs to be a method because it can then be hooked into WP at the - * right time + * right time. * - * @return void + * @since 4.6 */ public function front_end_page_load() { @@ -1063,24 +1131,26 @@ public function front_end_page_load() { return; } - // add resources for front end + // Add resources for front end $this->add_core_resources( TRUE ); - // merge CiviCRM's HTML header with the WordPress theme's header + // Merge CiviCRM's HTML header with the WordPress theme's header add_action( 'wp_head', array( $this, 'wp_head' ) ); - // set flag so this only happens once + // Set flag so this only happens once $frontend_loaded = TRUE; } /** - * Load only the CiviCRM CSS. This is needed because $this->front_end_page_load() - * is only called when there is a single Civi entity present on a page or archive - * and, whilst we don't want all the Javascript to load, we do want stylesheets + * Load only the CiviCRM CSS. * - * @return void + * This is needed because $this->front_end_page_load() is only called when + * there is a single CiviCRM entity present on a page or archive and, whilst + * we don't want all the Javascript to load, we do want stylesheets. + * + * @since 4.6 */ public function front_end_css_load() { @@ -1095,22 +1165,22 @@ public function front_end_css_load() { $config = CRM_Core_Config::singleton(); - // default custom CSS to standalone + // Default custom CSS to standalone $dependent = NULL; // Load core CSS if (!CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'disable_core_css')) { - // enqueue stylesheet + // Enqueue stylesheet wp_enqueue_style( 'civicrm_css', $config->resourceBase . 'css/civicrm.css', - NULL, // dependencies - CIVICRM_PLUGIN_VERSION, // version - 'all' // media + NULL, // Dependencies + CIVICRM_PLUGIN_VERSION, // Version + 'all' // Media ); - // custom CSS is dependent + // Custom CSS is dependent $dependent = array( 'civicrm_css' ); } @@ -1120,23 +1190,24 @@ public function front_end_css_load() { wp_enqueue_style( 'civicrm_custom_css', $config->customCSSURL, - $dependent, // dependencies - CIVICRM_PLUGIN_VERSION, // version - 'all' // media + $dependent, // Dependencies + CIVICRM_PLUGIN_VERSION, // Version + 'all' // Media ); } - // set flag so this only happens once + // Set flag so this only happens once $frontend_css_loaded = TRUE; } /** - * Add CiviCRM core resources + * Add CiviCRM core resources. + * + * @since 4.6 * - * @param bool $front_end True if on WP front end, false otherwise - * @return void + * @param bool $front_end True if on WP front end, false otherwise. */ public function add_core_resources( $front_end = TRUE ) { @@ -1147,21 +1218,22 @@ public function add_core_resources( $front_end = TRUE ) { $config = CRM_Core_Config::singleton(); $config->userFrameworkFrontend = $front_end; - // add CiviCRM core resources + // Add CiviCRM core resources CRM_Core_Resources::singleton()->addCoreResources(); } /** - * Merge CiviCRM's HTML header with the WordPress theme's header - * Callback from WordPress 'admin_head' and 'wp_head' hooks + * Merge CiviCRM's HTML header with the WordPress theme's header. + * + * Callback from WordPress 'admin_head' and 'wp_head' hooks. * - * @return void + * @since 4.4 */ public function wp_head() { - // CRM-11823 - If Civi bootstrapped, then merge its HTML header with the CMS's header + // CRM-11823 - If CiviCRM bootstrapped, then merge its HTML header with the CMS's header global $civicrm_root; if ( empty( $civicrm_root ) ) { return; @@ -1182,12 +1254,13 @@ public function wp_head() { /** - * Invoke CiviCRM in a WordPress context + * Invoke CiviCRM in a WordPress context. + * * Callback function from add_menu_page() * Callback from WordPress 'init' and 'the_content' hooks * Also called by shortcode_render() and _civicrm_update_user() * - * @return void + * @since 4.4 */ public function invoke() { @@ -1196,7 +1269,7 @@ public function invoke() { return; } - // bail if this is called via a content-preprocessing plugin + // Bail if this is called via a content-preprocessing plugin if ( $this->is_page_request() && !in_the_loop() && !is_admin() ) { return; } @@ -1205,10 +1278,12 @@ public function invoke() { return; } - // CRM-12523 - // WordPress has it's own timezone calculations - // Civi relies on the php default timezone which WP - // overrides with UTC in wp-settings.php + /* + * CRM-12523 + * WordPress has it's own timezone calculations + * CiviCRM relies on the php default timezone which WP + * overrides with UTC in wp-settings.php + */ $wpBaseTimezone = date_default_timezone_get(); $wpUserTimezone = get_option('timezone_string'); if ($wpUserTimezone) { @@ -1216,15 +1291,17 @@ public function invoke() { CRM_Core_Config::singleton()->userSystem->setMySQLTimeZone(); } - // CRM-95XX - // At this point we are calling a CiviCRM function - // WP always quotes the request, CiviCRM needs to reverse what it just did + /* + * CRM-95XX + * At this point we are calling a CiviCRM function + * WP always quotes the request, CiviCRM needs to reverse what it just did. + */ $this->remove_wp_magic_quotes(); // Code inside invoke() requires the current user to be set up $current_user = wp_get_current_user(); - /** + /* * Bypass synchronize if running upgrade to avoid any serious non-recoverable * error which might hinder the upgrade process. */ @@ -1232,52 +1309,53 @@ public function invoke() { $this->users->sync_user( $current_user ); } - // set flag + // Set flag $alreadyInvoked = TRUE; - // get args + // Get args $argdata = $this->get_request_args(); - // set dashboard as default if args are empty + // Set dashboard as default if args are empty if ( !isset( $_GET['q'] ) ) { $_GET['q'] = 'civicrm/dashboard'; $_GET['reset'] = 1; $argdata['args'] = array('civicrm', 'dashboard'); } - // do the business + // Do the business CRM_Core_Invoke::invoke($argdata['args']); - // restore WP's timezone + // Restore WP's timezone if ($wpBaseTimezone) { date_default_timezone_set($wpBaseTimezone); } - // restore WP's arrays + // Restore WP's arrays $this->restore_wp_magic_quotes(); - // notify plugins + // Notify plugins do_action( 'civicrm_invoked' ); } /** - * Non-destructively override WordPress magic quotes - * Only called by invoke() to undo WordPress default behaviour - * CMW: Should probably be a private method + * Non-destructively override WordPress magic quotes. + * + * Only called by invoke() to undo WordPress default behaviour. + * CMW: Should probably be a private method. * - * @return void + * @since 4.4 */ public function remove_wp_magic_quotes() { - // save original arrays + // Save original arrays $this->wp_get = $_GET; $this->wp_post = $_POST; $this->wp_cookie = $_COOKIE; $this->wp_request = $_REQUEST; - // reassign globals + // Reassign globals $_GET = stripslashes_deep($_GET); $_POST = stripslashes_deep($_POST); $_COOKIE = stripslashes_deep($_COOKIE); @@ -1287,15 +1365,16 @@ public function remove_wp_magic_quotes() { /** - * Restore WordPress magic quotes - * Only called by invoke() to redo WordPress default behaviour - * CMW: Should probably be a private method + * Restore WordPress magic quotes. * - * @return void + * Only called by invoke() to redo WordPress default behaviour. + * CMW: Should probably be a private method. + * + * @since 4.4 */ public function restore_wp_magic_quotes() { - // restore original arrays + // Restore original arrays $_GET = $this->wp_get; $_POST = $this->wp_post; $_COOKIE = $this->wp_cookie; @@ -1305,23 +1384,27 @@ public function restore_wp_magic_quotes() { /** - * Detect Ajax, snippet, or file requests + * Detect Ajax, snippet, or file requests. + * + * @since 4.4 * - * @return boolean True if request is for a CiviCRM page, false otherwise + * @return boolean True if request is for a CiviCRM page, false otherwise. */ public function is_page_request() { - // kick out if not CiviCRM + // Kick out if not CiviCRM if (!$this->initialize()) { return; } - // get args + // Get args $argdata = $this->get_request_args(); - // FIXME: It's not sustainable to hardcode a whitelist of all of non-HTML - // pages. Maybe the menu-XML should include some metadata to make this - // unnecessary? + /* + * FIXME: It's not sustainable to hardcode a whitelist of all of non-HTML + * pages. Maybe the menu-XML should include some metadata to make this + * unnecessary? + */ if (CRM_Utils_Array::value('HTTP_X_REQUESTED_WITH', $_SERVER) == 'XMLHttpRequest' || ($argdata['args'][0] == 'civicrm' && in_array($argdata['args'][1], array('ajax', 'file')) ) || !empty($_REQUEST['snippet']) @@ -1337,9 +1420,11 @@ public function is_page_request() { /** - * Get arguments and request string from $_GET + * Get arguments and request string from $_GET. + * + * @since 4.6 * - * @return array $argdata Array containing request arguments and request string + * @return array $argdata Array containing request arguments and request string. */ public function get_request_args() { @@ -1359,10 +1444,12 @@ public function get_request_args() { } /** - * Add CiviCRM's title to the header's + * Add CiviCRM's title to the header's <title> tag. + * + * @since 4.6 * - * @param string $title - * @return string + * @param string $title The title to set. + * @return string The computed title. */ public function set_admin_title($title) { global $civicrm_wp_title; @@ -1379,32 +1466,38 @@ public function set_admin_title($title) { /** - * Override a WordPress page title with the CiviCRM entity title - * Callback method for 'single_page_title' hook, always called from WP front-end + * Override a WordPress page title with the CiviCRM entity title. * - * @param string $post_title The title of the WordPress page or post - * @param object $post The WordPress post object the title applies to - * @return string $civicrm_wp_title The title of the CiviCRM entity + * Callback method for 'single_page_title' hook, always called from WP front-end. + * + * @since 4.6 + * + * @param string $post_title The title of the WordPress page or post. + * @param object $post The WordPress post object the title applies to. + * @return string $civicrm_wp_title The title of the CiviCRM entity. */ public function single_page_title( $post_title, $post ) { - // sanity check and override + // Sanity check and override global $civicrm_wp_title; if (!empty($civicrm_wp_title)) { return $civicrm_wp_title; } - // fallback + // Fallback return $post_title; } /** - * Remove edit link from page content - * Callback from 'edit_post_link' hook + * Remove edit link from page content. + * + * Callback from 'edit_post_link' hook. + * + * @since 4.6 * - * @return string Always empty + * @return string Always empty. */ public function clear_edit_post_link() { return ''; @@ -1412,39 +1505,45 @@ public function clear_edit_post_link() { /** - * Remove edit link in WP Admin Bar - * Callback from 'wp_before_admin_bar_render' hook + * Remove edit link in WP Admin Bar. * - * @return void + * Callback from 'wp_before_admin_bar_render' hook. + * + * @since 4.6 */ public function clear_edit_post_menu_item() { - // access object + // Access object global $wp_admin_bar; - // bail if in admin + // Bail if in admin if ( is_admin() ) return; - // remove the menu item from front end + // Remove the menu item from front end $wp_admin_bar->remove_menu( 'edit' ); } /** + * Get base URL. + * * Clone of CRM_Utils_System_WordPress::getBaseUrl() whose access is set to * private. Until it is public, we cannot access the URL of the basepage since - * CRM_Utils_System_WordPress::url() - * + * CRM_Utils_System_WordPress::url(). + * * 27-09-2016 * CRM-16421 CRM-17633 WIP Changes to support WP in it's own directory * https://wiki.civicrm.org/confluence/display/CRM/WordPress+installed+in+its+own+directory+issues * For now leave hard coded wp-admin references. - * TODO: remove wp-admin references and replace with admin_url() in the future. Look at best way to get path to admin_url + * TODO: remove wp-admin references and replace with admin_url() in the future. + * TODO: Look at best way to get path to admin_url. * - * @param bool $absolute Passing TRUE prepends the scheme and domain, FALSE doesn't - * @param bool $frontend Passing FALSE returns the admin URL - * @param $forceBackend Passing TRUE overrides $frontend and returns the admin URL + * @since 4.4 + * + * @param bool $absolute Passing TRUE prepends the scheme and domain, FALSE doesn't. + * @param bool $frontend Passing FALSE returns the admin URL. + * @param $forceBackend Passing TRUE overrides $frontend and returns the admin URL. * @return mixed|null|string */ public function get_base_url($absolute, $frontend, $forceBackend) { @@ -1458,7 +1557,7 @@ public function get_base_url($absolute, $frontend, $forceBackend) { } -} // class CiviCRM_For_WordPress ends +} // Class CiviCRM_For_WordPress ends /* @@ -1472,19 +1571,21 @@ public function get_base_url($absolute, $frontend, $forceBackend) { * The main function responsible for returning the CiviCRM_For_WordPress instance * to functions everywhere. * - * Use this function like you would a global variable, except without needing - * to declare the global. + * Use this function like you would a global variable, except without needing to + * declare the global. * * Example: $civi = civi_wp(); * - * @return CiviCRM_For_WordPress instance + * @since 4.4 + * + * @return CiviCRM_For_WordPress The plugin instance. */ function civi_wp() { return CiviCRM_For_WordPress::singleton(); } -/** +/* * Hook CiviCRM_For_WordPress early onto the 'plugins_loaded' action. * * This gives all other plugins the chance to load before CiviCRM, to get their @@ -1493,28 +1594,28 @@ function civi_wp() { if ( defined( 'CIVICRM_LATE_LOAD' ) ) { add_action( 'plugins_loaded', 'civi_wp', (int) CIVICRM_LATE_LOAD ); -// initialize +// Initialize } else { civi_wp(); } -/** +/* * Tell WordPress to call plugin activation method - no longer calls legacy - * global scope function + * global scope function. */ register_activation_hook( CIVICRM_PLUGIN_FILE, array( civi_wp(), 'activate' ) ); -/** +/* * Tell WordPress to call plugin deactivation method - needed in order to reset * the option that is set on activation. */ register_deactivation_hook( CIVICRM_PLUGIN_FILE, array( civi_wp(), 'deactivate' ) ); -// uninstall uses the 'uninstall.php' method -// see: http://codex.wordpress.org/Function_Reference/register_uninstall_hook +// Uninstall uses the 'uninstall.php' method +// See: http://codex.wordpress.org/Function_Reference/register_uninstall_hook @@ -1527,18 +1628,26 @@ function civi_wp() { /** - * add CiviCRM access capabilities to WordPress roles + * Add CiviCRM access capabilities to WordPress roles. + * * Called by postProcess() in civicrm/CRM/ACL/Form/WordPress/Permissions.php * Also a callback for the 'init' hook in civi_wp()->register_hooks() + * + * @since 4.3 */ function wp_civicrm_capability() { civi_wp()->users->set_access_capabilities(); } /** - * Test if CiviCRM is currently being displayed in WordPress + * Test if CiviCRM is currently being displayed in WordPress. + * * Called by setTitle() in civicrm/CRM/Utils/System/WordPress.php * Also called at the top of this plugin file to determine AJAX status + * + * @since 4.3 + * + * @return bool True if CiviCRM is displayed in WordPress, false otherwise. */ function civicrm_wp_in_civicrm() { return civi_wp()->civicrm_in_wordpress(); @@ -1546,7 +1655,11 @@ function civicrm_wp_in_civicrm() { /** * This was the original name of the initialization function and is - * retained for backward compatibility + * retained for backward compatibility. + * + * @since 4.3 + * + * @return bool True if CiviCRM is initialized, false otherwise. */ function civicrm_wp_initialize() { return civi_wp()->initialize(); @@ -1555,37 +1668,57 @@ function civicrm_wp_initialize() { /** * Initialize CiviCRM. Call this function from other modules too if * they use the CiviCRM API. + * + * @since 4.3 + * + * @return bool True if CiviCRM is initialized, false otherwise. */ function civicrm_initialize() { return civi_wp()->initialize(); } /** - * Callback from 'edit_post_link' hook to remove edit link in civicrm_set_post_blank() + * Callback from 'edit_post_link' hook to remove edit link in civicrm_set_post_blank(). + * + * @since 4.3 + * + * @return string Always empty. */ function civicrm_set_blank() { return civi_wp()->clear_edit_post_link(); } /** - * Authentication function used by civicrm_wp_frontend() + * Authentication function used by civicrm_wp_frontend(). + * + * @since 4.3 + * + * @param array $args The page arguments array. + * @return bool True if authenticated, false otherwise. */ function civicrm_check_permission( $args ) { return civi_wp()->users->check_permission( $args ); } /** - * Called when authentication fails in civicrm_wp_frontend() + * Called when authentication fails in civicrm_wp_frontend(). + * + * @since 4.3 + * + * @return string Warning message. */ function civicrm_set_frontendmessage() { return civi_wp()->users->get_permission_denied(); } /** - * Invoke CiviCRM in a WordPress context - * Callback function from add_menu_page() - * Callback from WordPress 'init' and 'the_content' hooks - * Also used by civicrm_wp_shortcode_includes() and _civicrm_update_user() + * Invoke CiviCRM in a WordPress context. + * + * Callback function from add_menu_page(). + * Callback from WordPress 'init' and 'the_content' hooks. + * Also used by civicrm_wp_shortcode_includes() and _civicrm_update_user(). + * + * @since 4.3 */ function civicrm_wp_invoke() { civi_wp()->invoke(); @@ -1593,39 +1726,55 @@ function civicrm_wp_invoke() { /** * Method that runs only when civicrm plugin is activated. + * + * @since 4.3 */ function civicrm_activate() { civi_wp()->activate(); } /** - * Function to create anonymous_user' role, if 'anonymous_user' role is not in the wordpress installation - * and assign minimum capabilities for all wordpress roles - * This function is called on plugin activation and also from upgrade_4_3_alpha1() + * Set WordPress user capabilities. + * + * Function to create anonymous_user' role, if 'anonymous_user' role is not in + * the wordpress installation and assign minimum capabilities for all wordpress roles. + * This function is called on plugin activation and also from upgrade_4_3_alpha1(). + * + * @since 4.3 */ function civicrm_wp_set_capabilities() { civi_wp()->users->set_wp_user_capabilities(); } /** - * Callback function for add_options_page() that runs the CiviCRM installer + * Callback function for add_options_page() that runs the CiviCRM installer. + * + * @since 4.3 */ function civicrm_run_installer() { civi_wp()->run_installer(); } /** - * Function to get the contact type - * @param string $default contact type - * @return $ctype contact type + * Function to get the contact type. + * + * @since 4.3 + * + * @param string $default The contact type. + * @return string $ctype The contact type. */ function civicrm_get_ctype( $default = NULL ) { return civi_wp()->users->get_civicrm_contact_type( $default ); } /** - * Getter function for global $wp_set_breadCrumb + * Getter function for global $wp_set_breadCrumb. + * * Called by appendBreadCrumb() in civicrm/CRM/Utils/System/WordPress.php + * + * @since 4.3 + * + * @return string $wp_set_breadCrumb The breadcrumb markup. */ function wp_get_breadcrumb() { global $wp_set_breadCrumb; @@ -1633,9 +1782,15 @@ function wp_get_breadcrumb() { } /** - * Setter function for global $wp_set_breadCrumb + * Setter function for global $wp_set_breadCrumb. + * * Called by appendBreadCrumb() in civicrm/CRM/Utils/System/WordPress.php * Called by resetBreadCrumb() in civicrm/CRM/Utils/System/WordPress.php + * + * @since 4.3 + * + * @param string $breadCrumb The desired breadcrumb markup. + * @return string $wp_set_breadCrumb The breadcrumb markup. */ function wp_set_breadcrumb( $breadCrumb ) { global $wp_set_breadCrumb; @@ -1645,11 +1800,14 @@ function wp_set_breadcrumb( $breadCrumb ) { /** - * Incorporate WP-CLI Integration - * Based on drush civicrm functionality, work done by Andy Walker + * Incorporate WP-CLI Integration. + * + * Based on drush civicrm functionality, work done by Andy Walker. * https://github.com/andy-walker/wp-cli-civicrm + * + * @since 4.5 */ if ( defined('WP_CLI') && WP_CLI ) { - // changed from __DIR__ because of possible symlink issues + // Changed from __DIR__ because of possible symlink issues include_once CIVICRM_PLUGIN_DIR . 'wp-cli/civicrm.php'; } diff --git a/includes/civicrm.basepage.php b/includes/civicrm.basepage.php index 78762ba..9395968 100644 --- a/includes/civicrm.basepage.php +++ b/includes/civicrm.basepage.php @@ -33,45 +33,48 @@ */ -// this file must not accessed directly +// This file must not accessed directly if ( ! defined( 'ABSPATH' ) ) exit; /** - * Define CiviCRM_For_WordPress_Basepage Class + * Define CiviCRM_For_WordPress_Basepage Class. + * + * @since 4.6 */ class CiviCRM_For_WordPress_Basepage { - /** - * Declare our properties + * Plugin object reference. + * + * @since 4.6 + * @access public + * @var object $civi The plugin object reference. */ - - // init property to store reference to Civi public $civi; /** - * Instance constructor + * Instance constructor. * - * @return object $this The object instance + * @since 4.6 */ function __construct() { - // store reference to Civi object + // Store reference to CiviCRM plugin object $this->civi = civi_wp(); } /** - * Register hooks to handle CiviCRM in a WordPress wpBasePage context + * Register hooks to handle CiviCRM in a WordPress wpBasePage context. * - * @return void + * @since 4.6 */ public function register_hooks() { - // kick out if not CiviCRM + // Kick out if not CiviCRM if (!$this->civi->initialize()) { return; } @@ -85,63 +88,67 @@ public function register_hooks() { // And also for All in One SEO to handle canonical URL add_filter( 'aioseop_canonical_url', array( $this, 'basepage_canonical_url' ), 999 ); - // regardless of URL, load page template + // Regardless of URL, load page template add_filter( 'template_include', array( $this, 'basepage_template' ), 999 ); - // check permission + // Check permission $argdata = $this->civi->get_request_args(); if ( ! $this->civi->users->check_permission( $argdata['args'] ) ) { add_filter( 'the_content', array( $this->civi->users, 'get_permission_denied' ) ); return; } - // cache CiviCRM base page markup + // Cache CiviCRM base page markup add_action( 'wp', array( $this, 'basepage_handler' ), 10, 1 ); } /** - * Build CiviCRM base page content - * Callback method for 'wp' hook, always called from WP front-end + * Build CiviCRM base page content. + * + * Callback method for 'wp' hook, always called from WP front-end. + * + * @since 4.6 * - * @param object $wp The WP object, present but not used - * @return void + * @param object $wp The WP object, present but not used. */ public function basepage_handler( $wp ) { - /** + /* * At this point, all conditional tags are available * @see http://codex.wordpress.org/Conditional_Tags */ - // bail if this is a 404 + // Bail if this is a 404 if ( is_404() ) return; - // kick out if not CiviCRM + // Kick out if not CiviCRM if (!$this->civi->initialize()) { return ''; } - // add core resources for front end + // Add core resources for front end add_action( 'wp', array( $this->civi, 'front_end_page_load' ), 100 ); // CMW: why do we need this? Nothing that follows uses it... require_once ABSPATH . WPINC . '/pluggable.php'; - // let's do the_loop - // this has the effect of bypassing the logic in - // https://github.com/civicrm/civicrm-wordpress/pull/36 + /* + * Let's do the_loop. + * This has the effect of bypassing the logic in + * https://github.com/civicrm/civicrm-wordpress/pull/36 + */ if ( have_posts() ) { while ( have_posts() ) : the_post(); global $post; - ob_start(); // start buffering - $this->civi->invoke(); // now, instead of echoing, base page output ends up in buffer - $this->basepage_markup = ob_get_clean(); // save the output and flush the buffer + ob_start(); // Start buffering + $this->civi->invoke(); // Now, instead of echoing, base page output ends up in buffer + $this->basepage_markup = ob_get_clean(); // Save the output and flush the buffer - /** + /* * The following logic is in response to some of the complexities of how * titles are handled in WordPress, particularly when there are SEO * plugins present that modify the title for Open Graph purposes. There @@ -156,121 +163,132 @@ public function basepage_handler( $wp ) { * page title if other plugins modify it. */ - // override post title + // Override post title global $civicrm_wp_title; $post->post_title = $civicrm_wp_title; - // because the above seems unreliable, store title for later use + // Because the above seems unreliable, store title for later use $this->basepage_title = $civicrm_wp_title; - // disallow commenting + // Disallow commenting $post->comment_status = 'closed'; endwhile; } - // reset loop + // Reset loop rewind_posts(); - // override page title with high priority + // Override page title with high priority add_filter( 'wp_title', array( $this, 'wp_page_title' ), 100, 3 ); - // add compatibility with WordPress SEO plugin's Open Graph title + // Add compatibility with WordPress SEO plugin's Open Graph title add_filter( 'wpseo_opengraph_title', array( $this, 'wpseo_page_title' ), 100, 1 ); - // include this content when base page is rendered + // Include this content when base page is rendered add_filter( 'the_content', array( $this, 'basepage_render' ) ); - // hide the edit link + // Hide the edit link add_action( 'edit_post_link', array( $this->civi, 'clear_edit_post_link' ) ); - // tweak admin bar + // Tweak admin bar add_action( 'wp_before_admin_bar_render', array( $this->civi, 'clear_edit_post_menu_item' ) ); - // add body classes for easier styling + // Add body classes for easier styling add_filter( 'body_class', array( $this, 'add_body_classes' ) ); - // flag that we have parsed the base page + // Flag that we have parsed the base page $this->basepage_parsed = TRUE; - // broadcast this as well + /** + * Broadcast that the base page is parsed. + * + * @since 4.4 + */ do_action( 'civicrm_basepage_parsed' ); } /** - * Get CiviCRM basepage title for <title> element + * Get CiviCRM basepage title for <title> element. + * + * Callback method for 'wp_title' hook, called at the end of function wp_title. * - * Callback method for 'wp_title' hook, called at the end of function wp_title + * @since 4.6 * - * @param string $title Title that might have already been set - * @param string $separator Separator determined in theme (but defaults to WordPress default) - * @param string $separator_location Whether the separator should be left or right + * @param string $title Title that might have already been set. + * @param string $separator Separator determined in theme (but defaults to WordPress default). + * @param string $separator_location Whether the separator should be left or right. */ public function wp_page_title( $title, $separator = '»', $separator_location = '' ) { - // if feed, return just the title + // If feed, return just the title if ( is_feed() ) return $this->basepage_title; - // set default separator location, if it isn't defined + // Set default separator location, if it isn't defined if ( '' === trim( $separator_location ) ) { $separator_location = ( is_rtl() ) ? 'left' : 'right'; } - // if we have WP SEO present, use its separator + // If we have WP SEO present, use its separator if ( class_exists( 'WPSEO_Options' ) ) { $separator_code = WPSEO_Options::get_default( 'wpseo_titles', 'separator' ); $separator_array = WPSEO_Option_Titles::get_instance()->get_separator_options(); if ( array_key_exists( $separator_code, $separator_array ) ) { - $separator = $separator_array[$separator_code]; + $separator = $separator_array[$separator_code]; } } - // construct title depending on separator location + // Construct title depending on separator location if ( $separator_location == 'right' ) { - $title = $this->basepage_title . " $separator " . get_bloginfo( 'name', 'display' ); + $title = $this->basepage_title . " $separator " . get_bloginfo( 'name', 'display' ); } else { - $title = get_bloginfo( 'name', 'display' ) . " $separator " . $this->basepage_title; + $title = get_bloginfo( 'name', 'display' ) . " $separator " . $this->basepage_title; } - // return modified title + // Return modified title return $title; } /** - * Get CiviCRM base page title for Open Graph elements + * Get CiviCRM base page title for Open Graph elements. * * Callback method for 'wpseo_opengraph_title' hook, to provide compatibility * with the WordPress SEO plugin. * - * @param string $post_title The title of the WordPress page or post - * @return string $basepage_title The title of the CiviCRM entity + * @since 4.6.4 + * + * @param string $post_title The title of the WordPress page or post. + * @return string $basepage_title The title of the CiviCRM entity. */ public function wpseo_page_title( $post_title ) { - // hand back our base page title + // Hand back our base page title return $this->basepage_title; } /** - * Get CiviCRM base page content - * Callback method for 'the_content' hook, always called from WP front-end + * Get CiviCRM base page content. * - * @param object $wp The WP object, present but not used - * @return void + * Callback method for 'the_content' hook, always called from WP front-end. + * + * @since 4.6 + * + * @return str $basepage_markup The base page markup. */ public function basepage_render() { - // hand back our base page markup + // Hand back our base page markup return $this->basepage_markup; } + /** * Provide the canonical URL for a page accessed through a basepage. * @@ -287,15 +305,17 @@ public function basepage_render() { * not. We don't actually need the page object, so the argument is omitted * here. * - * @param string $canonical - * The canonical URL. + * @since 4.6 * - * @return string - * The complete URL to the page as it should be accessed. + * @param string $canonical The canonical URL. + * @return string The complete URL to the page as it should be accessed. */ public function basepage_canonical_url( $canonical ) { - // It would be better to specify which params are okay to accept as the - // canonical URLs, but this will work for the time being. + + /* + * It would be better to specify which params are okay to accept as the + * canonical URLs, but this will work for the time being. + */ if ( empty( $_GET['page'] ) || empty( $_GET['q'] ) || 'CiviCRM' !== $_GET['page'] ) { @@ -309,42 +329,50 @@ public function basepage_canonical_url( $canonical ) { // We should, however, build the URL the way that CiviCRM expects it to be // (rather than through some other funny base page). return CRM_Utils_System::url( $path, $query ); + } + /** * Get CiviCRM base page template. * * Callback method for 'template_include' hook, always called from WP front-end. * - * @param string $template The path to the existing template - * @return string $template The modified path to the desired template + * @since 4.6 + * + * @param string $template The path to the existing template. + * @return string $template The modified path to the desired template. */ public function basepage_template( $template ) { - // get template filename + // Get template filename $template_name = basename( $template ); - // use the provided page template, but allow overrides. + // Use the provided page template, but allow overrides. $page_template = locate_template( array( /** + * Allow base page template to be overridden. + * * In most cases, the logic will not progress beyond here. Shortcodes in * posts and pages will have a template set, so we leave them alone unless * specifically overridden by the filter. * - * @param string $template_name The provided template name - * @return string The overridden template name + * @since 4.6 + * + * @param string $template_name The provided template name. + * @return string The overridden template name. */ apply_filters( 'civicrm_basepage_template', $template_name ) ) ); - // if not homepage and template is found + // If not homepage and template is found if ( '' != $page_template && !is_front_page() ) { return $page_template; } - // find homepage the template + // Find homepage the template $home_template = locate_template( array( /** @@ -360,19 +388,21 @@ public function basepage_template( $template ) { * template override will not have the desired effect. A basepage *must* * be set if this is the case. * - * @param string The template name (set to the default page template) - * @return string The overridden template name + * @since 4.6 + * + * @param string The template name (set to the default page template). + * @return string The overridden template name. */ apply_filters( 'civicrm_basepage_home_template', 'page.php' ) ) ); - // use it if found + // Use it if found if ( '' != $home_template ) { return $home_template; } - // fall back to provided template + // Fall back to provided template return $template; } @@ -384,41 +414,43 @@ public function basepage_template( $template ) { * This allows selectors to be written for particular CiviCRM "pages" despite * them all being rendered on the one WordPress basepage. * - * @param array $classes The existing body classes - * @return array $classes The modified body classes + * @since 4.7.18 + * + * @param array $classes The existing body classes. + * @return array $classes The modified body classes. */ public function add_body_classes( $classes ) { - $args = $this->civi->get_request_args(); + $args = $this->civi->get_request_args(); - // bail if we don't have any - if ( is_null( $args['argString'] ) ) { - return $classes; - } + // Bail if we don't have any + if ( is_null( $args['argString'] ) ) { + return $classes; + } - // check for top level - it can be assumed this always 'civicrm' - if ( isset( $args['args'][0] ) AND ! empty( $args['args'][0] ) ) { - $classes[] = $args['args'][0]; - } + // Check for top level - it can be assumed this always 'civicrm' + if ( isset( $args['args'][0] ) AND ! empty( $args['args'][0] ) ) { + $classes[] = $args['args'][0]; + } - // check for second level - the component - if ( isset( $args['args'][1] ) AND ! empty( $args['args'][1] ) ) { - $classes[] = $args['args'][0] . '-' . $args['args'][1]; - } + // Check for second level - the component + if ( isset( $args['args'][1] ) AND ! empty( $args['args'][1] ) ) { + $classes[] = $args['args'][0] . '-' . $args['args'][1]; + } - // check for third level - the component's configuration - if ( isset( $args['args'][2] ) AND ! empty( $args['args'][2] ) ) { - $classes[] = $args['args'][0] . '-' . $args['args'][1] . '-' . $args['args'][2]; - } + // Check for third level - the component's configuration + if ( isset( $args['args'][2] ) AND ! empty( $args['args'][2] ) ) { + $classes[] = $args['args'][0] . '-' . $args['args'][1] . '-' . $args['args'][2]; + } - // check for fourth level - because well, why not? - if ( isset( $args['args'][3] ) AND ! empty( $args['args'][3] ) ) { - $classes[] = $args['args'][0] . '-' . $args['args'][1] . '-' . $args['args'][2] . '-' . $args['args'][3]; - } + // Check for fourth level - because well, why not? + if ( isset( $args['args'][3] ) AND ! empty( $args['args'][3] ) ) { + $classes[] = $args['args'][0] . '-' . $args['args'][1] . '-' . $args['args'][2] . '-' . $args['args'][3]; + } - return $classes; + return $classes; } -} // class CiviCRM_For_WordPress_Basepage ends +} // Class CiviCRM_For_WordPress_Basepage ends diff --git a/includes/civicrm.shortcodes.modal.php b/includes/civicrm.shortcodes.modal.php index d606a8a..94ac15c 100644 --- a/includes/civicrm.shortcodes.modal.php +++ b/includes/civicrm.shortcodes.modal.php @@ -33,53 +33,56 @@ */ -// this file must not accessed directly +// This file must not accessed directly if ( ! defined( 'ABSPATH' ) ) exit; /** - * Define CiviCRM_For_WordPress_Shortcodes_Modal Class + * Define CiviCRM_For_WordPress_Shortcodes_Modal Class. + * + * @since 4.6 */ class CiviCRM_For_WordPress_Shortcodes_Modal { - /** - * Declare our properties + * Plugin object reference. + * + * @since 4.6 + * @access public + * @var object $civi The plugin object reference. */ - - // init property to store reference to Civi public $civi; /** - * Instance constructor + * Instance constructor. * - * @return object $this The object instance + * @since 4.6 */ function __construct() { - // store reference to Civi object + // Store reference to CiviCRM plugin object $this->civi = civi_wp(); } /** - * Register hooks to handle the presence of shortcodes in content + * Register hooks to handle the shortcode modal. * - * @return void + * @since 4.6 */ public function register_hooks() { - // bail if Civi not installed yet + // Bail if CiviCRM not installed yet if ( ! CIVICRM_INSTALLED ) return; - // adds the CiviCRM button to post and page edit screens - // use priority 100 to position button to the farright + // Adds the CiviCRM button to post and page edit screens + // Use priority 100 to position button to the farright add_action( 'media_buttons', array( $this, 'add_form_button' ), 100 ); - // add the javascript and styles to make it all happen + // Add the javascript and styles to make it all happen add_action('load-post.php', array($this, 'add_core_resources')); add_action('load-post-new.php', array($this, 'add_core_resources')); add_action('load-page.php', array($this, 'add_core_resources')); @@ -89,14 +92,15 @@ public function register_hooks() { /** - * Callback method for 'media_buttons' hook as set in register_hooks() + * Add button to editor for WP selected post types. * - * @param string $editor_id Unique editor identifier, e.g. 'content' - * @return void + * Callback method for 'media_buttons' hook as set in register_hooks(). + * + * @since 4.7 */ public function add_form_button() { - // add button to WP selected post types, if allowed + // Add button to WP selected post types, if allowed if ( $this->post_type_has_button() ) { $civilogo = file_get_contents( plugin_dir_path( __FILE__ ) . '../assets/civilogo.svg.b64' ); @@ -110,9 +114,11 @@ public function add_form_button() { /** - * Callback method as set in register_hooks() + * Add core resources. + * + * Callback method as set in register_hooks(). * - * @return void + * @since 4.7 */ public function add_core_resources() { if ($this->civi->initialize()) { @@ -124,23 +130,25 @@ public function add_core_resources() { /** * Does a WordPress post type have the CiviCRM button on it? * - * @return bool $has_button True if the post type has the button, false otherwise + * @since 4.6 + * + * @return bool $has_button True if the post type has the button, false otherwise. */ public function post_type_has_button() { - // get screen object + // Get screen object $screen = get_current_screen(); - // bail if no post type (e.g. Ninja Forms) + // Bail if no post type (e.g. Ninja Forms) if ( ! isset( $screen->post_type ) ) return; - // get post types that support the editor + // Get post types that support the editor $capable_post_types = $this->get_post_types_with_editor(); - // default allowed to true on all capable post types + // Default allowed to true on all capable post types $allowed = ( in_array( $screen->post_type, $capable_post_types ) ) ? true : false; - // allow plugins to override + // Allow plugins to override $allowed = apply_filters( 'civicrm_restrict_button_appearance', $allowed, $screen ); return $allowed; @@ -149,9 +157,11 @@ public function post_type_has_button() { /** - * Get WordPress post types that support the editor + * Get WordPress post types that support the editor. + * + * @since 4.6 * - * @return array $supported_post_types Array of post types that have an editor + * @return array $supported_post_types Array of post types that have an editor. */ public function get_post_types_with_editor() { @@ -160,17 +170,17 @@ public function get_post_types_with_editor() { return $supported_post_types; } - // get only post types with an admin UI + // Get only post types with an admin UI $args = array( 'public' => true, 'show_ui' => true, ); - // get post types + // Get post types $post_types = get_post_types($args); foreach ($post_types AS $post_type) { - // filter only those which have an editor + // Filter only those which have an editor if (post_type_supports($post_type, 'editor')) { $supported_post_types[] = $post_type; } @@ -179,4 +189,4 @@ public function get_post_types_with_editor() { return $supported_post_types; } -} // class CiviCRM_For_WordPress_Shortcodes_Modal ends +} // Class CiviCRM_For_WordPress_Shortcodes_Modal ends diff --git a/includes/civicrm.shortcodes.php b/includes/civicrm.shortcodes.php index e9491c1..7da0d76 100644 --- a/includes/civicrm.shortcodes.php +++ b/includes/civicrm.shortcodes.php @@ -33,103 +33,128 @@ */ -// this file must not accessed directly +// This file must not accessed directly if ( ! defined( 'ABSPATH' ) ) exit; /** - * Define CiviCRM_For_WordPress_Shortcodes Class + * Define CiviCRM_For_WordPress_Shortcodes Class. + * + * @since 4.6 */ class CiviCRM_For_WordPress_Shortcodes { - /** - * Declare our properties + * Plugin object reference. + * + * @since 4.6 + * @access public + * @var object $civi The plugin object reference. */ - - // init property to store reference to Civi public $civi; - // init property to store shortcodes + /** + * Stored shortcodes. + * + * @since 4.6 + * @access public + * @var array $shortcodes The stored shortcodes. + */ public $shortcodes = array(); - // init property to store shortcode markup + /** + * Rendered shortcode markup. + * + * @since 4.6 + * @access public + * @var array $shortcode_markup The array of rendered shortcode markup. + */ public $shortcode_markup = array(); - // count multiple passes of do_shortcode in a post + /** + * Count multiple passes of do_shortcode in a post. + * + * @since 4.6 + * @access public + * @var array $shortcode_in_post Count multiple passes of do_shortcode in a post. + */ public $shortcode_in_post = array(); /** - * Instance constructor + * Instance constructor. * - * @return object $this The object instance + * @since 4.6 */ function __construct() { - // store reference to Civi object + // Store reference to CiviCRM plugin object $this->civi = civi_wp(); } /** - * Register hooks to handle the presence of shortcodes in content + * Register hooks to handle the presence of shortcodes in content. * - * @return void + * @since 4.6 */ public function register_hooks() { - // register the CiviCRM shortcode + // Register the CiviCRM shortcode add_shortcode( 'civicrm', array( $this, 'render_single' ) ); - // add CiviCRM core resources when a shortcode is detected in the post content + // Add CiviCRM core resources when a shortcode is detected in the post content add_action( 'wp', array( $this, 'prerender' ), 10, 1 ); } /** - * Determine if a CiviCRM shortcode is present in any of the posts about to be displayed - * Callback method for 'wp' hook, always called from WP front-end + * Determine if a CiviCRM shortcode is present in any of the posts about to be displayed. + * + * Callback method for 'wp' hook, always called from WP front-end. * - * @param object $wp The WP object, present but not used - * @return void + * @since 4.6 + * + * @param object $wp The WP object, present but not used. */ public function prerender( $wp ) { - /** + /* * At this point, all conditional tags are available * @see http://codex.wordpress.org/Conditional_Tags */ - // bail if this is a 404 + // Bail if this is a 404 if ( is_404() ) return; - // a counter's useful + // A counter's useful $shortcodes_present = 0; - // let's loop through the results - // this also has the effect of bypassing the logic in - // https://github.com/civicrm/civicrm-wordpress/pull/36 + /* + * Let's loop through the results + * This also has the effect of bypassing the logic in + * https://github.com/civicrm/civicrm-wordpress/pull/36 + */ if ( have_posts() ) { while ( have_posts() ) : the_post(); global $post; - // check for existence of shortcode in content + // Check for existence of shortcode in content if ( has_shortcode( $post->post_content, 'civicrm' ) ) { - // get CiviCRM shortcodes in this post + // Get CiviCRM shortcodes in this post $shortcodes_array = $this->get_for_post( $post->post_content ); - // sanity check + // Sanity check if ( !empty( $shortcodes_array ) ) { - // add it to our property + // Add it to our property $this->shortcodes[$post->ID] = $shortcodes_array; - // bump shortcode counter + // Bump shortcode counter $shortcodes_present += count( $this->shortcodes[$post->ID] ); } @@ -139,32 +164,32 @@ public function prerender( $wp ) { endwhile; } - // reset loop + // Reset loop rewind_posts(); - // did we get any? + // Did we get any? if ( $shortcodes_present ) { - // we need CiviCRM initialised prior to parsing shortcodes + // We need CiviCRM initialised prior to parsing shortcodes if (!$this->civi->initialize()) { return; } - // how should we handle multiple shortcodes? + // How should we handle multiple shortcodes? if ( $shortcodes_present > 1 ) { - // add CSS resources for front end + // Add CSS resources for front end add_action( 'wp_enqueue_scripts', array( $this->civi, 'front_end_css_load' ), 100 ); - // let's add dummy markup + // Let's add dummy markup foreach( $this->shortcodes AS $post_id => $shortcode_array ) { - // set flag if there are multple shortcodes in this post + // Set flag if there are multple shortcodes in this post $multiple = ( count( $shortcode_array ) > 1 ) ? 1 : 0; foreach( $shortcode_array AS $shortcode ) { - // mimic invoke in multiple shortcode context + // Mimic invoke in multiple shortcode context $this->shortcode_markup[$post_id][] = $this->render_multiple( $post_id, $shortcode, $multiple ); } @@ -173,49 +198,51 @@ public function prerender( $wp ) { } else { - // add core resources for front end + // Add core resources for front end add_action( 'wp', array( $this->civi, 'front_end_page_load' ), 100 ); - // since we have only one shortcode, run the_loop again - // the DB query has already been done, so this has no significant impact + /* + * Since we have only one shortcode, run the_loop again + * the DB query has already been done, so this has no significant impact + */ if ( have_posts() ) { while ( have_posts() ) : the_post(); global $post; - // is this the post? + // Is this the post? if ( ! array_key_exists( $post->ID, $this->shortcodes ) ) { continue; } - // the shortcode must be the first item in the shortcodes array + // The shortcode must be the first item in the shortcodes array $shortcode = $this->shortcodes[$post->ID][0]; - // check to see if a shortcode component has been repeated? + // Check to see if a shortcode component has been repeated? $atts = $this->get_atts( $shortcode ); - // test for hijacking + // Test for hijacking if ( isset( $atts['hijack'] ) AND $atts['hijack'] == '1' ) { add_filter( 'civicrm_context', array( $this, 'get_context' ) ); } - // store corresponding markup + // Store corresponding markup $this->shortcode_markup[$post->ID][] = do_shortcode( $shortcode ); - // test for hijacking + // Test for hijacking if ( isset( $atts['hijack'] ) AND $atts['hijack'] == '1' ) { - // ditch the filter + // Ditch the filter remove_filter( 'civicrm_context', array( $this, 'get_context' ) ); - // set title + // Set title global $civicrm_wp_title; $post->post_title = $civicrm_wp_title; - // override page title + // Override page title add_filter( 'single_post_title', array( $this->civi, 'single_page_title' ), 50, 2 ); - // overwrite content + // Overwrite content add_filter( 'the_content', array( $this, 'get_content' ) ); } @@ -223,27 +250,33 @@ public function prerender( $wp ) { endwhile; } - // reset loop + // Reset loop rewind_posts(); } } - // flag that we have parsed shortcodes + // Flag that we have parsed shortcodes $this->shortcodes_parsed = TRUE; - // broadcast this as well + /** + * Broadcast that shortcodes have been parsed. + * + * @since 4.6 + */ do_action( 'civicrm_shortcodes_parsed' ); } /** - * Handles CiviCRM-defined shortcodes + * Handles CiviCRM-defined shortcodes. + * + * @since 4.6 * - * @param array Shortcode attributes array - * @return string HTML for output + * @param array $atts Shortcode attributes array. + * @return string HTML for output. */ public function render_single( $atts ) { // Do not parse shortcodes in REST context for PUT, POST and DELETE methods @@ -257,30 +290,30 @@ public function render_single( $atts ) { return $shortcode; } - // check if we've already parsed this shortcode + // Check if we've already parsed this shortcode global $post; if ( is_object($post) ) { if ( !empty( $this->shortcode_markup ) ) { if ( isset( $this->shortcode_markup[$post->ID] ) ) { - // set counter flag + // Set counter flag if ( ! isset( $this->shortcode_in_post[$post->ID] ) ) { $this->shortcode_in_post[$post->ID] = 0; } else { $this->shortcode_in_post[$post->ID]++; } - // this shortcode must have been rendered + // This shortcode must have been rendered return $this->shortcode_markup[$post->ID][$this->shortcode_in_post[$post->ID]]; } } } - // preprocess shortcode attributes + // Preprocess shortcode attributes $args = $this->preprocess_atts( $atts ); - // sanity check for improperly constructed shortcode + // Sanity check for improperly constructed shortcode if ( $args === FALSE ) { return '<p>' . __( 'Do not know how to handle this shortcode.', 'civicrm' ) . '</p>'; } @@ -292,12 +325,12 @@ public function render_single( $atts ) { } } - // kick out if not CiviCRM + // Kick out if not CiviCRM if (!$this->civi->initialize()) { return ''; } - // check permission + // Check permission $argdata = $this->civi->get_request_args(); if ( ! $this->civi->users->check_permission( $argdata['args'] ) ) { return $this->civi->users->get_permission_denied();; @@ -306,58 +339,60 @@ public function render_single( $atts ) { // CMW: why do we need this? Nothing that follows uses it... require_once ABSPATH . WPINC . '/pluggable.php'; - ob_start(); // start buffering - $this->civi->invoke(); // now, instead of echoing, shortcode output ends up in buffer - $content = ob_get_clean(); // save the output and flush the buffer + ob_start(); // Start buffering + $this->civi->invoke(); // Now, instead of echoing, shortcode output ends up in buffer + $content = ob_get_clean(); // Save the output and flush the buffer return $content; } /** - * Return a generic display for a shortcode instead of a CiviCRM invocation + * Return a generic display for a shortcode instead of a CiviCRM invocation. * - * @param int $post_id The containing WordPress post ID - * @param string $shortcode The shortcode being parsed - * @param bool $multiple Boolean flag, TRUE if post has multiple shortcodes, FALSE otherwise - * @return string $markup Generic markup for multiple instances + * @since 4.6 + * + * @param int $post_id The containing WordPress post ID. + * @param string $shortcode The shortcode being parsed. + * @param bool $multiple Boolean flag, TRUE if post has multiple shortcodes, FALSE otherwise. + * @return string $markup Generic markup for multiple instances. */ private function render_multiple( $post_id = FALSE, $shortcode = FALSE, $multiple = 0 ) { - // get attributes + // Get attributes $atts = $this->get_atts( $shortcode ); - // pre-process shortcode and retrieve args + // Pre-process shortcode and retrieve args $args = $this->preprocess_atts( $atts ); - // sanity check for improperly constructed shortcode + // Sanity check for improperly constructed shortcode if ( $args === FALSE ) { return '<p>' . __( 'Do not know how to handle this shortcode.', 'civicrm' ) . '</p>'; } - // get data for this shortcode + // Get data for this shortcode $data = $this->get_data( $atts, $args ); - // sanity check + // Sanity check if ( $data === FALSE ) return ''; - // did we get a title? + // Did we get a title? $title = __( 'Content via CiviCRM', 'civicrm' ); if ( ! empty( $data['title'] ) ) $title = $data['title']; - // init title flag + // Init title flag $show_title = TRUE; - // default link + // Default link $link = get_permalink( $post_id ); - // default to no class + // Default to no class $class = ''; - // access CIvi config object + // Access CIvi config object $config = CRM_Core_Config::singleton(); - // do we have multiple shortcodes? + // Do we have multiple shortcodes? if ( $multiple != 0 ) { $links = array(); @@ -371,7 +406,7 @@ private function render_multiple( $post_id = FALSE, $shortcode = FALSE, $multipl // $absolute, $frontend, $forceBackend $base_url = $this->civi->get_base_url(TRUE, FALSE, FALSE); - // construct query parts + // Construct query parts $queryParts = array(); $queryParts[] = 'page=CiviCRM'; if (isset($args['q'])) { @@ -381,61 +416,61 @@ private function render_multiple( $post_id = FALSE, $shortcode = FALSE, $multipl $queryParts[] = $query; } - // construct link + // Construct link $link = trailingslashit( $base_url ) . '?' . implode('&', $queryParts); - // add a class for styling purposes + // Add a class for styling purposes $class = ' civicrm-shortcode-multiple'; } - // test for hijacking + // Test for hijacking if ( !$multiple ) { if ( isset( $atts['hijack'] ) AND $atts['hijack'] == '1' ) { - // add title to array + // Add title to array $this->post_titles[$post_id] = $data['title']; - // override title + // Override title add_filter( 'the_title', array( $this, 'get_title' ), 100, 2 ); - // overwrite content + // Overwrite content add_filter( 'the_content', array( $this, 'get_content' ) ); - // don't show title + // Don't show title $show_title = FALSE; - // add a class for styling purposes + // Add a class for styling purposes $class = ' civicrm-shortcode-single'; } } - // set some template variables + // Set some template variables - // description + // Description $description = FALSE; if ( isset( $data['text'] ) AND ! empty( $data['text'] ) ) { $description = $data['text']; } - // provide an enticing link + // Provide an enticing link $more_link = sprintf( '<a href="%s">%s</a>', $link, apply_filters( 'civicrm_shortcode_more_link', __( 'Find out more...', 'civicrm' ) ) ); - // assume CiviCRM footer is not enabled + // Assume CiviCRM footer is not enabled $empowered_enabled = FALSE; $footer = ''; - // test config object for setting + // Test config object for setting if ( $config->empoweredBy == 1 ) { - // footer enabled - define it + // Footer enabled - define it $civi = __( 'CiviCRM.org - Growing and Sustaining Relationships', 'civicrm' ); $logo = '<div class="empowered-by-logo"><span>' . __( 'CiviCRM', 'civicrm' ) . '</span></div>'; $civi_link = '<a href="http://civicrm.org/" title="' . $civi . '" target="_blank" class="empowered-by-link">' . $logo . '</a>'; @@ -446,25 +481,27 @@ private function render_multiple( $post_id = FALSE, $shortcode = FALSE, $multipl } - // start buffering + // Start buffering ob_start(); - // include template + // Include template include( CIVICRM_PLUGIN_DIR . 'assets/templates/civicrm.shortcode.php' ); - // save the output and flush the buffer + // Save the output and flush the buffer $markup = ob_get_clean(); - // allow plugins to override + // Allow plugins to override return apply_filters( 'civicrm_shortcode_render_multiple', $markup, $post_id, $shortcode ); } /** - * In order to hijack the page, we need to override the context + * In order to hijack the page, we need to override the context. + * + * @since 4.6 * - * @return string Overridden context code + * @return string The overridden context code. */ public function get_context() { return 'nonpage'; @@ -472,20 +509,22 @@ public function get_context() { /** - * In order to hijack the page, we need to override the content + * In order to hijack the page, we need to override the content. * - * @return string Overridden content + * @since 4.6 + * + * @return string The overridden content. */ public function get_content( $content ) { global $post; - // is this the post? + // Is this the post? if ( ! array_key_exists( $post->ID, $this->shortcode_markup ) ) { return $content; } - // bail if it has multiple shortcodes + // Bail if it has multiple shortcodes if ( count( $this->shortcode_markup[$post->ID] ) > 1 ) { return $content; } @@ -496,23 +535,27 @@ public function get_content( $content ) { /** - * In order to hijack the page, we need to override the title + * In order to hijack the page, we need to override the title. + * + * @since 4.6 * - * @return string Overridden title + * @param string $title The existing title. + * @param int $post_id The numeric ID of the WordPress post. + * @return string $title The overridden title. */ public function get_title( $title, $post_id ) { - // is this the post? + // Is this the post? if ( ! array_key_exists( $post_id, $this->shortcode_markup ) ) { return $title; } - // bail if it has multiple shortcodes + // Bail if it has multiple shortcodes if ( count( $this->shortcode_markup[$post_id] ) > 1 ) { return $title; } - // shortcodes may or may not override title + // Shortcodes may or may not override title if ( array_key_exists( $post_id, $this->post_titles ) ) { $title = $this->post_titles[$post_id]; } @@ -523,17 +566,19 @@ public function get_title( $title, $post_id ) { /** - * Detect and return CiviCRM shortcodes in post content + * Detect and return CiviCRM shortcodes in post content. * - * @param $content The content to parse - * @return array $shortcodes Array of shortcodes + * @since 4.6 + * + * @param str $content The content to parse. + * @return array $shortcodes Array of shortcodes. */ private function get_for_post( $content ) { - // init return array + // Init return array $shortcodes = array(); - // attempt to discover all instances of the shortcode + // Attempt to discover all instances of the shortcode $pattern = get_shortcode_regex(); if ( @@ -542,7 +587,7 @@ private function get_for_post( $content ) { && in_array( 'civicrm', $matches[2] ) ) { - // get keys for our shortcode + // Get keys for our shortcode $keys = array_keys( $matches[2], 'civicrm' ); foreach( $keys AS $key ) { @@ -557,18 +602,20 @@ private function get_for_post( $content ) { /** - * Return attributes for a given CiviCRM shortcode + * Return attributes for a given CiviCRM shortcode. + * + * @since 4.6 * - * @param $shortcode The shortcode to parse - * @return array $shortcode_atts Array of shortcode attributes + * @param $shortcode The shortcode to parse. + * @return array $shortcode_atts Array of shortcode attributes. */ private function get_atts( $shortcode ) { - // strip all but attributes definitions + // Strip all but attributes definitions $text = str_replace( '[civicrm ', '', $shortcode ); $text = str_replace( ']', '', $text ); - // extract attributes + // Extract attributes $shortcode_atts = shortcode_parse_atts( $text ); return $shortcode_atts; @@ -577,10 +624,12 @@ private function get_atts( $shortcode ) { /** - * Preprocess CiviCRM-defined shortcodes + * Preprocess CiviCRM-defined shortcodes. * - * @param array $atts Shortcode attributes array - * @return array $args Shortcode arguments array + * @since 4.6 + * + * @param array $atts Shortcode attributes array. + * @return array $args Shortcode arguments array. */ public function preprocess_atts( $atts ) { @@ -606,7 +655,7 @@ public function preprocess_atts( $atts ) { 'force' => $force, ); - // construct args for known components + // Construct args for known components switch ( $component ) { case 'contribution': @@ -677,13 +726,15 @@ public function preprocess_atts( $atts ) { * that the 'civicrm' shortcode allows. Injected attributes and their values * will also become available in the $_REQUEST and $_GET arrays. * - * @param array $args Existing shortcode arguments - * @param array $shortcode_atts Shortcode attributes - * @return array $args Modified shortcode arguments + * @since 4.7.28 + * + * @param array $args Existing shortcode arguments. + * @param array $shortcode_atts Shortcode attributes. + * @return array $args Modified shortcode arguments. */ $args = apply_filters( 'civicrm_shortcode_preprocess_atts', $args, $shortcode_atts ); - // sanity check for path + // Sanity check for path if ( ! isset( $args['q'] ) ) { return FALSE; } @@ -694,7 +745,9 @@ public function preprocess_atts( $atts ) { /** - * Post-process CiviCRM-defined shortcodes + * Post-process CiviCRM-defined shortcodes. + * + * @since 4.6 * * @param array $atts Shortcode attributes array * @param array $args Shortcode arguments array @@ -702,7 +755,7 @@ public function preprocess_atts( $atts ) { */ public function get_data( $atts, $args ) { - // init return array + // Init return array $data = array(); if (!$this->civi->initialize()) { @@ -715,10 +768,12 @@ public function get_data( $atts, $args ) { * This filter allows plugins or CiviExtensions to modify the API call when * there are multiple shortcodes being rendered. * - * @param array $params Existing API params - * @param array $atts Shortcode attributes array - * @param array $args Shortcode arguments array - * @return array $params Modified API params + * @since 4.7.28 + * + * @param array $params Existing API params. + * @param array $atts Shortcode attributes array. + * @param array $args Shortcode arguments array. + * @return array $params Modified API params. */ $params = apply_filters( 'civicrm_shortcode_api_params', array( 'version' => 3, @@ -727,21 +782,21 @@ public function get_data( $atts, $args ) { 'sequential' => '1', ), $atts, $args ); - // get the Civi entity via the API + // Get the CiviCRM entity via the API switch ( $atts['component'] ) { case 'contribution': - // add event ID + // Add event ID $params['id'] = $args['id']; - // call API + // Call API $civi_entity = civicrm_api( 'contribution_page', 'getsingle', $params ); - // set title + // Set title $data['title'] = $civi_entity['title']; - // set text, if present + // Set text, if present $data['text'] = ''; if ( isset( $civi_entity['intro_text'] ) ) { $data['text'] = $civi_entity['intro_text']; @@ -751,13 +806,13 @@ public function get_data( $atts, $args ) { case 'event': - // add event ID + // Add event ID $params['id'] = $args['id']; - // call API + // Call API $civi_entity = civicrm_api( 'event', 'getsingle', $params ); - // set title + // Set title switch ( $atts['action'] ) { case 'register': $data['title'] = sprintf( @@ -772,19 +827,19 @@ public function get_data( $atts, $args ) { break; } - // set text, if present + // Set text, if present $data['text'] = ''; if ( isset( $civi_entity['summary'] ) ) { $data['text'] = $civi_entity['summary']; } if ( - // summary is not present or is empty + // Summary is not present or is empty ( !isset($civi_entity['summary']) OR empty($civi_entity['summary']) ) AND - // we do have a description + // We do have a description isset( $civi_entity['description'] ) AND !empty( $civi_entity['description'] ) ) { - // override with description + // Override with description $data['text'] = $civi_entity['description']; } @@ -792,38 +847,38 @@ public function get_data( $atts, $args ) { case 'user-dashboard': - // set title + // Set title $data['title'] = __( 'Dashboard', 'civicrm' ); break; case 'profile': - // add event ID + // Add event ID $params['id'] = $args['gid']; - // call API + // Call API $civi_entity = civicrm_api( 'uf_group', 'getsingle', $params ); - // set title + // Set title $data['title'] = $civi_entity['title']; - // set text to empty + // Set text to empty $data['text'] = ''; break; case 'petition': - // add petition ID + // Add petition ID $params['id'] = $atts['id']; - // call API + // Call API $civi_entity = civicrm_api( 'survey', 'getsingle', $params ); - // set title + // Set title $data['title'] = $civi_entity['title']; - // set text, if present + // Set text, if present $data['text'] = ''; if ( isset( $civi_entity['instructions'] ) ) { $data['text'] = $civi_entity['instructions']; @@ -833,7 +888,7 @@ public function get_data( $atts, $args ) { default: - // do we need to protect against malformed shortcodes? + // Do we need to protect against malformed shortcodes? break; } @@ -844,6 +899,8 @@ public function get_data( $atts, $args ) { * This filter allows plugins or CiviExtensions to modify the data used to * display the shortcode when there are multiple shortcodes being rendered. * + * @since 4.7.28 + * * @param array $data Existing shortcode data * @param array $atts Shortcode attributes array * @param array $args Shortcode arguments array @@ -854,6 +911,6 @@ public function get_data( $atts, $args ) { } -} // class CiviCRM_For_WordPress_Shortcodes ends +} // Class CiviCRM_For_WordPress_Shortcodes ends diff --git a/includes/civicrm.users.php b/includes/civicrm.users.php index 6c387d7..8837137 100644 --- a/includes/civicrm.users.php +++ b/includes/civicrm.users.php @@ -33,64 +33,72 @@ */ -// this file must not accessed directly +// This file must not accessed directly if ( ! defined( 'ABSPATH' ) ) exit; /** - * Define CiviCRM_For_WordPress_Users Class + * Define CiviCRM_For_WordPress_Users Class. + * + * @since 4.6 */ class CiviCRM_For_WordPress_Users { - /** - * Declare our properties + * Plugin object reference. + * + * @since 4.6 + * @access public + * @var object $civi The plugin object reference. */ - - // init property to store reference to Civi public $civi; /** - * Instance constructor + * Instance constructor. * - * @return object $this The object instance + * @since 4.6 */ function __construct() { - // store reference to Civi object + // Store reference to CiviCRM plugin object $this->civi = civi_wp(); } /** - * Register hooks to handle CiviCRM in a WordPress wpBasePage context + * Register hooks. * - * @return void + * @since 4.6 */ public function register_hooks() { - // add CiviCRM access capabilities to WordPress roles + // Add CiviCRM access capabilities to WordPress roles add_action( 'init', array( $this, 'set_access_capabilities' ) ); - // do not hook into user updates if Civi not installed yet + // Do not hook into user updates if CiviCRM not installed yet if ( ! CIVICRM_INSTALLED ) return; - // synchronise users on insert and update + // Synchronise users on insert and update add_action( 'user_register', array( $this, 'update_user' ) ); add_action( 'profile_update', array( $this, 'update_user' ) ); - // delete ufMatch record when a WordPress user is deleted + // Delete ufMatch record when a WordPress user is deleted add_action( 'deleted_user', array( $this, 'delete_user_ufmatch' ), 10, 1 ); } /** + * Check permissions. + * * Authentication function used by basepage_register_hooks() * - * @return bool True if authenticated, false otherwise + * @since 4.6 + * + * @param array $args The page arguments array. + * @return bool True if authenticated, false otherwise. */ public function check_permission( $args ) { @@ -100,12 +108,12 @@ public function check_permission( $args ) { $config = CRM_Core_Config::singleton(); - // set frontend true + // Set frontend true $config->userFrameworkFrontend = TRUE; require_once 'CRM/Utils/Array.php'; - // all profile and file urls, as well as user dashboard and tell-a-friend are valid + // All profile and file urls, as well as user dashboard and tell-a-friend are valid $arg1 = CRM_Utils_Array::value(1, $args); $invalidPaths = array('admin'); if ( in_array( $arg1, $invalidPaths ) ) { @@ -118,9 +126,13 @@ public function check_permission( $args ) { /** + * Get "permission denied" text. + * * Called when authentication fails in basepage_register_hooks() * - * @return string Warning message + * @since 4.6 + * + * @return string Warning message. */ public function get_permission_denied() { return __( 'You do not have permission to access this content.', 'civicrm' ); @@ -128,15 +140,17 @@ public function get_permission_denied() { /** - * Keep WordPress user synced with CiviCRM Contact + * Handle WordPress user events. + * * Callback function for 'user_register' hook * Callback function for 'profile_update' hook * * CMW: seems to (wrongly) create new CiviCRM Contact every time a user changes their * first_name or last_name attributes in WordPress. * + * @since 4.6 + * * @param int $user_id The numeric ID of the WordPress user - * @return void */ public function update_user( $user_id ) { @@ -149,14 +163,15 @@ public function update_user( $user_id ) { /** - * Keep WordPress user synced with CiviCRM Contact + * Keep WordPress user synced with CiviCRM Contact. + * + * @since 4.6 * - * @param object $user The WordPress user object - * @return void + * @param object $user The WordPress user object. */ public function sync_user( $user = FALSE ) { - // sanity check + // Sanity check if ( $user === FALSE OR !is_a($user, 'WP_User') ) { return; } @@ -167,27 +182,29 @@ public function sync_user( $user = FALSE ) { require_once 'CRM/Core/BAO/UFMatch.php'; - // this does not return anything, so if we want to do anything further - // to the CiviCRM Contact, we have to search for it all over again... + /* + * This does not return anything, so if we want to do anything further + * to the CiviCRM Contact, we have to search for it all over again. + */ CRM_Core_BAO_UFMatch::synchronize( - $user, // user object - TRUE, // update = true + $user, // User object + TRUE, // Update = true 'WordPress', // CMS 'Individual' // contact type ); /* - // IN progress: synchronizeUFMatch does return the contact object, however + // IN PROGRESS: synchronizeUFMatch does return the contact object, however $civi_contact = CRM_Core_BAO_UFMatch::synchronizeUFMatch( - $user, // user object + $user, // User object $user->ID, // ID - $user->user_mail, // unique identifier - null // unused + $user->user_mail, // Unique identifier + null // Unused 'WordPress' // CMS 'Individual' // contact type ); - // now we can allow other plugins to do their thing + // Now we can allow other plugins to do their thing do_action( 'civicrm_contact_synced', $user, $civi_contact ); */ @@ -195,11 +212,13 @@ public function sync_user( $user = FALSE ) { /** - * When a WordPress user is deleted, delete the ufMatch record + * When a WordPress user is deleted, delete the ufMatch record. + * * Callback function for 'delete_user' hook * - * @param $user_id The numerical ID of the WordPress user - * @return void + * @since 4.6 + * + * @param $user_id The numerical ID of the WordPress user. */ public function delete_user_ufmatch( $user_id ) { @@ -207,7 +226,7 @@ public function delete_user_ufmatch( $user_id ) { return; } - // delete the ufMatch record + // Delete the ufMatch record require_once 'CRM/Core/BAO/UFMatch.php'; CRM_Core_BAO_UFMatch::deleteUser($user_id); @@ -215,13 +234,16 @@ public function delete_user_ufmatch( $user_id ) { /** - * Function to create 'anonymous_user' role, if 'anonymous_user' role is not in - * the WordPress installation and assign minimum capabilities for all WordPress roles + * Create anonymous role and define capabilities. + * + * Function to create 'anonymous_user' role, if 'anonymous_user' role is not + * in the WordPress installation and assign minimum capabilities for all + * WordPress roles. * - * The legacy global scope function civicrm_wp_set_capabilities() is called from - * upgrade_4_3_alpha1() + * The legacy global scope function civicrm_wp_set_capabilities() is called + * from upgrade_4_3_alpha1() * - * @return void + * @since 4.6 */ public function set_wp_user_capabilities() { @@ -245,7 +267,14 @@ public function set_wp_user_capabilities() { 'view_public_civimail_content' => 1, ); - // allow other plugins to filter + /** + * Allow minimum capabilities to be filtered. + * + * @since 4.6 + * + * @param array $default_min_capabilities The minimum capabilities. + * @return array $default_min_capabilities The modified capabilities. + */ $min_capabilities = apply_filters( 'civicrm_min_capabilities', $default_min_capabilities ); // Assign the Minimum capabilities (Civicrm permissions) to all WP roles @@ -269,23 +298,24 @@ public function set_wp_user_capabilities() { /** - * Add CiviCRM access capabilities to WordPress roles - * this is a callback for the 'init' hook in register_hooks() + * Add CiviCRM access capabilities to WordPress roles. + * + * This is a callback for the 'init' hook in register_hooks(). * * The legacy global scope function wp_civicrm_capability() is called by * postProcess() in civicrm/CRM/ACL/Form/WordPress/Permissions.php * - * @return void + * @since 4.6 */ public function set_access_capabilities() { - // test for existing global + // Test for existing global global $wp_roles; if ( ! isset( $wp_roles ) ) { $wp_roles = new WP_Roles(); } - // give access to civicrm page menu link to particular roles + // Give access to civicrm page menu link to particular roles $roles = apply_filters( 'civicrm_access_roles', array( 'super admin', 'administrator' ) ); foreach ( $roles as $role ) { $roleObj = $wp_roles->get_role( $role ); @@ -302,15 +332,17 @@ public function set_access_capabilities() { /** - * Get CiviCRM contact type + * Get CiviCRM contact type. + * + * @since 4.6 * - * @param string $default contact type - * @return string $ctype contact type + * @param string $default The requested contact type. + * @return string $ctype The computed contact type. */ public function get_civicrm_contact_type( $default = NULL ) { - // here we are creating a new contact - // get the contact type from the POST variables if any + // Here we are creating a new contact + // Get the contact type from the POST variables if any if ( isset( $_REQUEST['ctype'] ) ) { $ctype = $_REQUEST['ctype']; } elseif ( @@ -335,6 +367,6 @@ public function get_civicrm_contact_type( $default = NULL ) { } -} // class CiviCRM_For_WordPress_Users ends +} // Class CiviCRM_For_WordPress_Users ends diff --git a/uninstall.php b/uninstall.php index 7579c21..60c6b5a 100644 --- a/uninstall.php +++ b/uninstall.php @@ -34,9 +34,9 @@ */ -// kick out if uninstall not called from WordPress +// Kick out if uninstall not called from WordPress if ( !defined( 'WP_UNINSTALL_PLUGIN' ) ) { exit(); } -// delete options that this plugin has set +// Delete options that this plugin has set delete_option( 'civicrm_activation_in_progress' );