feat: migrate to PSR-4 namespace

AGENTS.md

@@ -11,7 +11,7 @@ Goal: modern baseline with minimal overhead and Packagist-readiness.
 Use these files first when relevant:
 - README.md for runtime behavior, documented API, and migration notes
 - composer.json for dependencies, scripts, and autoloading
-- class/ for implementation (SimplePhpCache.php)
+- src/ for implementation (SimplePhpCache.php)
 - tests/ for behavior checks (PHPUnit)
 - CHANGELOG.md for release notes
 - TODO.md for deferred or optional work
@@ -30,7 +30,7 @@ Use these files first when relevant:
 - Apply a security-first mindset when touching cache keys, file paths, serialization, and user-controlled input.
 
 ## Project Structure and Conventions
-- Source: `class/SimplePhpCache.php` (classmap autoloading, no namespace)
+- Source: `src/SimplePhpCache.php` (PSR-4 autoloading, namespace `Tschueller\SimplePhpCache`)
 - Tests: `tests/` (PHPUnit 11, PHP 8.2+)
 - CI: `.github/workflows/ci.yml` (PHP 8.2 / 8.3 / 8.4)
 - Static analysis: PHPStan level 3 (`phpstan.neon`)

CHANGELOG.md

@@ -7,6 +7,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Changed
+- **BREAKING**: The `SimplePhpCache` global class is now
+  `Tschueller\SimplePhpCache\SimplePhpCache`, loaded from `src/` through PSR-4.
+  Manual includes must be replaced with Composer's autoloader. See the migration
+  notes in README.md.
 - **BREAKING**: Variable cache storage switched from PHP serialization to JSON payloads with `SPCJSON1:` marker.
   Caching PHP objects is no longer supported.
 - Legacy serialized variable cache files are treated as invalid cache entries,

README.md

@@ -11,9 +11,16 @@ Requirements
 Preparation
 -----------
 
-Include the SimplePhpCache class
+Install the package with Composer:
 
-	include "SimplePhpCache.php";
+	composer require tschueller/simplephpcache
+
+Load Composer's autoloader and import the class:
+
+	<?php
+	require __DIR__ . '/vendor/autoload.php';
+
+	use Tschueller\SimplePhpCache\SimplePhpCache;
 
 Set the cacheBaseDir (Optional, default is the system temp directory)
 
@@ -69,6 +76,15 @@ To refresh a special cache file, set in the init method as the second parameter
 Migration
 ---------
 
+### From pre-1.0 (global class)
+
+**Namespace and autoloading changed (breaking):** `SimplePhpCache` is now the
+`Tschueller\SimplePhpCache\SimplePhpCache` class and is loaded via Composer
+PSR-4 autoloading. Replace manual includes such as `include "SimplePhpCache.php";`
+with Composer's `vendor/autoload.php`, then import the class:
+
+	use Tschueller\SimplePhpCache\SimplePhpCache;
+
 ### From pre-0.2 (PHP 5.x / 7.x)
 
 **PHP version:** Minimum requirement is now PHP 8.2.

TODO.md

@@ -2,18 +2,8 @@
 
 Deferred improvements — implement when explicitly requested or when capacity allows.
 
-## High Priority
-
-- **[HIGH] Add namespace `Tschueller\SimplePhpCache`**
-  Currently a global class. Adding a namespace is a breaking API change and requires
-  a major version bump. Should be paired with moving to `src/` and PSR-4 autoloading.
-
 ## Medium Priority
 
-- **[MEDIUM] Move source to `src/` and switch to PSR-4 autoloading**
-  Current `class/` layout with `classmap` is non-standard. Migration path: move file,
-  add namespace, update `composer.json`. Breaking change for manual `include` users.
-
 - **[MEDIUM] Add proper return types and parameter types to all public methods**
   Current code has no type declarations. Requires PHP 8.x syntax review.
   Non-breaking as long as callers pass correct types.

composer.json

@@ -16,15 +16,14 @@
     "require-dev": {
         "phpunit/phpunit": "^11.0",
         "phpstan/phpstan": "^2.0"
-    },
-    "autoload": {
-        "classmap": ["class/SimplePhpCache.php"]
-    },
-    "autoload-dev": {
-        "classmap": ["tests/"]
+    },
+    "autoload": {
+        "psr-4": {
+            "Tschueller\\SimplePhpCache\\": "src/"
+        }
     },
     "scripts": {
-        "lint": "php -l class/SimplePhpCache.php",
+        "lint": "php -l src/SimplePhpCache.php",
         "test": "phpunit --testdox",
         "analyse": "phpstan analyse --no-progress",
         "check": ["@lint", "@analyse", "@test"],
@@ -33,4 +32,4 @@
             "php -S 127.0.0.1:8000 -t . demo/index.php"
         ]
     }
-}
+}

demo/index.php

@@ -2,6 +2,8 @@
 
 require_once __DIR__ . '/../vendor/autoload.php';
 
+use Tschueller\SimplePhpCache\SimplePhpCache;
+
 // Set the cacheBaseDir (default is the system temp directory).
 SimplePhpCache::$cacheBaseDir = __DIR__;
 
@@ -65,4 +67,4 @@
     <p><?=$cachedData["time"]?></p>
 
   </body>
-</html>
+</html>

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
     level: 3
     paths:
-        - class
+        - src
     ignoreErrors: []

class/SimplePhpCache.php → src/SimplePhpCache.php

@@ -5,6 +5,10 @@
  * Licensed under the MIT license.
  */
 
+namespace Tschueller\SimplePhpCache;
+
+use RuntimeException;
+
 class SimplePhpCache
 {
     /** Prefix marker for JSON variable cache payloads. */

tests/SimplePhpCacheTest.php

@@ -2,9 +2,8 @@
 
 declare(strict_types=1);
 
-require_once __DIR__ . '/../class/SimplePhpCache.php';
-
 use PHPUnit\Framework\TestCase;
+use Tschueller\SimplePhpCache\SimplePhpCache;
 
 class SimplePhpCacheTest extends TestCase
 {