From a07855c9f6bd3e38e3bb799e4547274b5a6d7516 Mon Sep 17 00:00:00 2001 From: Ryan Cramer Date: Wed, 2 Aug 2017 11:16:32 -0400 Subject: [PATCH] Minor adjustments, mostly phpdoc related --- wire/core/Roles.php | 8 ++- wire/core/Sanitizer.php | 6 +- wire/core/Templates.php | 137 ++++++++++++++++++++++++++++++++++++++-- wire/core/WireHooks.php | 6 +- 4 files changed, 145 insertions(+), 12 deletions(-) diff --git a/wire/core/Roles.php b/wire/core/Roles.php index 0ae88f35..96722048 100644 --- a/wire/core/Roles.php +++ b/wire/core/Roles.php @@ -28,7 +28,7 @@ class Roles extends PagesType { * * #pw-internal * - * @return Role + * @return Role|NullPage|Page * @throws WireException * */ @@ -84,8 +84,8 @@ class Roles extends PagesType { * * #pw-group-manipulation * - * @param string $name Name of permission you want to add, i.e. "hello-world" - * @return Role|Page|NullPage Returns a Permission page on success, or a NullPage on error + * @param string $name Name of role you want to add, i.e. "hello-world" + * @return Role|Page|NullPage Returns a Role page on success, or a NullPage on error * */ public function ___add($name) { @@ -96,6 +96,8 @@ class Roles extends PagesType { * Ensure that every role has at least 'page-view' permission * * #pw-internal + * + * @param Page $page * */ protected function loaded(Page $page) { diff --git a/wire/core/Sanitizer.php b/wire/core/Sanitizer.php index 9861fc0d..f5b9aa42 100644 --- a/wire/core/Sanitizer.php +++ b/wire/core/Sanitizer.php @@ -116,8 +116,10 @@ class Sanitizer extends Wire { } } - $v = iconv("UTF-8", "ASCII//TRANSLIT//IGNORE", $value); - if($v) $value = $v; + if(function_exists("\\iconv")) { + $v = iconv("UTF-8", "ASCII//TRANSLIT//IGNORE", $value); + if($v) $value = $v; + } $needsWork = strlen(str_replace($allowed, '', $value)); } diff --git a/wire/core/Templates.php b/wire/core/Templates.php index 866794c0..799ebf61 100644 --- a/wire/core/Templates.php +++ b/wire/core/Templates.php @@ -13,7 +13,9 @@ * @method TemplatesArray find($selector) Return the templates matching the the given selector query. #pw-internal * @method bool save(Template $template) Save the given Template. * @method bool delete() delete(Template $template) Delete the given Template. Note that this will throw a fatal error if the template is in use by any pages. - * @method bool|Saveable|Template clone(Saveable $item, $name = '') + * @method bool|Saveable|Template clone(Saveable $item, $name = '') #pw-internal + * @method array getExportData(Template $template) Export Template data for external use. #pw-advanced + * @method array setImportData(Template $template, array $data) Given an array of Template export data, import it to the given Template. #pw-advanced * */ class Templates extends WireSaveableItems { @@ -107,7 +109,7 @@ class Templates extends WireSaveableItems { * Given a template ID or name, return the matching template or NULL if not found. * * @param string|int $key Template name or ID - * @return Template|null + * @return Template|null|string * */ public function get($key) { @@ -178,8 +180,10 @@ class Templates extends WireSaveableItems { $access = $this->wire(new PagesAccess()); $access->updateTemplate($item); } - - $this->wire('cache')->maintenance($item); + + /** @var WireCache $cache */ + $cache = $this->wire('cache'); + $cache->maintenance($item); return $result; } @@ -198,7 +202,9 @@ class Templates extends WireSaveableItems { if($cnt > 0) throw new WireException("Can't delete template '{$item->name}' because it is used by $cnt pages."); $return = parent::___delete($item); - $this->wire('cache')->maintenance($item); + /** @var WireCache $cache */ + $cache = $this->wire('cache'); + $cache->maintenance($item); return $return; } @@ -268,6 +274,9 @@ class Templates extends WireSaveableItems { /** * Overridden from WireSaveableItems to retain specific keys + * + * @param array $value + * @return string * */ protected function encodeData(array $value) { @@ -367,7 +376,6 @@ class Templates extends WireSaveableItems { * * @param Template $template Template you want to import to * @param array $data Import data array (must have been exported from getExportData() method). - * @return bool True if successful, false if not * @return array Returns array with list of changes (see example in method description) * */ @@ -548,6 +556,123 @@ class Templates extends WireSaveableItems { return $this->getParentPage($template, $checkAccess, true); } + /** + * FUTURE USE: Is the parent/child relationship allowed? + * + * By default this method returns an associative array containing the following: + * + * - `allowed` (bool): Is the relationship allowed? + * - `reasons` (array): Array of strings containing reasons why relationship is or is not allowed. + * + * If you specify the `false` for the `verbose` option then this method just returns a boolean. + * + * @param Template|Page $parent Parent Template or Page to test. + * @param Template|Page $child Child Template or Page to test. + * @param array $options Options to modify default behavior: + * - `verbose` (bool): Return verbose array. When false, returns boolean rather than array (default=true). + * - `strict` (bool): Disallow relationships that do not match rules, even if relationship already exists (default=false). + * Note that this option only applies if method is given Page objects rather than Template objects. + * @return array|bool Returns associative array by default, or bool if the verbose option is false. + * @throws WireException if given invalid argument + * + public function allowRelationship($parent, $child, array $options = array()) { + + $defaults = array( + 'verbose' => true, + 'strict' => false, + ); + + $options = array_merge($defaults, $options); + $parentPage = null; + $childPage = null; + + if($child instanceof Template) { + $childTemplate = $child; + } else if($child instanceof Page) { + $childPage = $child; + $childTemplate = $child->template; + } else { + throw new WireException('Invalid argument for child'); + } + + if($parent instanceof Template) { + $parentTemplate = $parent; + } else if($parent instanceof Page) { + $parentPage = $parent; + $parentTemplate = $parent->template; + } else { + throw new WireException('Invalid argument for parent'); + } + $reasonsNo = array(); + $reasonsYes = array(); + $isAlreadyParent = $parentPage && $childPage && $childPage->parent_id == $parentPage->id; + $isAlreadyParentNote = "parent/child allowed because relationship already exists"; + + if($isAlreadyParent) { + if($options['strict']) { + // in strict mode, existing relationships are ignored and we stick only to the rules + $isAlreadyParent = false; + } else { + $reasonsYes[] = "Given child page ($childPage) already has this parent ($parentPage)"; + } + } + + if($parentTemplate->noChildren) { + $reason = "Parent template “$parentTemplate” specifies “no children”"; + if($isAlreadyParent) { + $reasonsYes[] = "$reason - $isAlreadyParentNote"; + } else { + $reasonsNo[] = $reason; + } + } + + if($childTemplate->noMove) { + $reason = "Child template “$childTemplate” specifies “no move”"; + if($isAlreadyParent) { + $reasonsYes[] = "$reason - $isAlreadyParentNote"; + } else { + $reasonsNo[] = $reason; + } + } + + if($childTemplate->noParents > 0) { + $reason = "Child template “$childTemplate” specifies “no parents” option"; + if($isAlreadyParent) { + $reasonsYes[] = "$reason - $isAlreadyParentNote"; + } else { + $reasonsNo[] = $reason; + } + } + + if(count($parentTemplate->childTemplates)) { + if(in_array($childTemplate->id, $parentTemplate->childTemplates)) { + $reasonsYes[] = "Parent template “$parentTemplate” specifically allows children of “$childTemplate”"; + } else { + $reasonsNo[] = "Parent template “$parentTemplate” does not allow children using template “$childTemplate”"; + } + } + + if(count($childTemplate->parentTemplates)) { + if(in_array($parentTemplate->id, $childTemplate->parentTemplates)) { + $reasonsYes[] = "Child template “$childTemplate” specifically allows parents using template “$parentTemplate”"; + } else { + $reasonsNo[] = "Child template “$childTemplate” does not allow parents using template “$parentTemplate”"; + } + } + + $allowed = count($reasonsNo) ? false : true; + + if($options['verbose']) { + return array( + 'allowed' => $allowed, + 'reasons' => $allowed ? $reasonsYes : $reasonsNo, + ); + } + + return $allowed; + } + */ + } diff --git a/wire/core/WireHooks.php b/wire/core/WireHooks.php index 1368b08d..27c1079e 100644 --- a/wire/core/WireHooks.php +++ b/wire/core/WireHooks.php @@ -878,7 +878,11 @@ class WireHooks { public function getAllLocalHooks() { return $this->allLocalHooks; } - + + /** + * @return string + * + */ public function className() { return wireClassName($this, false); }