From b656b254e85d02a83ec5f1bc73f81a96c28df949 Mon Sep 17 00:00:00 2001
From: Ryan Cramer <ryan@processwire.com>
Date: Wed, 26 Jul 2023 14:04:47 -0400
Subject: [PATCH] phpdoc update and hook example in wire/core/Users.php

---
 wire/core/PageComparison.php | 11 +++++++++--
 wire/core/Users.php          | 31 ++++++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/wire/core/PageComparison.php b/wire/core/PageComparison.php
index 25d86148..d5f1a5d0 100644
--- a/wire/core/PageComparison.php
+++ b/wire/core/PageComparison.php
@@ -12,6 +12,14 @@
 
 class PageComparison {
 
+	/**
+	 * Selector properties that the matches() method ignores
+	 * 
+	 * @var string[] 
+	 * 
+	 */
+	protected $matchesIgnores = array('limit', 'start', 'sort', 'include');
+
 	/** 
 	 * Is this page of the given type? (status, template, etc.)
  	 *
@@ -231,7 +239,6 @@ class PageComparison {
 		}
 
 		$matches = false;
-		$ignores = array('limit', 'start', 'sort', 'include');
 
 		foreach($selectors as $selector) {
 			
@@ -240,7 +247,7 @@ class PageComparison {
 			
 			if(is_array($property)) $property = reset($property);
 			if(strpos($property, '.')) list($property, $subproperty) = explode('.', $property, 2);
-			if(in_array($property, $ignores)) continue;
+			if(in_array($property, $this->matchesIgnores)) continue;
 			
 			$matches = true; 
 			$value = $page->getUnformatted($property); 
diff --git a/wire/core/Users.php b/wire/core/Users.php
index 4fefadf6..e1307dc4 100644
--- a/wire/core/Users.php
+++ b/wire/core/Users.php
@@ -156,10 +156,12 @@ class Users extends PagesType {
 	 * 
 	 */
 	public function newUser() {
-		return $this->wire()->pages->newPage(array(
+		/** @var User $user */
+		$user = $this->wire()->pages->newPage(array(
 			'template' => 'user',
 			'pageClass' => $this->getPageClass()
 		));
+		return $user;
 	}
 
 	/**
@@ -214,6 +216,33 @@ class Users extends PagesType {
 		return $qty;
 	}
 	
+	/**
+	 * Save a User 
+	 *
+	 * - This is the same as calling $user->save()
+	 * - If the user is new, it will be inserted. If existing, it will be updated.
+	 * - If you want to just save a particular field for the user, use `$user->save($fieldName)` instead.
+	 *
+	 * **Hook note:**  
+	 * If you want to hook this method, please hook the `Users::saveReady`, `Users::saved`, or any one of 
+	 * the `Pages::save*` hook methods instead, as this method will not capture users saved directly 
+	 * through `$pages->save($user)`. 
+	 * ~~~~~
+	 * // Example of hooking $pages->save() on User objects only
+	 * $wire->addHookBefore('Pages::save(<User>)', function(HookEvent $e) {
+	 *   $user = $event->arguments(0);
+	 * });
+	 * ~~~~~
+	 *
+	 * @param Page $page
+	 * @return bool True on success
+	 * @throws WireException
+	 *
+	 */
+	public function ___save(Page $page) {
+		return parent::___save($page);
+	}
+
 	/**
 	 * Hook called just before a user is saved
 	 *