byjg · byjg · Aug 22, 2026 · Aug 22, 2026 · Sep 14, 2026
diff --git a/.github/workflows/phpunit.yml b/.github/workflows/phpunit.yml
@@ -18,6 +18,7 @@ jobs:
     strategy:
       matrix:
         php-version:
+          - "8.6"
           - "8.5"
           - "8.4"
           - "8.3"
@@ -34,7 +35,7 @@ jobs:
       # for github/codeql-action/upload-sarif to upload SARIF results
       security-events: write
     container:
-      image: byjg/php:8.4-cli
+      image: byjg/php:8.5-cli
       options: --user root --privileged
 
     steps:
@@ -44,10 +45,13 @@ jobs:
       - name: Composer
         run: composer install
 
+      - name: Composer (psalm)
+        run: composer --working-dir=tools/psalm update --no-interaction
+
       - name: Psalm
         # Note: Ignoring error code 2, which just signals that some
         # flaws were found, not that Psalm itself failed to run.
-        run: ./vendor/bin/psalm
+        run: ./tools/psalm/vendor/bin/psalm
           --show-info=true
           --report=psalm-results.sarif || [ $? = 2 ]
 

diff --git a/.travis.yml b/.travis.yml
diff --git a/CHANGELOG-6.0.md b/CHANGELOG-6.0.md
@@ -0,0 +1,134 @@
+# Changelog - Version 6.0
+
+## Overview
+
+Version 6.0 brings significant improvements to the Singleton Pattern library, including updated PHP version requirements, comprehensive documentation, improved tooling support, and enhanced GitHub Actions workflows.
+
+## New Features
+
+### Comprehensive Documentation Structure
+- Added detailed markdown-based documentation in the `docs/` folder
+- **Getting Started Guide** (`docs/getting-started.md`) - Installation and requirements
+- **Creating a Singleton Class** (`docs/creating-singleton.md`) - Step-by-step implementation guide
+- **Using Your Singleton** (`docs/using-singleton.md`) - Working with singleton instances
+- **How It Works** (`docs/how-it-works.md`) - Implementation details and internals
+- **API Reference** (`docs/api-reference.md`) - Complete API documentation
+- Updated `README.md` with links to the new documentation structure
+
+### Enhanced Development Environment
+- Added Gitpod configuration (`.gitpod.yml`) for cloud-based development
+- Added VSCode launch configuration (`.vscode/launch.json`) for debugging support
+- Added Composer scripts for easier testing and analysis:
+  - `composer test` - Run PHPUnit tests
+  - `composer psalm` - Run Psalm static analysis
+
+### Improved CI/CD Workflows
+- Enhanced GitHub Actions workflow with better container options
+- Added separate Psalm static analysis job with SARIF upload for security insights
+- Updated to use latest `actions/checkout` action
+- Added PHP 8.4 and PHP 8.5 to test matrix
+
+### Stability Configuration
+- Added `minimum-stability: dev` with `prefer-stable: true` in `composer.json` for better dependency resolution
+
+## Breaking Changes
+
+| Aspect | Before (5.x) | After (6.x) | Description |
+|--------|-------------|------------|-------------|
+| **Minimum PHP Version** | PHP 8.1 | PHP 8.3 | Dropped support for PHP 8.1 and 8.2 |
+| **Maximum PHP Version** | PHP <8.4 | PHP <8.6 | Added support for PHP 8.4 and 8.5 |
+| **PHPUnit Version** | ^9.6 | ^10.5\|^11.5 | Updated to support PHPUnit 10 and 11 |
+| **Psalm Version** | ^5.9 | ^5.9\|^6.13 | Added support for Psalm 6 |
+
+## Path to Upgrade from 5.x to 6.x
+
+### Prerequisites Check
+
+1. **Verify PHP Version**
+   ```bash
+   php -v
+   ```
+   Ensure you are running PHP 8.3, 8.4, or 8.5. If you're on PHP 8.1 or 8.2, you must upgrade your PHP version before updating to version 6.0.
+
+### Upgrade Steps
+
+2. **Update Composer Dependency**
+   ```bash
+   composer require "byjg/singleton-pattern:^6.0"
+   ```
+
+3. **Update Development Dependencies** (if applicable)
+
+   If your project uses PHPUnit or Psalm and references the same versions, you may need to update them:
+   ```bash
+   composer update --with-dependencies
+   ```
+
+4. **Run Tests**
+
+   Verify your implementation works correctly:
+   ```bash
+   composer test
+   # or
+   vendor/bin/phpunit
+   ```
+
+5. **Review Documentation**
+
+   Check the new comprehensive documentation for best practices and implementation details:
+   - [Getting Started](docs/getting-started.md)
+   - [Creating a Singleton Class](docs/creating-singleton.md)
+   - [Using Your Singleton](docs/using-singleton.md)
+
+### Code Changes Required
+
+**No code changes are required** in your implementation. The Singleton trait API remains fully backward compatible. The only changes are:
+
+- PHP version requirement (upgrade your environment if needed)
+- Development dependencies versions (only affects contributors/developers)
+
+### Compatibility Notes
+
+- All singleton implementations using the trait will continue to work without modification
+- The `getInstance()` method signature remains unchanged
+- Clone, serialize, and unserialize protections remain the same
+- Constructor requirements (private/protected) remain unchanged
+
+### Troubleshooting
+
+If you encounter issues after upgrading:
+
+1. **Clear Composer cache:**
+   ```bash
+   composer clear-cache
+   composer install
+   ```
+
+2. **Verify PHP version compatibility:**
+   ```bash
+   composer check-platform-reqs
+   ```
+
+3. **Review the comprehensive documentation** in the `docs/` folder for implementation guidance
+
+## Additional Changes
+
+- Updated `psalm.xml` configuration to adjust error level and exclude test directory
+- Added sponsor badge to README
+- Improved PHPUnit configuration (`phpunit.xml.dist`)
+- Updated GitHub workflow to use Composer scripts for Psalm analysis
+- Added sample test file (`tests/Sample2.php`) for expanded test coverage
+- Removed deprecated `_config.yml` file
+
+## Migration Timeline
+
+- **Version 5.x** remains available for projects using PHP 8.1-8.2
+- **Version 6.x** is recommended for all projects using PHP 8.3+
+- No end-of-life date has been announced for 5.x at this time
+
+## Support
+
+For issues, questions, or contributions:
+- GitHub Issues: https://github.com/byjg/php-singleton-pattern/issues
+- Documentation: [docs/getting-started.md](docs/getting-started.md)
+- Sponsor: https://github.com/sponsors/byjg
diff --git a/CHANGELOG-7.0.md b/CHANGELOG-7.0.md
@@ -0,0 +1,36 @@
+# Changelog - Version 7.0
+
+> **Status: in development.** This document tracks changes landing on the `7.0` branch.
+> Nothing here is released yet, and the contents may still change.
+
+## Breaking Changes
+
+- None.
+
+## Requirements
+
+- PHP 8.3, 8.4, 8.5 and 8.6 are now supported: `"php": ">=8.3 <8.7"`.
+  The previous `<8.6` upper bound excluded PHP 8.6, since `<8.6` is exclusive.
+
+## Toolchain
+
+- PHPUnit updated to `^12.5`.
+- Psalm updated to `^6.16`.
+
+  PHPUnit 13 is deliberately **not** used. It requires PHP `>=8.4.1`, which would
+  break the 8.3 floor, and it pulls `sebastian/diff ^9.0`, which the newest stable
+  Psalm (6.16.1) does not accept — that combination silently resolves Psalm to an
+  unreleased `6.x-dev` branch. Pinning PHPUnit to `^12.5` keeps a single stable
+  PHPUnit and a single stable Psalm across the whole matrix.
+
+## Continuous Integration
+
+- The build matrix now includes PHP 8.6.
+- The Psalm job now runs on PHP 8.5. Psalm 6.16.1 declares
+  `~8.1.31 || ~8.2.27 || ~8.3.16 || ~8.4.3 || ~8.5.0` and therefore cannot be
+  installed on PHP 8.6.
+
+## Housekeeping
+
+- `phpunit.xml.dist` renamed to `phpunit.xml`.
+- Removed the obsolete `.travis.yml`.
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Just one class and no dependencies.
 [![Build Status](https://github.com/byjg/php-singleton-pattern/actions/workflows/phpunit.yml/badge.svg?branch=master)](https://github.com/byjg/php-singleton-pattern/actions/workflows/phpunit.yml)
 [![Opensource ByJG](https://img.shields.io/badge/opensource-byjg-success.svg)](http://opensource.byjg.com)
 [![GitHub source](https://img.shields.io/badge/Github-source-informational?logo=github)](https://github.com/byjg/php-singleton-pattern/)
-[![GitHub license](https://img.shields.io/github/license/byjg/php-singleton-pattern.svg)](https://opensource.byjg.com/opensource/licensing.html)
+[![GitHub license](https://img.shields.io/github/license/byjg/php-singleton-pattern.svg)](https://opensource.byjg.com/license/)
 [![GitHub release](https://img.shields.io/github/release/byjg/php-singleton-pattern.svg)](https://github.com/byjg/php-singleton-pattern/releases/)
 
 ## Documentation
@@ -107,12 +107,5 @@ vendor/bin/phpunit
 * [Wikipedia: Singleton Pattern](https://en.wikipedia.org/wiki/Singleton_pattern)
 * [Documentation](docs/getting-started.md)
 
-## Dependencies
-
-```mermaid
-flowchart TD
-    byjg/singleton-pattern
-```
-
 ----
 [Open source ByJG](http://opensource.byjg.com)
diff --git a/composer.json b/composer.json
@@ -12,15 +12,17 @@
       }
   },
   "require": {
-    "php": ">=8.3 <8.6"
+    "php": ">=8.3 <8.7"
   },
   "require-dev": {
-    "phpunit/phpunit": "^10.5|^11.5",
-    "vimeo/psalm": "^5.9|^6.13"
+    "phpunit/phpunit": "^12.5"
   },
   "scripts": {
     "test": "vendor/bin/phpunit",
-    "psalm": "vendor/bin/psalm --threads=1"
+    "psalm": [
+      "@composer --working-dir=tools/psalm update --no-interaction",
+      "tools/psalm/vendor/bin/psalm --threads=1"
+    ]
   },
   "minimum-stability": "dev",
   "prefer-stable": true,

diff --git a/phpunit.xml.dist → phpunit.xml b/phpunit.xml.dist → phpunit.xml
diff --git a/psalm.xml b/psalm.xml
@@ -7,7 +7,7 @@
     cacheDirectory="/tmp/psalm"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns="https://getpsalm.org/schema/config"
-    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+    xsi:schemaLocation="https://getpsalm.org/schema/config tools/psalm/vendor/vimeo/psalm/config.xsd"
 >
     <projectFiles>
         <directory name="src" />

diff --git a/tools/psalm/composer.json b/tools/psalm/composer.json
@@ -0,0 +1,5 @@
+{
+    "require": {
+        "vimeo/psalm": "^6.16"
+    }
+}