Add apigen to version control

.gitignore

@@ -69,4 +69,3 @@ vendor
 
 # General
 NOTES.md
-apigen/

apigen/apigen.neon

@@ -0,0 +1,75 @@
+# source:
+#   - bootstrap.php
+#   - example-functions.php
+#   - init.php
+#   - includes
+#   - tests
+source: ./
+
+destination: ../../../../wpengine/api
+# list of scanned file extensions (e.g. php5, phpt...)
+extensions: [php]
+
+# directories and files matching this file mask will not be parsed
+exclude:
+    - node_modules/
+    - tmp/
+    - apigen/
+    - css/
+    - images/
+    - js/
+    - languages/
+    - vendor/
+
+# # similar to above, but this files will be included in class tree
+# skipDocPath:
+#     - *Component\Console
+
+# character set of source files; if you use only one across your files, we recommend you name it
+charset: [UTF-8]
+
+# title of generated documentation
+main: CMB2
+
+# title of generated documentation
+title: CMB2 Documentation
+
+# base url used for sitemap (useful for public doc)
+baseUrl: https://cmb2.io/api
+
+# custom search engine id, will be used by search box
+googleCseId: 001227520415713999821:rbrooe8zpyi
+
+# Google Analytics tracking code
+googleAnalytics: UA-61730501-1
+
+# choose ApiGen template theme
+templateTheme: bootstrap # or: default
+templateConfig: apigen/theme-bootstrap/src/config.neon
+
+# the way elements are grouped in menu
+groups: packages # also: namespace, packages, none; auto will detect namespace first, than packages
+
+# access levels of included method and properties
+accessLevels: [public, protected, private] # also [private]
+
+# include elements marked as @internal/{@internal}
+internal: true
+
+# generate documentation for PHP internal classes
+php: false
+
+# generate highlighted source code for elements
+sourceCode: true
+
+# generate tree view of classes, interfaces, traits and exceptions
+tree: true
+
+# generate documentation for deprecated elements
+deprecated: true
+
+# generate list of tasks with @todo annotation
+todo: true
+
+# add link to ZIP archive of documentation
+download: true

apigen/hook-docs.php

@@ -0,0 +1,279 @@
+<?php
+/**
+ * Generate documentation for hooks in CMB2
+ * Credit: https://github.com/woothemes/woocommerce/blob/master/apigen/hook-docs.php
+ */
+class CMB2_Hook_Finder {
+	private static $current_file           = '';
+	private static $files_to_scan          = array();
+	private static $pattern_custom_actions = '/do_action(.*?);/i';
+	private static $pattern_custom_filters = '/apply_filters(.*?);/i';
+	private static $found_files            = array();
+	private static $custom_hooks_found     = '';
+
+	private static function get_files( $pattern, $flags = 0, $path = '' ) {
+
+	    if ( ! $path && ( $dir = dirname( $pattern ) ) != '.' ) {
+
+	        if ($dir == '\\' || $dir == '/') { $dir = ''; } // End IF Statement
+
+	        return self::get_files(basename( $pattern ), $flags, $dir . '/' );
+
+	    } // End IF Statement
+	    $paths = glob( $path . '*', GLOB_ONLYDIR | GLOB_NOSORT );
+	    $files = glob( $path . $pattern, $flags );
+
+	    if ( is_array( $paths ) ) {
+		    foreach ( $paths as $p ) {
+			    $found_files = array();
+		   		$retrieved_files = (array) self::get_files( $pattern, $flags, $p . '/' );
+		   		foreach ( $retrieved_files as $file ) {
+			   		if ( ! in_array( $file, self::$found_files ) )
+			   			$found_files[] = $file;
+		   		}
+
+		   		self::$found_files = array_merge( self::$found_files, $found_files );
+
+		   		if ( is_array( $files ) && is_array( $found_files ) ) {
+		   			$files = array_merge( $files, $found_files );
+		   		}
+
+		    } // End FOREACH Loop
+	    }
+	    return $files;
+    }
+
+	private static function get_hook_link( $hook, $details = array() ) {
+		if ( ! empty( $details['class'] ) ) {
+			$link = 'https://cmb2.io/api//source-class-' . $details['class'] . '.html#' . $details['line'];
+		} elseif ( ! empty( $details['function'] ) ) {
+			$link = 'https://cmb2.io/api//source-function-' . $details['function'] . '.html#' . $details['line'];
+		} else {
+			$link = 'https://github.com/CMB2/CMB2/search?utf8=%E2%9C%93&q=' . $hook;
+		}
+
+		if ( false !== strpos( $hook, '{' ) || false !== strpos( $hook, '$' ) ) {
+			$hook = '"'. $hook .'"';
+		} else {
+			$hook = "'$hook'";
+		}
+
+		return '<a href="' . $link . '">' . $hook . '</a>';
+	}
+
+	public static function process_hooks() {
+		// If we have one, get the PHP files from it.
+		$class_files = self::get_files( '*.php', GLOB_MARK, dirname( __FILE__ ) . '/../includes/' );
+		$class_files[] = dirname( __FILE__ ) . '/../init.php';
+
+		self::$files_to_scan = array(
+			'Hooks' => $class_files,
+		);
+
+		$scanned = array();
+
+		ob_start();
+
+		echo '<div id="content">';
+		echo '<h1>WordPress Action and Filter Hook Reference</h1>';
+
+		foreach ( self::$files_to_scan as $heading => $files ) {
+			self::$custom_hooks_found = array();
+
+			foreach ( $files as $f ) {
+				self::$current_file = basename( $f );
+				$tokens             = token_get_all( file_get_contents( $f ) );
+				$token_type         = false;
+				$current_class      = '';
+				$current_function   = '';
+
+				if ( in_array( self::$current_file, $scanned ) ) {
+					continue;
+				}
+
+				$scanned[] = self::$current_file;
+
+				foreach ( $tokens as $index => $token ) {
+					if ( is_array( $token ) ) {
+						if ( $token[0] == T_CLASS ) {
+							$token_type = 'class';
+						} elseif ( $token[0] == T_FUNCTION ) {
+							$token_type = 'function';
+						} elseif ( $token[1] === 'do_action' ) {
+							$token_type = 'action';
+						} elseif ( $token[1] === 'apply_filters' ) {
+							$token_type = 'filter';
+						} elseif ( $token_type && ! empty( trim( $token[1] ) ) ) {
+							switch ( $token_type ) {
+								case 'class' :
+									$current_class = $token[1];
+								break;
+								case 'function' :
+									$current_function = $token[1];
+								break;
+								case 'filter' :
+								case 'action' :
+									$hook = trim( $token[1], "'" );
+									$loop = 0;
+
+									if ( '_' === substr( $hook, '-1', 1 ) ) {
+										$hook .= '{';
+										$open = true;
+										// Keep adding to hook until we find a comma or colon
+										while ( 1 ) {
+											$loop ++;
+											$next_hook  = trim( trim( is_string( $tokens[ $index + $loop ] ) ? $tokens[ $index + $loop ] : $tokens[ $index + $loop ][1], '"' ), "'" );
+
+											if ( in_array( $next_hook, array( '.', '{', '}', '"', "'", ' ' ) ) ) {
+												continue;
+											}
+
+											$hook_first = substr( $next_hook, 0, 1 );
+											$hook_last  = substr( $next_hook, -1, 1 );
+
+											if ( in_array( $next_hook, array( ',', ';' ), true ) ) {
+												if ( $open ) {
+													$hook .= '}';
+													$open = false;
+												}
+												break;
+											}
+
+											if ( '_' === $hook_first ) {
+												// Because CMB2 uses an _id() method
+												if ( '_id' !== $next_hook ) {
+													$next_hook = '}' . $next_hook;
+													$open = false;
+												}
+											}
+
+											if ( '_' === $hook_last ) {
+												$next_hook .= '{';
+												$open = true;
+											}
+
+											$hook .= $next_hook;
+											// echo '<xmp>$hook: '. print_r( $hook, true ) .'</xmp>';
+										}
+									}
+
+									if ( isset( self::$custom_hooks_found[ $hook ] ) ) {
+										self::$custom_hooks_found[ $hook ]['file'][] = self::$current_file;
+									} else {
+    									self::$custom_hooks_found[ $hook ] = array(
+											'line'     => $token[2],
+											'class'    => $current_class,
+											'function' => $current_function,
+											'file'     => array( self::$current_file ),
+											'type'     => $token_type
+										);
+									}
+								break;
+							}
+							$token_type = false;
+						}
+					}
+				}
+			}
+			// die( '<xmp>self::$custom_hooks_found: '. print_r( self::$custom_hooks_found, true ) .'</xmp>' );
+
+			foreach ( self::$custom_hooks_found as $hook => $details ) {
+				if ( ! strstr( $hook, 'cmb2' ) ) {
+					unset( self::$custom_hooks_found[ $hook ] );
+				}
+			}
+
+			ksort( self::$custom_hooks_found );
+
+			if ( ! empty( self::$custom_hooks_found ) ) {
+				$actions = self::wp_list_filter( self::$custom_hooks_found, array( 'type' => 'action' ) );
+				$filters = self::wp_list_filter( self::$custom_hooks_found, array( 'type' => 'filter' ) );
+
+				echo '<div class="panel panel-default"><div class="panel-heading"><h2>Action Hooks</h2></div>';
+
+				echo '<table class="summary table table-bordered table-striped"><thead><tr><th>Hook</th><th>File(s)</th></tr></thead><tbody>';
+
+				foreach ( $actions as $hook => $details ) {
+					echo '<tr>
+						<td>' . self::get_hook_link( $hook, $details ) . '</td>
+						<td>' . implode( ', ', array_unique( $details['file'] ) ) . '</td>
+					</tr>' . "\n";
+				}
+
+				echo '</tbody></table></div>';
+				echo '<div class="panel panel-default"><div class="panel-heading"><h2>Filter Hooks</h2></div>';
+
+				echo '<table class="summary table table-bordered table-striped"><thead><tr><th>Hook</th><th>File(s)</th></tr></thead><tbody>';
+
+				foreach ( $filters as $hook => $details ) {
+					echo '<tr>
+						<td>' . self::get_hook_link( $hook, $details ) . '</td>
+						<td>' . implode( ', ', array_unique( $details['file'] ) ) . '</td>
+					</tr>' . "\n";
+				}
+
+				echo '</tbody></table></div>';
+			}
+		}
+
+		echo '</div><div id="footer">';
+
+		$html   = file_get_contents( '/Users/JT/Sites/wpengine/api/tree.html' );
+		$header = explode( '<div id="content">', $html );
+		$header = str_replace( '<li class="active">', '<li>', current( $header ) );
+		$header = str_replace( '<li class="hooks">', '<li class="active">', $header );
+		$header = str_replace( '<li class="hooks">', '<li class="active">', $header );
+		$header = str_replace( 'Tree | ', 'Hook Reference | ', $header );
+		$footer = explode( '<div id="footer">', $html );
+
+		file_put_contents( '/Users/JT/Sites/wpengine/api/hook-docs.html', $header . ob_get_clean() . end( $footer ) );
+		echo "Hook docs generated :)\n";
+	}
+
+	/**
+	 * Filters a list of objects, based on a set of key => value arguments.
+	 *
+	 * @since 3.1.0
+	 *
+	 * @param array  $list     An array of objects to filter.
+	 * @param array  $args     Optional. An array of key => value arguments to match
+	 *                         against each object. Default empty array.
+	 * @param string $operator Optional. The logical operation to perform. 'AND' means
+	 *                         all elements from the array must match. 'OR' means only
+	 *                         one element needs to match. 'NOT' means no elements may
+	 *                         match. Default 'AND'.
+	 * @return array Array of found values.
+	 */
+	protected static function wp_list_filter( $list, $args = array(), $operator = 'AND' ) {
+		if ( ! is_array( $list ) )
+			return array();
+
+		if ( empty( $args ) )
+			return $list;
+
+		$operator = strtoupper( $operator );
+		$count = count( $args );
+		$filtered = array();
+
+		foreach ( $list as $key => $obj ) {
+			$to_match = (array) $obj;
+
+			$matched = 0;
+			foreach ( $args as $m_key => $m_value ) {
+				if ( array_key_exists( $m_key, $to_match ) && $m_value == $to_match[ $m_key ] )
+					$matched++;
+			}
+
+			if ( ( 'AND' == $operator && $matched == $count )
+			  || ( 'OR' == $operator && $matched > 0 )
+			  || ( 'NOT' == $operator && 0 == $matched ) ) {
+				$filtered[$key] = $obj;
+			}
+		}
+
+		return $filtered;
+	}
+}
+
+CMB2_Hook_Finder::process_hooks();
+

apigen/theme-bootstrap/.gitattributes

@@ -0,0 +1 @@
+screenshot.png export-ignore

apigen/theme-bootstrap/LICENSE

@@ -0,0 +1,26 @@
+The MIT License
+---------------
+
+- Copyright (c) 2012 [Olivier Laviale](https://github.com/olvlvl)
+- Copyright (c) 2014 [Tomáš Votruba](http://tomasvotruba.cz)
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

apigen/theme-bootstrap/README.md

@@ -0,0 +1,8 @@
+# Twitter Bootstrap Theme
+
+[![Downloads this Month](https://img.shields.io/packagist/dm/apigen/theme-bootstrap.svg?style=flat-square)](https://packagist.org/packages/apigen/theme-bootstrap)
+[![Latest stable](https://img.shields.io/packagist/v/apigen/theme-bootstrap.svg?style=flat-square)](https://packagist.org/packages/apigen/theme-bootstrap)
+
+Uses [Twitter Bootstrap 3.3.2](https://github.com/twbs/bootstrap/releases/tag/v3.3.2), *released on 2015-01-19* 
+
+![Twitter Bootstrap Theme](screenshot.png)