2026-tidy (#214)

* build: upgrade dependencies and test frameworks

* tidy: pass existing tests

* ci: upgrade test runners

* tidy: Gt->GT

* build: php8.1 compat

* tweak: kill scrutinizer

* tweak: use ulid

Author: g105b

README.md

@@ -8,10 +8,10 @@ This library handles [CSRF protection](https://www.owasp.org/index.php/Cross-Sit
 <a href="https://github.com/PhpGt/Csrf/actions" target="_blank">
     <img src="https://badge.status.php.gt/csrf-build.svg" alt="Build status" />
 </a>
-<a href="https://scrutinizer-ci.com/g/PhpGt/Csrf" target="_blank">
+<a href="https://app.codacy.com/gh/PhpGt/Csrf" target="_blank">
     <img src="https://badge.status.php.gt/csrf-quality.svg" alt="Code quality" />
 </a>
-<a href="https://scrutinizer-ci.com/g/PhpGt/Csrf" target="_blank">
+<a href="https://app.codecov.io/gh/PhpGt/Csrf" target="_blank">
     <img src="https://badge.status.php.gt/csrf-coverage.svg" alt="Code coverage" />
 </a>
 <a href="https://packagist.org/packages/PhpGt/Csrf" target="_blank">
@@ -85,7 +85,7 @@ echo $protector->getHTMLDocument();
 Using tokens of a different lengths
 -----------------------------------
 
-By default, 32 character tokens are generated. They use characters from the set [a-zA-Z0-9], meaning a 64-bit token which would take a brute-force attacker making 100,000 requests per second around 2.93 million years to guess. If this seems either excessive or inadequate you can change the token length using `TokenStore::setTokenLength()`.
+By default, tokens are generated as ULIDs with the prefix `CSRF_`. The configured token length refers to the ULID portion, which is 32 characters long by default in this package. The full token string length is therefore the configured token length plus the length of the prefix `CSRF_`.
 
 Special note about client-side requests
 ---------------------------------------

composer.json

@@ -6,8 +6,9 @@
 
 	"require": {
 		"php": ">=8.1",
-		"phpgt/dom": "^v4.0",
-		"phpgt/session": "^v1.1"
+		"phpgt/dom": "^4.0",
+		"phpgt/session": "^1.1",
+		"phpgt/ulid": "^1.2"
 	},
 	"require-dev": {
 		"phpstan/phpstan": "^1.10",

composer.lock

@@ -4,6 +4,7 @@
 use GT\Csrf\Exception\CsrfTokenInvalidException;
 use GT\Csrf\Exception\CsrfTokenMissingException;
 use GT\Csrf\Exception\CsrfTokenSpentException;
+use GT\Ulid\Ulid;
 
 /**
  * Extend this base class to create a store for CSRF tokens. The core functionality of generating
@@ -14,11 +15,9 @@ abstract class TokenStore {
 	protected int $tokenLength = 32;
 
 	/**
-	 * An optional limit of the number of valid tokens the TokenStore will retain may be passed.
-	 * If not specified, an unlimited number of tokens will be retained (which is probably
-	 * fine unless you have a very, very busy site with long-running sessions).
+	 * Optionally configure how many valid tokens the store will retain.
 	 *
-	 * @see static::DEFAULT_MAX_TOKENS
+	 * If not specified, the default limit is 1000 tokens.
 	 */
 	public function __construct(?int $maxTokens = null) {
 		if(!is_null($maxTokens)) {
@@ -31,22 +30,25 @@ public function getMaxTokens():int {
 	}
 
 	/**
-	 * Specify that tokens of a different length should be generated.
+	 * Specify the length of the ULID portion of generated tokens.
 	 *
-	 * @see static::DEFAULT_MAX_TOKENS
+	 * The full token string will also include the "CSRF_" prefix.
 	 */
 	public function setTokenLength(int $newTokenLength):void {
 		$this->tokenLength = $newTokenLength;
 	}
 
 	/**
 	 * Generate a new token. NOTE: This method does NOT store the token.
+	 *
+	 * The generated token is a prefixed ULID, so the full string length is
+	 * the configured token length plus the length of "CSRF_".
 	 */
 	public function generateNewToken():string {
-// This function uses PHP 7.2's inbuilt random_bytes function, which generates
-// raw bytes. When converted to hex, each byte is represented by two
-// characters, hence why we divide the token length by two.
-		return bin2hex(random_bytes($this->tokenLength / 2));
+		return new Ulid(
+			prefix: "CSRF",
+			length: $this->tokenLength,
+		);
 	}
 
 	/**

src/TokenStore.php

@@ -148,12 +148,17 @@ public function testGenerateNewToken_codesAreUnique():void {
 
 	public function testSaveToken_tokenLengthChange():void {
 		$sut = new ArrayTokenStore();
-		$sut->setTokenLength(6);
+		$tokenLength = 16;
+		$sut->setTokenLength($tokenLength);
 
 		$token = $sut->generateNewToken();
-		self::assertEquals(6, strlen($token));
+		self::assertStringStartsWith("CSRF_", $token);
+		self::assertEquals(
+			strlen("CSRF_") + $tokenLength,
+			strlen($token)
+		);
 
-// now make sure the shorter token is successfully stored
+	// now make sure the custom-length token is successfully stored
 		$sut->saveToken($token);
 
 		$exception = null;
@@ -165,4 +170,14 @@ public function testSaveToken_tokenLengthChange():void {
 
 		self::assertNull($exception);
 	}
+
+	public function testGenerateNewToken_usesCsrfUlidPrefix():void {
+		$sut = new ArrayTokenStore();
+		$token = $sut->generateNewToken();
+		self::assertStringStartsWith("CSRF_", $token);
+		self::assertSame(
+			strlen("CSRF_") + 32,
+			strlen($token)
+		);
+	}
 }