Update/add documentation to a few classes (like WireCache), correct issue with HTTPS detection on AWS load balancer, plus some other minor tweaks.

2025-08-08 15:57:01 +02:00 · 2017-04-14 06:32:23 -04:00
parent 93779e2017
commit 223b80d685
6 changed files with 140 additions and 47 deletions
--- a/wire/config.php
+++ b/wire/config.php
@@ -293,7 +293,7 @@ $config->sessionCookieSecure = 1;
 * Cookie domain for sessions
 * 
 * Enables a session to traverse multiple subdomains.
- * Specify a string with domain or NULL to disable (default/recommended). 
+ * Specify a string having “.domain.com” (with leading period) or NULL to disable (default/recommended). 
 * 
 * @var string|null
 *
--- a/wire/core/Config.php
+++ b/wire/core/Config.php
@@ -12,6 +12,10 @@
 * https://processwire.com
 * 
 * #pw-summary Holds ProcessWire configuration settings as defined in /wire/config.php and /site/config.php. 
+ * #pw-body =
+ * For more detailed descriptions of these $config properties, including default values, see the
+ * [/wire/config.php](https://github.com/processwire/processwire/blob/master/wire/config.php) file. 
+ * #pw-body
 *
 *
 * @see /wire/config.php for more detailed descriptions of all config properties. 
@@ -57,14 +61,14 @@
 * @property bool|callable $sessionAllow Are sessions allowed? Typically boolean true, unless provided a callable function that returns boolean. See /wire/config.php for an example.  #pw-group-session
 * @property int $sessionExpireSeconds How many seconds of inactivity before session expires? #pw-group-session
 * @property bool $sessionChallenge Should login sessions have a challenge key? (for extra security, recommended) #pw-group-session
- * @property bool $sessionFingerprint Should login sessions be tied to IP and user agent? May conflict with dynamic IPs. #pw-group-session
+ * @property bool $sessionFingerprint Should login sessions be tied to IP and user agent? 0 or false: Fingerprint off. 1 or true: Fingerprint on with default/recommended setting (currently 10). 2: Fingerprint only the remote IP. 4: Fingerprint only the forwarded/client IP (can be spoofed). 8: Fingerprint only the useragent. 10: Fingerprint the remote IP and useragent (default). 12: Fingerprint the forwarded/client IP and useragent. 14: Fingerprint the remote IP, forwarded/client IP and useragent (all). #pw-group-session
 * @property int $sessionHistory Number of session entries to keep (default=0, which means off). #pw-group-session
 * 
 * @property string $prependTemplateFile PHP file in /site/templates/ that will be loaded before each page's template file (default=none) #pw-group-template-files
 * @property string $appendTemplateFile PHP file in /site/templates/ that will be loaded after each page's template file (default=none) #pw-group-template-files
 * @property bool $templateCompile Allow use of compiled templates? #pw-group-template-files
 * 
- * @property string $uploadUnzipCommand Shell command to unzip archives, used by WireUpload class. @deprecated #pw-group-deprecated
+ * @property string $uploadUnzipCommand Shell command to unzip archives, used by WireUpload class. #pw-group-deprecated
 * @property string $uploadTmpDir Optionally override PHP's upload_tmp_dir with your own. Should include a trailing slash. #pw-group-files
 * @property string $uploadBadExtensions Space separated list of file extensions that are always disallowed from uploads. #pw-group-files
 * 
@@ -135,26 +139,26 @@
 * @property int $inputfieldColumnWidthSpacing Used by some admin themes to commmunicate to InputfieldWrapper at runtime. #pw-internal
 * @property bool $debugMarkupQA Set to true to make the MarkupQA class report verbose debugging messages (to superusers). #pw-internal
 * 
- * @property int $rootPageID ID of homepage (usually 1) #pw-group-system-IDs
- * @property int $adminRootPageID ID of admin root page #pw-group-system-IDs
- * @property int $trashPageID #pw-group-system-IDs
- * @property int $loginPageID #pw-group-system-IDs
- * @property int $http404PageID #pw-group-system-IDs
- * @property int $usersPageID #pw-group-system-IDs
+ * @property int $rootPageID Page ID of homepage (usually 1) #pw-group-system-IDs
+ * @property int $adminRootPageID Page ID of admin root page #pw-group-system-IDs
+ * @property int $trashPageID Page ID of the trash page. #pw-group-system-IDs
+ * @property int $loginPageID Page ID of the admin login page. #pw-group-system-IDs
+ * @property int $http404PageID Page ID of the 404 “page not found” page. #pw-group-system-IDs
+ * @property int $usersPageID Page ID of the page having users as children. #pw-group-system-IDs
 * @property array $usersPageIDs Populated if multiple possible users page IDs (parent for users pages) #pw-group-system-IDs
- * @property int $rolesPageID #pw-group-system-IDs
- * @property int $permissionsPageID #pw-group-system-IDs
- * @property int $guestUserPageID #pw-group-system-IDs
- * @property int $superUserPageID #pw-group-system-IDs
- * @property int $guestUserRolePageID #pw-group-system-IDs
- * @property int $superUserRolePageID #pw-group-system-IDs
- * @property int $userTemplateID #pw-group-system-IDs
+ * @property int $rolesPageID Page ID of the page having roles as children. #pw-group-system-IDs
+ * @property int $permissionsPageID Page ID of the page having permissions as children. #pw-group-system-IDs
+ * @property int $guestUserPageID Page ID of the guest (default/not-logged-in) user. #pw-group-system-IDs
+ * @property int $superUserPageID Page ID of the original superuser (created during installation). #pw-group-system-IDs
+ * @property int $guestUserRolePageID Page ID of the guest user role (inherited by all users, not just guest). #pw-group-system-IDs
+ * @property int $superUserRolePageID Page ID of the superuser role. #pw-group-system-IDs
+ * @property int $userTemplateID Template ID of the user template. #pw-group-system-IDs
 * @property array $userTemplateIDs Array of template IDs when multiple allowed for users.  #pw-group-system-IDs
- * @property int $roleTemplateID #pw-group-system-IDs
- * @property int $permissionTemplateID #pw-group-system-IDs
- * @property int $externalPageID ID of page assigned to $page API variable when externally bootstrapped #pw-group-system-IDs
- * @property array $preloadPageIDs IDs of pages that will be preloaded at beginning of request #pw-group-system-IDs
- * @property int $installed Timestamp of when this PW was installed, set automatically for compatibility detection. #pw-group-system
+ * @property int $roleTemplateID Template ID of the role template. #pw-group-system-IDs
+ * @property int $permissionTemplateID Template ID of the permission template. #pw-group-system-IDs
+ * @property int $externalPageID Page ID of page assigned to $page API variable when externally bootstrapped #pw-group-system-IDs
+ * @property array $preloadPageIDs Page IDs of pages that will always be preloaded at beginning of request #pw-group-system-IDs
+ * @property int $installed Timestamp of when this PW was installed, set automatically by the installer for future compatibility detection. #pw-group-system
 *
 */
 class Config extends WireData {
--- a/wire/core/Pages.php
+++ b/wire/core/Pages.php
@@ -1585,6 +1585,8 @@ class Pages extends Wire {
 	/**
 	 * Hook called after a page has been sorted, or had its children re-sorted
 	 * 
+	 * #pw-hooker
+	 * 
 	 * @param Page $page Page given to have sort adjusted
 	 * @param bool $children If true, children of $page have been all been re-sorted
 	 * @param int $total Total number of pages that had sort adjusted as a result
--- a/wire/core/ProcessWire.php
+++ b/wire/core/ProcessWire.php
@@ -253,7 +253,8 @@ class ProcessWire extends Wire {

 		if($config->https === null) {
 			$config->https = (!empty($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) == 'on')
-				|| (isset($_SERVER['SERVER_PORT']) && $_SERVER['SERVER_PORT'] == 443);
+				|| (isset($_SERVER['SERVER_PORT']) && $_SERVER['SERVER_PORT'] == 443)
+				|| (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && strtolower($_SERVER['HTTP_X_FORWARDED_PROTO']) == 'https'); // AWS LOAD BALANCER
 		}
 		
 		$config->ajax = (isset($_SERVER['HTTP_X_REQUESTED_WITH']) && $_SERVER['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest');
--- a/wire/core/Wire.php
+++ b/wire/core/Wire.php
@@ -15,8 +15,11 @@
 * classes that are hooking into others. 
 * #pw-body
 * #pw-order-groups common,identification,hooks,notices,changes,hooker,api-helpers
+ * #pw-summary-api-helpers Shortcuts to ProcessWire API variables. Access without any arguments returns the API variable. Some support arguments as shortcuts to methods in the API variable.
+ * #pw-summary-changes Methods to support tracking and retrieval of changes made to the object.
+ * #pw-summary-hooks Methods for managing hooks for an object instance or class. 
 * 
- * ProcessWire 3.x, Copyright 2016 by Ryan Cramer
+ * ProcessWire 3.x, Copyright 2017 by Ryan Cramer
 * https://processwire.com
 * 
 * #pw-use-constants
@@ -76,7 +79,7 @@
 * @method WireFileTools files() Access the $files API variable as a function.  #pw-group-api-helpers
 * @method WireCache|string|array|PageArray|null cache($name = '', $expire = null, $func = null) Access the $cache API variable as a function.  #pw-group-api-helpers
 * @method Languages|Language|NullPage|null languages($name = '') Access the $languages API variable as a function.  #pw-group-api-helpers
- * @method WireInput|WireInputData array|string|int|null input($type = '', $key = '', $sanitizer = '') Access the $input API variable as a function.  #pw-group-api-helpers
+ * @method WireInput|WireInputData|array|string|int|null input($type = '', $key = '', $sanitizer = '') Access the $input API variable as a function.  #pw-group-api-helpers
 * @method WireInputData|string|int|array|null inputGet($key = '', $sanitizer = '') Access the $input->get() API variable as a function.  #pw-group-api-helpers
 * @method WireInputData|string|int|array|null inputPost($key = '', $sanitizer = '') Access the $input->post() API variable as a function.  #pw-group-api-helpers
 * @method WireInputData|string|int|array|null inputCookie($key = '', $sanitizer = '') Access the $input->cookie() API variable as a function.  #pw-group-api-helpers
--- a/wire/core/WireCache.php
+++ b/wire/core/WireCache.php
@@ -107,6 +107,8 @@ class WireCache extends Wire {
 	 * 
 	 * After a preloaded cache is returned from a get() call, it is removed from local storage. 
 	 * 
+	 * #pw-group-advanced
+	 * 
 	 * @param string|array $names
 	 * @param int|string|null $expire
 	 * 
@@ -119,6 +121,8 @@ class WireCache extends Wire {
 	/**
 	 * Preload all caches for the given object or namespace
 	 * 
+	 * #pw-group-advanced
+	 * 
 	 * @param object|string $ns
 	 * @param int|string|null $expire
 	 * 
@@ -134,18 +138,39 @@ class WireCache extends Wire {
 	 * 
 	 * Optionally specify expiration time and/or a cache generation function to use when cache needs to be created.
 	 * 
+	 * Cached value can be a string, an array of non-object values, or a PageArray. 
+	 * 
+	 * ~~~~~
+	 * // get single cache value 
+	 * $str = $cache->get('foo');
+	 * 
+	 * // get 3 cached values, returns associative array with foo, bar, baz indexes
+	 * $array = $cache->get([ 'foo', 'bar', 'baz' ]);
+	 * 
+	 * // get all cache values with names starting with “hello”
+	 * $array = $cache->get('hello*');
+	 * 
+	 * // get cache only if it’s less than or equal to 1 hour old (3600 seconds)
+	 * $str = $cache->get('foo', 3600);
+	 * 
+	 * // same as above, but also generates the cache value with function when expired
+	 * $str = $cache->get('foo', 3600, function() {
+	 *   return "This is the cached value";
+	 * });
+	 * ~~~~~
+	 * 
 	 * @param string|array $name Provide a single cache name, an array of cache names, or an asterisk cache name.
-	 * 	If given a single cache name (string) just the contents of that cache will be returned.
-	 * 	If given an array of names, multiple caches will be returned, indexed by cache name. 
-	 * 	If given a cache name with an asterisk in it, it will return an array of all matching caches. 
+	 * - If given a single cache name (string) just the contents of that cache will be returned.
+	 * - If given an array of names, multiple caches will be returned, indexed by cache name. 
+	 * - If given a cache name with an asterisk in it, it will return an array of all matching caches. 
 	 * @param int|string|null $expire Optionally specify max age (in seconds) OR oldest date string.
-	 * 	If cache exists and is older, then blank returned. You may omit this to divert to whatever expiration
-	 * 	was specified at save() time. Note: The $expire and $func arguments may optionally be reversed. 
-	 * 	If using a $func, the behavior of $expire becomes the same as that of save(). 
+	 * - If cache exists and is older, then blank returned. You may omit this to divert to whatever expiration
+	 *   was specified at save() time. Note: The $expire and $func arguments may optionally be reversed. 
+	 * - If using a $func, the behavior of $expire becomes the same as that of save(). 
 	 * @param callable $func Optionally provide a function/closure that generates the cache value and it 
-	 * 	will be used when needed.This option requires that only one cache is being retrieved (not an array of caches). 
+	 * 	will be used when needed. This option requires that only one cache is being retrieved (not an array of caches). 
 	 * 	Note: The $expire and $func arguments may optionally be reversed. 
-	 * @return string|array|PageArray|mixed|null Returns null if cache doesn't exist and no generation function provided. 
+	 * @return string|array|PageArray|mixed|null Returns null if cache doesn’t exist and no generation function provided. 
 	 * @throws WireException if given invalid arguments
 	 * 
 	 * 
@@ -320,11 +345,25 @@ class WireCache extends Wire {
 	/**
 	 * Same as get() but with namespace
 	 * 
+	 * Namespace is useful to avoid cache name collisions. The ProcessWire core commonly uses cache 
+	 * namespace to bind cache values to the object class, which often make a good namespace. 
+	 * 
+	 * Please see the `$cache->get()` method for usage of all arguments. 
+	 * 
+	 * ~~~~~
+	 * // specify namespace as a string
+	 * $value = $cache->getFor('my-namespace', 'my-cache-name');
+	 * 
+	 * // or specify namespace is an object instance
+	 * $value = $cache->get($this, 'my-cache-name'); 
+	 * ~~~~~
+	 * 
 	 * @param string|object $ns Namespace
-	 * @param string $name
-	 * @param null|int|string $expire
-	 * @param callable|null $func
-	 * @return string|array
+	 * @param string $name Cache name
+	 * @param null|int|string $expire Optional expiration
+	 * @param callable|null $func Optional cache generation function
+	 * @return string|array|PageArray|mixed|null Returns null if cache doesn’t exist and no generation function provided. 
+	 * @see WireCache::get()
 	 * 
 	 */
 	public function getFor($ns, $name, $expire = null, $func = null) {
@@ -335,17 +374,27 @@ class WireCache extends Wire {
 	/**
 	 * Save data to cache with given name
 	 * 
+	 * ~~~~~
+	 * $value = "This is the value that will be cached.";
+	 * 
+	 * // cache the value, using default expiration (daily)
+	 * $cache->save("my-cache-name", $value); 
+	 * 
+	 * // cache the value, and expire after 1 hour (3600 seconds)
+	 * $cache->save("my-cache-name", $value, 3600); 
+	 * ~~~~~
+	 * 
 	 * @param string $name Name of cache, can be any string up to 255 chars
-	 * @param string|array|PageArray $data Data that you want to cache 
+	 * @param string|array|PageArray $data Data that you want to cache. May be string, array of non-object values, or PageArray.
 	 * @param int|Page $expire Lifetime of this cache, in seconds, OR one of the following:
 	 *  - Specify one of the `WireCache::expire*` constants. 
-	 *  - Specify the future date you want it to expire (as unix timestamp or any strtotime compatible date format)  
-	 *  - Provide a Page object to expire when any page using that template is saved.  
+	 *  - Specify the future date you want it to expire (as unix timestamp or any `strtotime()` compatible date format)  
+	 *  - Provide a `Page` object to expire when any page using that template is saved.  
 	 *  - Specify `WireCache::expireNever` to prevent expiration.  
 	 *  - Specify `WireCache::expireSave` to expire when any page or template is saved.   
-	 *  - Specify selector string matching pages that, when saved, expire the cache.   
+	 *  - Specify selector string matching pages that–when saved–expire the cache.   
 	 * @return bool Returns true if cache was successful, false if not
-	 * @throws WireException if given uncachable data
+	 * @throws WireException if given data that cannot be cached
 	 * 
 	 */
 	public function save($name, $data, $expire = self::expireDaily) {
@@ -403,13 +452,24 @@ class WireCache extends Wire {
 	/**
 	 * Same as save() except with namespace
 	 * 
+	 * Namespace is useful to avoid cache name collisions. The ProcessWire core commonly uses cache
+	 * namespace to bind cache values to the object class, which often make a good namespace.
+	 * 
+	 * ~~~~~
+	 * // save cache using manually specified namespace
+	 * $cache->save("my-namespace", "my-cache-name", $value);
+	 * 
+	 * // save cache using namespace of current object
+	 * $cache->save($this, "my-cache-name", $value); 
+	 * ~~~~~
+	 *
 	 * @param string|object $ns Namespace for cache
 	 * @param string $name Name of cache, can be any string up to 255 chars
 	 * @param string|array|PageArray $data Data that you want to cache
 	 * @param int|Page $expire Lifetime of this cache, in seconds, OR one of the following:
 	 *  - Specify one of the `WireCache::expire*` constants.
 	 *  - Specify the future date you want it to expire (as unix timestamp or any strtotime compatible date format)
-	 *  - Provide a Page object to expire when any page using that template is saved.
+	 *  - Provide a `Page` object to expire when any page using that template is saved.
 	 *  - Specify `WireCache::expireNever` to prevent expiration.
 	 *  - Specify `WireCache::expireSave` to expire when any page or template is saved.
 	 *  - Specify selector string matching pages that, when saved, expire the cache.
@@ -422,7 +482,7 @@ class WireCache extends Wire {
 	}

 	/**
-	 * Given a $expire seconds, date, page, or template convert it to an ISO-8601 date
+	 * Given an expiration seconds, date, page, or template, convert it to an ISO-8601 date
 	 * 
 	 * Returns an array of expires info requires multiple parts, like with self::expireSelector.
 	 * In this case it returns array with array('expires' => date, 'selector' => selector);
@@ -498,7 +558,15 @@ class WireCache extends Wire {
 	}

 	/**
-	 * Delete/clear the cache(s) identified by $name
+	 * Delete/clear the cache(s) identified by given name or wildcard
+	 * 
+	 * ~~~~~
+	 * // Delete cache named "my-cache-name"
+	 * $cache->delete("my-cache-name");
+	 * 
+	 * // Delete all caches starting with "my-"
+	 * $cache->delete("my-*");
+	 * ~~~~~
 	 * 
 	 * @param string $name Name of cache, or partial name with wildcard (i.e. "MyCache*") to clear multiple caches. 
 	 * @return bool True on success, false on failure
@@ -527,10 +595,18 @@ class WireCache extends Wire {
 	}

 	/**
-	 * Delete the cache identified by $name within given namespace ($ns)
+	 * Delete one or more caches in a given namespace
+	 * 
+	 * ~~~~~
+	 * // Delete all in namespace
+	 * $cache->deleteFor("my-namespace"); 
+	 * 
+	 * // Delete one cache in namespace
+	 * $cache->deleteFor("my-namespace", "my-cache-name"); 
+	 * ~~~~~
 	 *
-	 * @param string $ns Namespace of cache
-	 * @param string $name If none specified, all for $ns are deleted
+	 * @param string $ns Namespace of cache.
+	 * @param string $name Name of cache. If none specified, all for namespace are deleted.
 	 * @return bool True on success, false on failure
 	 *
 	 */
@@ -544,6 +620,9 @@ class WireCache extends Wire {
 	 * Cache maintenance removes expired caches
 	 * 
 	 * Should be called as part of a regular maintenance routine and after page/template save/deletion.
+	 * ProcessWire already calls this automatically, so you don’t typically need to call this method on your own. 
+	 * 
+	 * #pw-group-advanced
 	 * 
 	 * @param Template|Page|null|bool Item to run maintenance for or, if not specified, general maintenance is performed.
 	 * 	General maintenance only runs once per request. Specify boolean true to force general maintenance to run.
@@ -796,6 +875,8 @@ class WireCache extends Wire {
 	/**
 	 * Get information about all the caches in this WireCache
 	 * 
+	 * #pw-group-advanced
+	 * 
 	 * @param bool $verbose Whether to be more verbose for human readability
 	 * @param string $name Optionally specify name of cache to get info. If omitted, all caches are included.
 	 * @return array of arrays of cache info
@@ -874,6 +955,8 @@ class WireCache extends Wire {

 	/**
 	 * Save to the cache log
+	 * 
+	 * #pw-internal
 	 *
 	 * @param string $str Message to log
 	 * @param array $options