Unverified Commit 80e91bd8 authored by kcristiano's avatar kcristiano Committed by GitHub

Merge pull request #137 from christianwach/codestyle

NFC: Give comments and docblocks some TLC
parents a3abbdc7 1c10119f
......@@ -65,35 +65,35 @@ http://make.wordpress.org/core/handbook/coding-standards/javascript/
*/
// 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 @@ if ( !defined( 'CIVICRM_SETTINGS_PATH' ) ) {
}
// 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 @@ class CiviCRM_For_WordPress {
/**
* 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 @@ class CiviCRM_For_WordPress {
/**
* 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 @@ class CiviCRM_For_WordPress {
/**
* 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 @@ class CiviCRM_For_WordPress {
// 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 @@ class CiviCRM_For_WordPress {
$_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 @@ class CiviCRM_For_WordPress {
* (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 @@ class CiviCRM_For_WordPress {
*
* @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 @@ class CiviCRM_For_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 @@ class CiviCRM_For_WordPress {
/**
* 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 @@ class CiviCRM_For_WordPress {
/**
* 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 @@ class CiviCRM_For_WordPress {
*/
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 @@ class CiviCRM_For_WordPress {
/**
* 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 @@ class CiviCRM_For_WordPress {
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 <a href="%s">WordPress Installation Guide</a> and the <a href="%s">Trouble-shooting page</a> for assistance. If you still need help installing, you can often find solutions to your issue by searching for the error message in the <a href="%s">installation support section of the community forum</a>.', 'civicrm' ),
$docLinkInstall,
......@@ -621,7 +688,7 @@ class CiviCRM_For_WordPress {
$forumLink
);
// does install message get used?
// Does install message get used?
$installMessage = sprintf(
__( 'Click <a href="%s">here</a> for fresh install.', 'civicrm' ),
$installLink
......@@ -632,20 +699,20 @@ class CiviCRM_For_WordPress {
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 @@ class CiviCRM_For_WordPress {
"</p><p class='error'>" . $errorMsgAdd . "</p></strong>"
);
// 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