praiadeseselle/wire/core/MarkupQA.php

<?php namespace ProcessWire;

/**
 * HTML Markup Quality Assurance
 * 
 * Provides runtime quality assurance for markup stored in [textarea] field values. 
 * 
 * 1. Ensures URLs referenced in <a> and <img> tags are relative to actual site root.
 * 2. Ensures local page URLs referenced in <a> tags up-to-date with current $page URL.
 * 3. Identifies and logs <img> tags that point to non-existing files in PW's file system.
 * 4. Re-creates image variations that don't exist, when the original still exists. 
 * 5. Populates blank 'alt' attributes with actual file description. 
 * 
 * - For #1 use the wakeupUrls($value) and sleepUrls($value) methods. 
 * - For #2 use the wakeupHrefs($value) and sleepHrefs($value) methods.
 * - For #3-5 use the checkImgTags($value, $options) method, where $options specifies 3-5.
 * 
 * Runtime errors are logged to: /site/assets/logs/markup-qa-errors.txt
 * 
 * ProcessWire 3.x, Copyright 2021 by Ryan Cramer
 * https://processwire.com
 * 
 */ 

class MarkupQA extends Wire {
	
	const errorLogName = 'markup-qa-errors';

	/**
	 * @var string
	 * 
	 */
	protected $assetsURL = '';

	/**
	 * @var Page
	 * 
	 */
	protected $page;

	/**
	 * @var Field
	 * 
	 */
	protected $field;

	/**
	 * Markup QA custom settings
	 * 
	 * Can be specified in $config->markupQA = [ ... ]
	 * 
	 * - `ignorePaths` (array): Starting paths that should be ignored during link abstraction. Any paths that begin
	 *    with one of these will be left alone. Note these are paths rather than URLs, so if the site runs off a 
	 *    subdirectory, then you should exclude the subdirectory in these paths. 
	 * - `debug` (bool): Show debugging info to superusers? (default=false). May also be specified in $config->debugMarkupQA=true;
	 * - `verbose` (bool): Whether or not to track verbose info to $page: `$page->_markupQA = [ 'field_name' => [ counts ]]`
	 * 
	 * @var array
	 * 
	 */
	protected $settings = array(
		'ignorePaths' => array(),
		'debug' => false,
		'verbose' => false,
	);

	/**
	 * Construct
	 * 
	 * @param Page $page
	 * @param Field $field
	 *
	 */
	public function __construct(Page $page = null, Field $field = null) {
		if($page) {
			$this->setPage($page);
			$page->wire($this);
		}
		if($field) {
			$this->setField($field);
			if(!$page) $field->wire($this);
		}
		/** @var Config $config */
		$config = $this->wire('config');
		$this->assetsURL = $config->urls->assets;
		$settings = $config->markupQA;
		if(is_array($settings) && count($settings)) {
			if(!empty($settings['ignorePaths'])) $this->ignorePaths($settings['ignorePaths']);
			if(!empty($settings['debug'])) $this->debug(true);
			if(!empty($settings['verbose'])) $this->verbose(true);
		}
		if($config->debugMarkupQA) $this->debug(true);
	}

	/**
	 * Set the current Page
	 * 
	 * @param Page $page
	 * 
	 */
	public function setPage(Page $page) {
		$this->page = $page; 
	}

	/**
	 * Set the current Field
	 * 
	 * @param Field $field
	 * 
	 */
	public function setField(Field $field) {
		$this->field = $field; 
	}

	/**
	 * Get or set paths to ignore for link abstraction
	 * 
	 * To get ignored paths call function with no arguments. Otherwise you are setting them. 
	 * 
	 * @param array|string|null $paths Array of paths or string of one path, or CSV or newline separated string of multiple paths. 
	 * @param bool $replace True to replace all existing paths, or false to merge with existing paths (default=false)
	 * @return array Returns array of current ignore paths
	 * @throws WireException if given invalid $paths argument
	 * 
	 */
	public function ignorePaths($paths = null, $replace = false) {
		if($paths === null) {
			return $this->settings['ignorePaths'];
		} else if(is_string($paths)) {
			// string of one path or CSV/newline separated multiple paths
			$paths = trim($paths);
			if(strpos($paths, "\n")) {
				$paths = explode("\n", $paths);
			} else if(strpos($paths, ",")) {
				$paths = explode(",", $paths);
			} else {
				$paths = strlen($paths) ? array($paths) : array();
			}
			foreach($paths as $k => $v) $paths[$k] = trim($v); // remove any remaining whitespace
		}
		if(!is_array($paths)) throw new WireException('setIgnorePaths() requires array or string');
		if(!$replace) $paths = array_merge($this->settings['ignorePaths'], $paths);
		$this->settings['ignorePaths'] = $paths;
		return $paths;
	}

	/**
	 * Get or set debug status
	 * 
	 * Applies only if current user is a superuser
	 * 
	 * @param bool|null $set Omit this argument to get or specify bool to set
	 * @return bool
	 * 
	 */
	public function debug($set = null) {
		if(is_bool($set)) {
			if($set === true) {
				$user = $this->wire('user');
				if(!$user || !$user->isSuperuser()) $set = false;
			}
			$this->settings['debug'] = $set;
		}
		return $this->settings['debug'];
	}

	/**
	 * Get or set verbose state
	 * 
	 * Whether or not to set/track verbose information to page, i.e.
	 * `$page->_markupQA = array('field_name' => array(counts))`
	 * 
	 * When getting, if $page or $field have not been populated, verbose is always false. 
	 *
	 * @param bool|null $set Omit this argument to get or specify bool to set
	 * @return bool
	 *
	 */
	public function verbose($set = null) {
		if(is_bool($set)) $this->settings['verbose'] = $set;
		return $this->settings['verbose'] && $this->page && $this->field ? true : false;
	}

	/**
	 * Wakeup URLs in href or src attributes for presentation
	 *
	 * @param $value
	 *
	 */
	public function wakeupUrls(&$value) {
		$this->checkUrls($value, false);
	}

	/**
	 * Sleep URLs in href or src attributes for storage
	 *
	 * @param $value
	 *
	 */
	public function sleepUrls(&$value) {
		$this->checkUrls($value, true);
	}

	/**
	 * Wake URLs for wakeup or sleep, converting root URLs as necessary
	 * 
	 * @param string $value
	 * @param bool $sleep
	 * 
	 */
	protected function checkUrls(&$value, $sleep = false) {

		// see if quick exit possible
		if(stripos($value, 'href=') === false && stripos($value, 'src=') === false) return;

		$config = $this->wire('config');
		$httpHost = $config->httpHost;
		$rootURL = $config->urls->root;
		$rootHostURL = $httpHost . $rootURL;

		$replacements = array(
			// wakeup => sleep
			" href=\"$rootURL" => "\thref=\"/",
			" href='$rootURL" => "\thref='/",
			" src=\"$rootURL" => "\tsrc=\"/",
			" src='$rootURL" => "\tsrc='/",
		);
		
		if(strpos($value, "//$rootHostURL")) $replacements = array_merge($replacements, array(
			// wakeup => sleep
			" href='http://$rootHostURL" => "\thref='http://$httpHost/",
			" href='https://$rootHostURL" => "\thref='https://$httpHost/",
			" href=\"http://$rootHostURL" => "\thref=\"http://$httpHost/",
			" href=\"https://$rootHostURL" => "\thref=\"https://$httpHost/",
		));
		
		if($sleep) {
			// sleep 
			$value = str_ireplace(array_keys($replacements), array_values($replacements), $value);

			if($this->verbose()) {
				$info = $this->page->get('_markupQA');	
				if(!is_array($info)) $info = array();
				if(!is_array($info[$this->field->name])) $info[$this->field->name] = array();
				$info[$this->field->name]['href'] = substr_count($value, "\thref=");
				$info[$this->field->name]['src'] = substr_count($value, "\tsrc=");
				$this->page->setQuietly('_markupQA', $info);
			}

		} else if(strpos($value, "\t") === false) {
			// wakeup, but nothing necessary (quick exit)
			return;

		} else {
			// wakeup
			$value = str_ireplace(array_values($replacements), array_keys($replacements), $value);
		}
	}

	/**
	 * Convert a relative path to be absolute
	 * 
	 * @param string $path
	 * @return string Returns absolute path, or blank string on error
	 * 
	 */
	protected function relativeToAbsolutePath($path) {
		
		// path is relative, i.e. "something/" or "./something/ or "../something/" or similar
		$_path = $path;
		$page = $this->page;
		$slashUrls = $page->template->slashUrls;

		if(strpos($path, './') === 0) {
			// remove leading "./" reference, making "./something/" => "something/"
			$path = substr($path, 2);
		}

		if(strpos($path, '.') !== 0 && !$slashUrls) {
			// path like "something/"
			// if slashUrls are not in use, then the meaning of "./" is parent rather than page
			$page = $page->parent();
			$slashUrls = $page->template->slashUrls;
		}

		// resolve leading "../" to a $page
		while(strpos($path, '../') === 0) {
			$page = $slashUrls ? $page->parent() : $page->parent()->parent();
			$path = substr($path, 3);
			$slashUrls = $page->template->slashUrls;
			if(!$page->id) break;
		}

		if(!$page->id) {
			// path resolved outside of PW's tree
			$path = '';
		} else if(strlen($path)) {
			// resolve path from $page plus remaining path
			$path = rtrim($page->path, '/') . '/' . ltrim($path, '/');
		} else {
			// resolve path from $page
			$path = $page->path;
		}
		
		if($path && $path != $_path) {
			if($this->debug()) $this->message("MarkupQA absoluteToRelative converted: $_path => $path");
		}

		return $path;
	}

	/**
	 * Sleep href attributes, adding a data-pwid attribute to <a> tags that resolve to a Page
	 * 
	 * Should be used AFTER sleepUrls() has already been called, so that any URLs are already 
	 * relative to "/" rather than potential "/subdir/". 
	 * 
	 * @param string $value
	 * 
	 */
	public function sleepLinks(&$value) {
	
		// if there are no href attributes, there's nothing to sleep 
		// if there is already a data-pwid attribute present, then links are already asleep
		if(strpos($value, 'href=') === false || strpos($value, 'data-pwid=')) return;
	
		$info = $this->verbose() ? $this->page->get('_markupQA') : array();
		if(!is_array($info)) $info = array();
		if(isset($info[$this->field->name])) {
			$counts = $info[$this->field->name];	
		} else {
			$counts = array(
				'external' => 0,
				'internal' => 0,
				'relative' => 0,
				'files' => 0,
				'other' => 0,
				'unresolved' => 0,
				'nohttp' => 0, 
				'ignored' => 0, 
			);
		}
		
		$re = '!' . 
			'(<a[^\t<>]*?)' . // 1:"start" which includes the starting <a tag and everything before href attribute
			'([\t ]+href=(?:["\'](?:https?:)?//[^/"\'\s<>]+|["\']))' . // 2:"href" with optional hostname
			'([-_./a-z0-9]*)' . // 3:"path" in ProcessWire page name format
			'([^<>]*>)' . // 4:"end" which includes everything after the path (potential query string, other attrs, etc.)
			'!i'; 
		
		if(!preg_match_all($re, $value, $matches)) return;
		
		$replacements = array();
		$languages = $this->wire()->languages;
		$debug = $this->debug();
		$config = $this->wire()->config;
		$pages = $this->wire()->pages;
		
		if($languages && !$languages->hasPageNames()) $languages = null;
		
		foreach($matches[3] as $key => $path) {
			
			if(!strlen($path)) continue;
			
			$full = $matches[0][$key];
			$start = $matches[1][$key];
			$href = $matches[2][$key];
			$end = $matches[4][$key];
			$_path = $path; // original unmodified path
		
			if(strpos($href, '//')) {
				// scheme and hostname present
				/** @noinspection PhpUnusedLocalVariableInspection */
				list($x, $host) = explode('//', $href);
				if($host != $config->httpHost && !in_array($host, $config->httpHosts)) {
					$counts['external']++;
					if($debug) $this->message("MarkupQA sleepLinks skipping because hostname: $host");
					// external hostname, which we will skip over
					continue;
				}
			} else if(strpos($href, ':') !== false || strpos($end, ':') === 0) {
				// non http link like mailto: or tel: 
				$counts['nohttp']++;	
				continue;
			}
		
			if(strpos($path, '/') !== 0) {
				// convert relative path to absolute
				$path = $this->relativeToAbsolutePath($path);
				if(!strlen($path)) continue;
				if($path != $_path) $counts['relative']++;
				
			} else if(strrpos($path, '.') > strrpos($path, '/')) {
				// not relative and possibly a filename
				// if this link is to a file that exists, then it's not a page link so skip it
				$file = $this->wire('config')->paths->root . ltrim($path, '/');
				if(file_exists($file)) {
					$counts['files']++;
					continue;
				}
			}
	
			// check if this path is in the ignored paths list
			$ignored = false;
			foreach($this->ignorePaths() as $ignorePath) {
				if(strpos($path, $ignorePath) !== 0) continue;
				if($debug) $this->message("MarkupQA sleepLinks skipped $path because it matches ignored path $ignorePath"); 
				$counts['ignored']++;
				$ignored = true;
				break;
			}
			if($ignored) continue;
	
			// get the page for the path
			$getByPathOptions = array(
				'useLanguages' => $languages ? true : false,
				'allowUrlSegments' => true,
				'useHistory' => true
			);
			$page = $pages->getByPath($path, $getByPathOptions);
			if(!$page->id) {
				// if not found try again with non-urlSegment partial matching
				$getByPathOptions['allowUrlSegments'] = false;
				$page = $pages->getByPath($path, $getByPathOptions);
			}
			$pageID = $page->id;
			
			if($pageID) {
				// resolved to a page
				$urlSegments = $page->get('_urlSegments');
				$urlSegmentStr = is_array($urlSegments) ? implode('/', $urlSegments) : '';
				
				if($languages) {
					/** @var Language $language */
					$language = $languages->pageNames()->getPagePathLanguage($path, $page);
					$pwid = !$language || $language->isDefault() ? $pageID : "$pageID-$language";
				} else {
					$language = null;
					$pwid = $pageID;
				}
				if($urlSegmentStr) {
					// append url segment path to the pwid
					$pwid .= "/$urlSegmentStr";
				}
				$replacements[$full] = "$start\tdata-pwid=$pwid$href$path$end";
				$counts['internal']++;
				if($debug) {
					$langName = $language ? $language->name : 'n/a';
					$this->message(
						"MarkupQA sleepLinks (field=$this->field, page={$this->page->path}, lang=$langName): " . 
						"$full => " . $replacements[$full]
					);
				}
			} else {
				// did not resolve to a page, see if it resolves to a file or directory
				$file = $this->wire('config')->paths->root . ltrim($path, '/');
				if(file_exists($file)) {
					if($debug) $this->message("MarkupQA sleepLinks link resolved to a file: $path");
					$counts['files']++;
				} else {
					$parts = explode('/', trim($path, '/'));
					$firstPart = array_shift($parts);
					$test = $this->wire('config')->paths->root . $firstPart; 
					if(is_dir($test)) {
						// possibly to something in another application, i.e. processwire.com/talk/
						$counts['other']++;
					} else {
						$counts['unresolved']++;
						$this->linkWarning($_path, false);
					}
				}
			}
		}
		
		if(count($replacements)) {
			$value = str_replace(array_keys($replacements), array_values($replacements), $value);
		}
		
		$info[$this->field->name] = $counts;
		if($this->verbose()) $this->page->setQuietly('_markupQA', $info);
	}

	/**
	 * Wakeup href attributes, using the data-pwid attribute to update the href attribute as necessary
	 * 
	 * Should be used BEFORE wakeupUrls() is called so that href attributes are relative to "/" rather than
	 * a potential "/subdir/" that wouldn't be recognized as a page path.
	 * 
	 * @param $value
	 * @return array Returns array of replacements that were made (3.0.184+)
	 * 
	 */
	public function wakeupLinks(&$value) {

		// if there's no data-pwid attribute present, then there's nothing to do here
		if(strpos($value, 'data-pwid=') === false) return array();
		
		$re = '!' . 
			'(<a[^\t<>]*?)' . // 1:"start" which includes "<a" and everything up until data-pwid attribute
			'\tdata-pwid=([-\d]+(?:/[-_./a-z0-9]+)?)' . // 2:"pwid" integer of page id ($pageID) referenced by the link (123-11/urlSegmentStr)
			'([\t ]+href=(?:["\'](?:https?:)?//[^/"\'\s<>]+|["\']))' . // 3:"href" attribute and optional scheme+hostname
			'([-_./a-z0-9]+)' . // 4:"path" in PW page name format
			'([^<>]*>)' . // 5:"end" which includes everything else and closing ">", i.e. query string, other attrs, etc.
			'!i';
		
		if(!preg_match_all($re, $value, $matches)) return array();
		
		$replacements = array();
		$languages = $this->wire('languages');
		$rootURL = $this->wire('config')->urls->root;
		$adminURL = $this->wire('config')->urls->admin;
		$adminPath = $rootURL === '/' ? $adminURL : str_replace($rootURL, '/', $adminURL);
		$debug = $this->debug();
		
		foreach($matches[2] as $key => $pwid) {
			
			if(strpos($pwid, '/')) {
				list($pwid, $urlSegmentStr) = explode('/', $pwid, 2);
			} else {
				$urlSegmentStr = '';
			}
			
			if(strpos($pwid, '-')) {
				list($pageID, $languageID) = explode('-', $pwid);
			} else {
				$pageID = $pwid;
				$languageID = 0;
			}

			$pageID = (int) $pageID;
			$full = $matches[0][$key];
			$start = $matches[1][$key];
			$href = $matches[3][$key];
			$path = $matches[4][$key];
			$end = $matches[5][$key];
			
			if($languages) {
				$language = $languageID ? $languages->get((int) $languageID) : $languages->getDefault();
			} else {
				$language = null;
			}
			
			$livePath = $this->wire('pages')->getPath($pageID, array(
				'language' => $language
			));
			
			if($urlSegmentStr) {
				$livePath = rtrim($livePath, '/') . "/$urlSegmentStr";
				if(substr($path, '-1') === '/') $livePath .= '/';
			}
			
			if(strlen($rootURL) > 1) {
				$livePath = rtrim($rootURL, '/') . $livePath;
				$href = ' ' . ltrim($href); // immunity to wakeupUrls(), replacing tab with space
			}
			
			$langName = $debug && $language ? $language->name : '';
			
			if($livePath) {
				$ignore = false;
				foreach($this->ignorePaths() as $ignorePath) {
					if(strpos($livePath, $ignorePath) !== 0) continue;
					if($debug) $this->message("MarkupQA wakeupLinks path $livePath matches ignored path $ignorePath");
					$ignore = true;
					break;
				}
				if($path && substr($path, -1) != '/') {
					// no trailing slash, retain the editors wishes here
					$livePath = rtrim($livePath, '/');
				}
				if($ignore) {
					// path should be ignored and left as-is
				} else if(strpos($livePath, '/trash/') !== false) {
					// linked page is in trash, we won't update it but we'll produce a warning
					$this->linkWarning("$path => $livePath (" . $this->_('it is in the trash') . ')');
					continue;
				} else if(strpos($livePath, $adminPath) === 0) {
					// do not update paths that point in admin
					$this->linkWarning("$path => $livePath (" . $this->_('points to the admin') . ')');
					continue;
				} else if($livePath != $path) {
					// path differs from what's in the markup and should be updated
					if($debug) $this->warning(
						"MarkupQA wakeupLinks PATH UPDATED (field=$this->field, page={$this->page->path}, " . 
						"language=$langName): $path => $livePath"
					);
					$path = $livePath;
				} else if($debug) {
					$this->message("MarkupQA wakeupLinks no changes (field=$this->field, language=$langName): $path => $livePath");
				}
			} else {
				// did not resolve to a PW page
				$this->linkWarning("wakeup: $path");
			}
			
			$replacements[$full] = "$start$href$path$end";
		}

		if(count($replacements)) {
			$value = str_replace(array_keys($replacements), array_values($replacements), $value);
		}
		
		return $replacements;
	}

	/**
	 * Find pages linking to another
	 * 
	 * @param Page $page Page to find links to, or omit to use page specified in constructor
	 * @param array $fieldNames Field names to look in or omit to use field specified in constructor
	 * @param string $selector Optional selector to use as a filter
	 * @param array $options Additional options
	 *  - `getIDs` (bool): Return array of page IDs rather than Page instances. (default=false)
	 *  - `getCount` (bool): Return a total count (int) of found pages rather than Page instances. (default=false)
	 *  - `confirm` (bool): Confirm that the links are present by looking at the actual page field data. (default=true)
	 *     You can specify false for this option to make it perform faster, but with a potentially less accurate result.
	 * @return PageArray|array|int
	 * 
	 */
	public function findLinks(Page $page = null, $fieldNames = array(), $selector = '', array $options = array()) {
		
		$defaults = array(
			'getIDs' => false,
			'getCount' => false, 
			'confirm' => true 
		);

		$options = array_merge($defaults, $options);
		
		if($options['getIDs']) {
			$result = array();
		} else if($options['getCount']) {
			$result = 0;
		} else {
			$result = $this->wire('pages')->newPageArray();
		}
		
		if(!$page) $page = $this->page;
		if(!$page) return $result;
		
		if(empty($fieldNames)) {
			if($this->field) $fieldNames[] = $this->field->name;
			if(empty($fieldNames)) return $result;
		}
		
		if($selector === true) $selector = "include=all";
		$op = strlen("$page->id") > 3 ? "~=" : "%=";
		$selector = implode('|', $fieldNames) . "$op'$page->id', id!=$page->id, $selector";
		$selector = trim($selector, ', ');
		
		
		// find pages
		if($options['getCount'] && !$options['confirm']) {
			// just return a count
			return $this->wire('pages')->count($selector);
		} else {
			// find the IDs
			$checkIDs = array();
			$foundIDs = $this->wire('pages')->findIDs($selector);
			if(!count($foundIDs)) return $result;
			if($options['confirm']) {
				$checkIDs = array_flip($foundIDs);
				$foundIDs = array();
			}
		}
		
		// confirm results
		foreach($fieldNames as $fieldName) {
			if(!count($checkIDs)) break;
			$field = $this->wire('fields')->get($fieldName);
			if(!$field) continue;
			$table = $field->getTable();
			$ids = implode(',', array_keys($checkIDs));
			$sql = "SELECT * FROM `$table` WHERE `pages_id` IN($ids)";
			$query = $this->wire('database')->prepare($sql);
			$query->execute();

			while($row = $query->fetch(\PDO::FETCH_ASSOC)) {
				$pageID = (int) $row['pages_id'];
				if(isset($foundIDs[$pageID])) continue;
				$row = implode(' ', $row);
				$find = "data-pwid=$page->id";
				// first check if it might be there
				if(!strpos($row, $find)) continue;
				// then confirm with a more accurate check
				if(!strpos($row, "$find ") && !strpos($row, "$find\t") && !strpos($row, "$find-")) continue;
				// at this point we have confirmed that this item links to $page
				unset($checkIDs[$pageID]);
				$foundIDs[$pageID] = $pageID;
			}
			
			$query->closeCursor();
		}
	
		if(count($foundIDs)) {
			if($options['getIDs']) {
				$result = $foundIDs;
			} else if($options['getCount']) {
				$result = count($foundIDs); 
			} else {
				$result = $this->wire('pages')->getById($foundIDs);
			}
		}
	
		return $result;
	}

	/**
	 * Display and log a warning about a path that didn't resolve
	 * 
	 * @param string $path
	 * @param bool $logWarning
	 * 
	 */
	protected function linkWarning($path, $logWarning = true) {
		if($this->wire('page')->template == 'admin' && $this->wire('process') == 'ProcessPageEdit') {
			$this->warning(sprintf(
				$this->_('Unable to resolve link on page %1$s in field "%2$s": %3$s'), 
				$this->page->path, 
				$this->field->getLabel(), 
				$path
			));
		}
		if($this->verbose() || $logWarning) {
			$this->error("Unable to resolve link: $path");
		}
	}

	/**
	 * Quality assurance for <img> tags
	 *
	 * @param string $value
	 * @param array $options What actions should be performed:
	 *  - replaceBlankAlt (bool): Replace blank alt attributes with file description? (default=true)
	 *  - removeNoExists (bool): Remove references to images that don't exist (or re-create images when possible) (default=true)
	 *  - removeNoAccess (bool): Remove references to images user doesn't have view permission to (default=true)
	 *
	 */
	public function checkImgTags(&$value, array $options = array()) {
		if(strpos($value, '<img ') !== false && preg_match_all('{(<' . 'img [^>]+>)}', $value, $matches)) {
			foreach($matches[0] as $key => $img) {
				$this->checkImgTag($value, $img, $options);
			}
		}
	}

	/**
	 * Quality assurance for one <img> tag
	 *
	 * @param string $value Entire markup
	 * @param string $img Just the found <img> tag
	 * @param array $options What actions should be performed:
	 *  - replaceBlankAlt (bool): Replace blank alt attributes with file description? (default=true)
	 *  - removeNoExists (bool): Remove references to images that don't exist (or re-create images when possible) (default=true)
	 *  - removeNoAccess (bool): Remove references to images user doesn't have view permission to (default=true)
	 *
	 */
	protected function checkImgTag(&$value, $img, array $options = array()) {
		
		$defaults = array(
			'replaceBlankAlt' => true,
			'removeNoExists' => true,
			'removeNoAccess' => true, 
		);
		
		$options = array_merge($defaults, $options);
		$replaceAlt = ''; // exact text to replace for blank alt attribute, i.e. alt=""
		$src = '';
		$user = $this->wire()->user;
		$attrStrings = explode(' ', $img); // array of strings like "key=value"

		if($this->verbose()) {
			$markupQA = $this->page->get('_markupQA');
			if(!is_array($markupQA)) $markupQA = array();
			if(!isset($markupQA[$this->field->name])) $markupQA[$this->field->name] = array();
			$info =& $markupQA[$this->field->name];
		} else {
			$markupQA = null;
			$info = array();
		}

		if(!isset($info['img_unresolved'])) $info['img_unresolved'] = 0;
		if(!isset($info['img_fixed'])) $info['img_fixed'] = 0;
		if(!isset($info['img_noalt'])) $info['img_noalt'] = 0; // blank alt

		// determine current 'alt' and 'src' attributes
		foreach($attrStrings as $n => $attr) {

			if(!strpos($attr, '=')) continue;
			list($name, $val) = explode('=', $attr);

			$name = strtolower($name);
			$val = trim($val, "\"'> ");

			if($name == 'alt' && !strlen($val)) {
				$replaceAlt = $attr;

			} else if($name == 'src') {
				$src = $val;
			}
		}

		// if <img> had no src attr, or if it was pointing to something outside of PW assets, skip it
		if(!$src || strpos($src, $this->assetsURL) === false) return;

		// recognized site image, make sure the file exists
		/** @var Pageimage $pagefile */
		$pagefile = $this->page->filesManager()->getFile($src);

		// if this doesn't resolve to a known pagefile, stop now
		if(!$pagefile) {
			if($options['removeNoExists']) {
				if(file_exists($this->page->filesManager()->path() . basename($src))) {
					// file exists, but we just don't know what it is - leave it alone
				} else {
					$this->error("Image file no longer exists: $src");
					if($this->page->of()) $value = str_replace($img, '', $value);
					$info['img_unresolved']++;
				}
			}
			return;
		}

		if($options['removeNoAccess']) {
			if(($pagefile->page->id != $this->page->id && !$user->hasPermission('page-view', $pagefile->page))
				|| ($pagefile->field && !$pagefile->page->viewable($pagefile->field))) {
				// if the file resolves to another page that the user doesn't have access to view, 
				// OR user doesn't have permission to view the field that $pagefile is in,
				// then we will simply remove the image
				$this->error("Image referenced that user does not have view access to: $src");
				if($this->page->of()) $value = str_replace($img, '', $value);
				return;
			}
		}
		
		/*
		 * @todo potential replacement for 'removeNoAccess' block above
		 * Regarding: https://github.com/processwire/processwire-issues/issues/1548
		 * 
		// if(($pagefile->page->id != $this->page->id && !$user->hasPermission('page-view', $pagefile->page))
		if($options['removeNoAccess']) {
			// if the file resolves to another page that the user doesn't have access to view, 
			// OR user doesn't have permission to view the field that $pagefile is in, remove image
			$page = $pagefile->page;
			$field = $pagefile->field;
			$removeImage = false;
			if(wireInstanceOf($page, 'RepeaterPage')) {
				$page = $page->getForPageRoot();
				$field = $page->getForFieldRoot();
			}
			if($page->id != $this->page->id && !$page->viewable(false)) {
				$this->error("Image on page ($page->id) that user does not have view access to: $src");
				$removeImage = true;
			} else if($field && !$page->viewable($field)) {
				$this->error("Image on page:field ($page->id:$field) that user does not have view access to: $src");
				$removeImage = true;
			}
			if($removeImage) {
				if($this->page->of()) $value = str_replace($img, '', $value);
				return;
			}
		}
		*/

		if($options['replaceBlankAlt'] && $replaceAlt) {
			// image has a blank alt tag, meaning, we will auto-populate it with current file description, 
			// if output formatting is on
			if($this->page->of()) {
				$alt = $pagefile->description;
				if(strlen($alt)) {
					$alt = $this->wire('sanitizer')->entities1($alt);
					$_img = str_replace(" $replaceAlt", " alt=\"$alt\"", $img);
					$value = str_replace($img, $_img, $value);
				}
			}
			$info['img_noalt']++;
		}

		if($options['removeNoExists'] && $pagefile instanceof Pageimage) {
			$result = $this->checkImgExists($pagefile, $img, $src, $value);
			if($result < 0) $info['img_unresolved'] += abs($result);
			if($result > 0) $info['img_fixed'] += $result;
		}
		
		if($markupQA) $this->page->setQuietly('_markupQA', $markupQA);
	}

	/**
	 * Attempt to re-create images that don't exist, when possible
	 *
	 * @param Pageimage $pagefile
	 * @param $img
	 * @param $src
	 * @param $value
	 * @return int Returns 0 on no change, negative count on broken, positive count on fixed
	 *
	 */
	protected function checkImgExists(Pageimage $pagefile, $img, $src, &$value) {

		$basename = basename($src);
		$pathname = $pagefile->pagefiles->path() . $basename;

		if(file_exists($pathname)) return 0; // no action necessary

		// file referenced in <img> tag does not exist, and it is not a variation we can re-create
		if($pagefile->basename == $basename) {
			// original file no longer exists
			$this->error("Original image file no longer exists, unable to create new variation ($basename)");
			if($this->page->of()) $value = str_replace($img, '', $value); // remove reference to image, when output formatting is on
			return -1;
		}

		// check if this is a variation that we might be able to re-create
		$info = $pagefile->isVariation($basename);
		if(!$info) {
			// file is not a variation, so we apparently have no source to pull info from
			$this->error("Unrecognized image that does not exist ($basename)");
			if($this->page->of()) $value = str_replace($img, '', $value); // remove reference to image, when output formatting is on
			return -1;
		}

		$info['targetName'] = $basename; 
		$variations = array($info);
		while(!empty($info['parent'])) {
			$variations[] = $info['parent'];
			$info = $info['parent'];
		}
		
		$good = 0;
		$bad = 0;
		
		foreach(array_reverse($variations) as $info) {
			// definitely a variation, attempt to re-create it
			$options = array();
			if($info['crop']) $options['cropping'] = $info['crop'];
			if($info['suffix']) {
				$options['suffix'] = $info['suffix'];
				if(in_array('hidpi', $options['suffix'])) $options['hidpi'] = true;
			}
			/** @var Pageimage $newPagefile */
			$newPagefile = $pagefile->size($info['width'], $info['height'], $options);
			if($newPagefile && is_file($newPagefile->filename())) {
				if(!empty($info['targetName']) && $newPagefile->basename != $info['targetName']) {
					// new name differs from what is in text. Rename file to be consistent with text.
					rename($newPagefile->filename(), $pathname);
				}
				if($this->debug() || $this->wire('config')->debug) {
					$this->message($this->_('Re-created image variation') . " - $newPagefile->name");
				}
				$pagefile = $newPagefile; // for next iteration
				$good++;
			} else {
				$this->error($this->_('Unable to re-create image variation') . " - $newPagefile->name");
				$bad++;
			}
		}
		
		if($good) return $good;
		if($bad) return -1 * $bad;
		
		return 0;
	}

	/**
	 * Record error message to image-errors log
	 *
	 * @param string $text
	 * @param int $flags
	 * @return $this
	 * 
	 */
	public function error($text, $flags = 0) {
		$logText = "$text (field={$this->field->name}, id={$this->page->id}, path={$this->page->path})";
		$this->wire('log')->save(self::errorLogName, $logText);
		/*
		if($this->wire('modules')->isInstalled('SystemNotifications')) {
			$user = $this->wire('modules')->get('SystemNotifications')->getSystemUser();
			if($user && !$user->notifications->getBy('title', $text)) {
				$no = $user->notifications()->getNew('error');
				$no->title = $text; 
				$no->html = "<p>Field: {$this->field->name}\n<br />Page: <a href='{$this->page->url}'>{$this->page->title}</a></p>";
				$user->notifications->save(); 
			}
		}
		*/
		return $this;
	}

	/**
	 * Get or set a setting
	 * 
	 * @param string $key Setting name to get or set, or omit to get all settings
	 * @param string|array|int|null $value Setting value to set, or omit when getting setting
	 * @return string|array|int|null|$this Returns value of $key
	 * 
	public function setting($key = null, $value = null) {
		if($key === null) return $this->settings; // return all
		if($value === null) return isset($this->settings[$key]) ? $this->settings[$key] : null; // return one
		if($key === 'ignorePaths') return $this->ignorePaths($value); // set specific
		$this->settings[$key] = $value; // set
		return $value;
	}
	 */
	
	/**
	 * Enable or disable verbose mode
	 *
	 * Sets whether or not to set/track verbose information to page, i.e.
	 * `$page->_markupQA = array('field_name' => array(counts))`
	 *
	 * #pw-internal
	 *
	 * @param bool $verbose
	 * @deprecated use verbose() method instead
	 *
	 */
	public function setVerbose($verbose) {
		$this->settings['verbose'] = $verbose ? true : false;
	}

}