Tweak a session variable name and update comments

www/artworks/get.php

@@ -3,7 +3,7 @@ use function Safe\session_unset;
 
 session_start();
 
-$isSaved = HttpInput::Bool(SESSION, 'is-saved') ?? false;
+$isSaved = HttpInput::Bool(SESSION, 'is-artwork-saved') ?? false;
 /** @var ?\Exception $exception */
 $exception = $_SESSION['exception'] ?? null;
 
@@ -49,7 +49,7 @@ try{
 	if($exception){
 		http_response_code(Enums\HttpCode::UnprocessableContent->value);
 
-		// Before we overwrite the original artwork with our new one, restore the old status, because if the new status is 'approved' then it will hide the status form entirely, which will be confusing.
+		// Before we overwrite the original artwork with our new one, restore the old status, because if the new status is `approved` then it will hide the status form entirely, which will be confusing.
 		$oldStatus = $artwork->Status;
 		/** @var Artwork $artwork */
 		$artwork = $_SESSION['artwork'] ?? $artwork;

www/artworks/new.php

@@ -3,7 +3,7 @@ use function Safe\session_unset;
 
 session_start();
 
-$isCreated = HttpInput::Bool(SESSION, 'is-created') ?? false;
+$isCreated = HttpInput::Bool(SESSION, 'is-artwork-created') ?? false;
 /** @var ?\Exception $exception */
 $exception = $_SESSION['exception'] ?? null;
 /** @var ?Artwork $artwork */

www/artworks/post.php

@@ -38,7 +38,7 @@ try{
 		$artwork->Create(HttpInput::File('artwork-image'));
 
 		$_SESSION['artwork'] = $artwork;
-		$_SESSION['is-created'] = true;
+		$_SESSION['is-artwork-created'] = true;
 
 		http_response_code(Enums\HttpCode::SeeOther->value);
 		header('Location: /artworks/new');
@@ -78,7 +78,7 @@ try{
 		$artwork->Save(HttpInput::File('artwork-image'));
 
 		$_SESSION['artwork'] = $artwork;
-		$_SESSION['is-saved'] = true;
+		$_SESSION['is-artwork-saved'] = true;
 
 		http_response_code(Enums\HttpCode::SeeOther->value);
 		header('Location: ' . $artwork->Url);
@@ -119,7 +119,7 @@ try{
 		$artwork->Save();
 
 		$_SESSION['artwork'] = $artwork;
-		$_SESSION['is-saved'] = true;
+		$_SESSION['is-artwork-saved'] = true;
 
 		http_response_code(Enums\HttpCode::SeeOther->value);
 		header('Location: ' . $artwork->Url);

www/ebooks/public-domain-day-placeholder.php

@@ -7,6 +7,7 @@ $ebook = null;
 try{
 	try{
 		// Attempt to read a draft ebook repo from the filesystem.
+		// **Important:** The `deploy` script *does not tranfer `.git` folders,* which `Ebook::FromFilesystem()` needs to have. Therefore, use `rsync` to sync Public Domain Day ebooks including their `.git` folders.
 		$ebook = Ebook::FromFilesystem(PD_DAY_DRAFT_PATH . '/' . str_replace('/', '_', preg_replace('|^' . EBOOKS_IDENTIFIER_PREFIX . '|', '', $identifier)));
 	}
 	catch(Exceptions\EbookNotFoundException $ex){

www/polls/votes/index.php

@@ -30,7 +30,7 @@ catch(Exceptions\AppException){
 							<div aria-hidden="true">
 								<p><?= number_format($pollItem->VoteCount) ?></p>
 							</div>
-							<? /* @max must be at least 1, otherwise 0/0 will appear as 100% */ ?>
+							<? /* `@max` must be at least 1, otherwise 0/0 will appear as 100%. */ ?>
 							<meter min="0" max="<?= $poll->VoteCount ?: 1 ?>" value="<?= $pollItem->VoteCount ?>"></meter>
 						</div>
 					</td>

www/polls/votes/new.php

@@ -28,11 +28,11 @@ try{
 	try{
 		$vote = PollVote::Get($poll->UrlName, Session::$User->UserId);
 
-		// Vote was found, don't allow another vote
+		// Vote was found, don't allow another vote.
 		throw new Exceptions\PollVoteExistsException($vote);
 	}
 	catch(Exceptions\PollVoteNotFoundException){
-		// Vote was not found, user is OK to vote
+		// Vote was not found, user is OK to vote.
 	}
 
 	if($exception){

www/polls/votes/post.php

@@ -22,7 +22,7 @@ try{
 		header('Location: ' . $vote->Url);
 	}
 	else{
-		// Access via Enums\HttpRequestType::Rest api; 201 CREATED with location
+		// Access via REST API; output `201 Created` with location.
 		http_response_code(Enums\HttpCode::Created->value);
 		header('Location: ' . $vote->Url);
 	}
@@ -32,12 +32,12 @@ catch(Exceptions\InvalidPollVoteException $ex){
 		$_SESSION['vote'] = $vote;
 		$_SESSION['exception'] = $ex;
 
-		// Access via form; 303 redirect to the form, which will emit a 422 Unprocessable Entity
+		// Access via form; output 303 redirect to the form, which will emit a `422 Unprocessable Entity`.
 		http_response_code(Enums\HttpCode::SeeOther->value);
 		header('Location: /polls/' . (HttpInput::Str(GET, 'pollurlname') ?? '') . '/votes/new');
 	}
 	else{
-		// Access via Enums\HttpRequestType::Rest api; 422 Unprocessable Entity
+		// Access via REST api; `422 Unprocessable Entity`.
 		http_response_code(Enums\HttpCode::UnprocessableContent->value);
 	}
 }

www/sessions/new.php

@@ -22,7 +22,7 @@ if($exception){
 		// Prompt the user for a password.
 		http_response_code(Enums\HttpCode::Unauthorized->value);
 		$passwordRequired = true;
-		$exception = null; // Clear the exception so we don't show an error
+		$exception = null; // Clear the exception so we don't show an error.
 	}
 	else{
 		http_response_code(Enums\HttpCode::UnprocessableContent->value);

www/sessions/post.php

@@ -26,7 +26,7 @@ try{
 		header('Location: ' . $redirect);
 	}
 	else{
-		// Access via Enums\HttpRequestType::Rest api; 201 CREATED with location
+		// Access via REST API; output `201 Created` with location.
 		http_response_code(Enums\HttpCode::Created->value);
 		header('Location: ' . $session->Url);
 	}

www/webhooks/github.php

@@ -6,8 +6,7 @@ use function Safe\glob;
 use function Safe\shell_exec;
 
 // This script makes various calls to external scripts using exec() (and when called via Apache, as the www-data user).
-// These scripts are allowed using the /etc/sudoers.d/www-data file. Only the specific scripts
+// These scripts are allowed using the /etc/sudoers.d/www-data file. Only the specific scripts in that file may be executed by this script.
-// in that file may be executed by this script.
 try{
 	$log = new Log(GITHUB_WEBHOOK_LOG_FILE_PATH);
 	$lastPushHashFlag = '';
@@ -87,13 +86,13 @@ try{
 			}
 			else{
 				if($data['after'] == $lastCommitSha1){
-					// This commit is already in our local repo, so silent success
+					// This commit is already in our local repo, so silent success.
 					$log->Write('Local repo already in sync, no action taken.');
 					throw new Exceptions\NoopException();
 				}
 			}
 
-			// Get the current HEAD hash and save for later
+			// Get the current HEAD hash and save for later.
 			$output = [];
 			exec('sudo --set-home --user se-vcs-bot git -C ' . escapeshellarg($dir) . ' rev-parse HEAD', $output, $returnCode);
 			if($returnCode != 0){
@@ -130,11 +129,9 @@ try{
 			throw new Exceptions\WebhookException('Unrecognized GitHub webhook event.', $post);
 	}
 
-	// "Success, no content"
 	http_response_code(Enums\HttpCode::NoContent->value);
 }
 catch(Exceptions\InvalidCredentialsException){
-	// "Forbidden"
 	http_response_code(Enums\HttpCode::Forbidden->value);
 }
 catch(Exceptions\WebhookException $ex){
@@ -146,14 +143,12 @@ catch(Exceptions\WebhookException $ex){
 	// Print less details to the client.
 	print($ex->getMessage());
 
-	// "Client error"
 	http_response_code(Enums\HttpCode::BadRequest->value);
 }
 catch(Exceptions\NoopException){
 	// We arrive here because a special case required us to take no action for the request, but execution also had to be interrupted.
 	// For example, we received a request for a known repo for which we must ignore requests.
 
-	// "Success, no content"
 	http_response_code(Enums\HttpCode::NoContent->value);
 }
 ?>

www/webhooks/postmark.php

@@ -16,7 +16,7 @@ try{
 
 	$apiKey = get_cfg_var('se.secrets.postmark.api_key');
 
-	// Ensure this webhook actually came from Postmark
+	// Ensure this webhook actually came from Postmark.
 	if($apiKey != ($_SERVER['HTTP_X_SE_KEY'] ?? '')){
 		throw new Exceptions\InvalidCredentialsException();
 	}
@@ -31,7 +31,7 @@ try{
 	}
 
 	if($data->RecordType == 'SpamComplaint'){
-		// Received when a user marks an email as spam
+		// Received when a user marks an email as spam.
 		$log->Write('Event type: spam complaint.');
 
 		Db::Query('
@@ -42,12 +42,12 @@ try{
 			', [$data->Email]);
 	}
 	elseif($data->RecordType == 'SubscriptionChange' && $data->SuppressSending){
-		// Received when a user clicks Postmark's "Unsubscribe" link in a newsletter email
+		// Received when a user clicks Postmark's "Unsubscribe" link in a newsletter email.
 		$log->Write('Event type: unsubscribe.');
 
 		$email = $data->Recipient;
 
-		// Remove the email from our newsletter list
+		// Remove the email from our newsletter list.
 		Db::Query('
 				DELETE ns.*
 				from NewsletterSubscriptions ns
@@ -55,7 +55,7 @@ try{
 				where u.Email = ?
 		', [$email]);
 
-		// Remove the suppression from Postmark, since we deleted it from our own list we will never email them again anyway
+		// Remove the suppression from Postmark, since we deleted it from our own list we will never email them again anyway.
 		$handle = curl_init();
 		curl_setopt($handle, CURLOPT_URL, 'https://api.postmarkapp.com/message-streams/' . $data->MessageStream . '/suppressions/delete');
 		curl_setopt($handle, CURLOPT_RETURNTRANSFER, 1);
@@ -73,11 +73,9 @@ try{
 
 	$log->Write('Event processed.');
 
-	// "Success, no content"
 	http_response_code(Enums\HttpCode::NoContent->value);
 }
 catch(Exceptions\InvalidCredentialsException){
-	// "Forbidden"
 	$log->Write('Invalid key: ' . ($_SERVER['HTTP_X_SE_KEY'] ?? ''));
 	http_response_code(Enums\HttpCode::Forbidden->value);
 }
@@ -90,6 +88,5 @@ catch(Exceptions\WebhookException $ex){
 	// Print less details to the client.
 	print($ex->getMessage());
 
-	// "Client error"
 	http_response_code(Enums\HttpCode::BadRequest->value);
 }

www/webhooks/zoho.php

@@ -3,9 +3,7 @@ use function Safe\file_get_contents;
 use function Safe\preg_match;
 use function Safe\json_decode;
 
-// This webhook receives POSTs when email from a Fractured Atlas donation is received
+// This webhook receives POSTs when email from a Fractured Atlas donation is received at the SE Zoho email account. This script processes the email, and inserts the donation ID into the database for later processing by `~se/web/scripts/process-pending-payments`.
-// at the SE Zoho email account. This script processes the email, and inserts the donation ID
-// into the database for later processing by ~se/web/scripts/process-pending-payments
 try{
 	$log = new Log(ZOHO_WEBHOOK_LOG_FILE_PATH);
 
@@ -29,7 +27,7 @@ try{
 	if($data->fromAddress == 'support@fracturedatlas.org' && strpos($data->subject, 'NOTICE:') !== false){
 		$log->Write('Processing new donation.');
 
-		// Get the donation ID
+		// Get the donation ID.
 		preg_match('/Donation ID: ([0-9a-f\-]+)/us', $data->html, $matches);
 		if(sizeof($matches) == 2){
 			$transactionId = $matches[1];
@@ -50,11 +48,9 @@ try{
 
 	$log->Write('Event processed.');
 
-	// "Success, no content"
 	http_response_code(Enums\HttpCode::NoContent->value);
 }
 catch(Exceptions\InvalidCredentialsException){
-	// "Forbidden"
 	$log->Write('Couldn\'t validate POST data.');
 	http_response_code(Enums\HttpCode::Forbidden->value);
 }
@@ -67,6 +63,5 @@ catch(Exceptions\WebhookException $ex){
 	// Print less details to the client.
 	print($ex->getMessage());
 
-	// "Client error"
 	http_response_code(Enums\HttpCode::BadRequest->value);
 }