diff --git a/wire/config.php b/wire/config.php index 32c8db0c..85490ce7 100644 --- 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 * diff --git a/wire/core/Config.php b/wire/core/Config.php index 41ef4adf..50c5d46a 100644 --- 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 { diff --git a/wire/core/Pages.php b/wire/core/Pages.php index f8c12af6..27078de1 100644 --- 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 diff --git a/wire/core/ProcessWire.php b/wire/core/ProcessWire.php index 9927372a..f12304ba 100644 --- 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'); diff --git a/wire/core/Wire.php b/wire/core/Wire.php index c58b3cc1..a9510ad1 100644 --- 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 diff --git a/wire/core/WireCache.php b/wire/core/WireCache.php index 53e95d96..e6f553b7 100644 --- 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