v2 with some tech improvements

.github/workflows/phpunit.yml

@@ -1,47 +1,90 @@
-name       : PHPUnit Test
+name: CI
 
-on         :
-  push        :
-    branches: [ "main" ]
+on:
+  push:
+    branches: ["main"]
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
 
 permissions:
   contents: read
 
-jobs       :
-  test:
+jobs:
+  lint:
+    name: Code Style
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
 
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+
+      - name: Run Laravel Pint
+        run: composer lint:test
+
+  analyse:
+    name: Static Analysis
     runs-on: ubuntu-latest
 
-    steps  :
-      -
-        name: Set up PHP
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: '8.4'
+          php-version: "8.4"
 
-      -
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+
+      - name: Run PHPStan
+        run: composer analyse
+
+  test:
+    name: PHPUnit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.4"
+          coverage: pcov
+
+      - name: Checkout code
         uses: actions/checkout@v4
 
-      -
-        name: Validate composer.json and composer.lock
-        run : composer validate --strict
+      - name: Validate composer.json and composer.lock
+        run: composer validate --strict
 
-      -
-        name: Cache Composer packages
-        id  : composer-cache
+      - name: Cache Composer packages
+        id: composer-cache
         uses: actions/cache@v4
         with:
-          path        : vendor
-          key         : ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+          path: vendor
+          key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
           restore-keys: |
             ${{ runner.os }}-php-
 
-      -
-        name: Install dependencies
-        run : composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+      - name: Install dependencies
+        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
 
-      -
-        name: Run test suite
-        run : composer run-script test
+      - name: Run test suite with coverage
+        run: vendor/bin/phpunit tests/ProgressableTest.php --testdox --coverage-text --coverage-clover=coverage.xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+          verbose: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -4,6 +4,7 @@ vendor/
 .vscode/
 node_modules/
 .phpunit.result.cache
+.phpunit.cache/
 *.log
 .DS_Store
 ai.txt

CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2025-01-XX
+
+### Added
+- **Metadata Support**: Store additional data with progress
+  - `setMetadata(array $metadata)` - Set metadata array
+  - `getMetadata()` - Get all metadata
+  - `addMetadata(string $key, mixed $value)` - Add single metadata value
+  - `getMetadataValue(string $key, mixed $default)` - Get single metadata value
+- **Status Messages**: Attach status messages to progress
+  - `setStatusMessage(?string $message)` - Set status message
+  - `getStatusMessage()` - Get status message
+- **Event Callbacks**: React to progress changes
+  - `onProgressChange(callable $callback)` - Called on progress change with `(float $new, float $old, static $instance)`
+  - `onComplete(callable $callback)` - Called when progress reaches 100% with `(static $instance)`
+- **Progress Helpers**:
+  - `incrementLocalProgress(float $amount = 1)` - Increment/decrement progress
+  - `isComplete()` - Check if local progress is 100%
+  - `isOverallComplete()` - Check if overall progress is 100%
+  - `removeLocalFromOverall()` - Remove instance from overall calculation
+- **Precision Configuration**:
+  - `setPrecision(int $precision)` - Set decimal precision
+  - `getPrecision()` - Get current precision
+  - Configurable default precision via `config/progressable.php`
+- **CI/CD Improvements**:
+  - PHPStan static analysis (level 5) with Larastan
+  - Laravel Pint code style enforcement
+  - Code coverage with pcov and Codecov integration
+  - Parallel CI jobs for lint, analyse, and test
+- **Documentation**:
+  - CHANGELOG.md with full history
+  - CONTRIBUTING.md with guidelines
+  - Comprehensive README with API tables
+  - Codecov badge in README
+
+### Changed
+- `getLocalProgress()` now accepts `?int` (null uses configured default precision)
+- `getOverallProgress()` now accepts `?int` (null uses configured default precision)
+- Progress data now stores metadata and messages alongside progress value
+- Improved test suite with 35 tests and 70+ assertions
+
+### Fixed
+- README.md incorrect method names (`updateLocalProgress` -> `setLocalProgress`)
+- README.md incorrect imports (`use Verseles\Progressable` -> `use Verseles\Progressable\Progressable`)
+- Config comment referencing wrong class name (`FullProgress` -> `Progressable`)
+- Added missing return type to `getOverallUniqueName()`
+- Optimized `setLocalKey()` to avoid duplicate storage calls
+
+## [1.0.0] - Previous Release
+
+### Added
+- Initial release with core progress tracking functionality
+- `setOverallUniqueName()` - Set progress group identifier
+- `setLocalProgress()` - Update instance progress
+- `getLocalProgress()` - Get instance progress
+- `getOverallProgress()` - Get average progress of all instances
+- `resetLocalProgress()` - Reset instance to 0
+- `resetOverallProgress()` - Clear all progress data
+- `setCustomSaveData()` / `setCustomGetData()` - Custom storage callbacks
+- `setTTL()` / `getTTL()` - Cache TTL configuration
+- `setPrefixStorageKey()` - Custom cache key prefix
+- `setLocalKey()` / `getLocalKey()` - Custom instance identifiers
+- Laravel service provider with auto-discovery
+- Support for Laravel 11 and 12
+- PHP 8.4 requirement

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to Progressable
+
+First off, thank you for considering contributing to Progressable!
+
+## Development Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/verseles/progressable.git
+cd progressable
+```
+
+2. Install dependencies:
+```bash
+composer install
+```
+
+3. Run tests to make sure everything works:
+```bash
+composer test
+```
+
+## Code Quality Tools
+
+This project uses several tools to maintain code quality:
+
+### PHPUnit Tests
+```bash
+composer test
+```
+
+### Laravel Pint (Code Style)
+```bash
+# Check for style issues
+composer lint:test
+
+# Fix style issues automatically
+composer lint
+```
+
+### PHPStan (Static Analysis)
+```bash
+composer analyse
+```
+
+## Pull Request Process
+
+1. Fork the repository and create your branch from `main`
+2. Make your changes
+3. Ensure all tests pass: `composer test`
+4. Ensure code style is correct: `composer lint:test`
+5. Ensure static analysis passes: `composer analyse`
+6. Update documentation if needed (README.md, CHANGELOG.md)
+7. Submit your pull request
+
+## Coding Standards
+
+- Follow PSR-12 coding standards (enforced by Laravel Pint)
+- Write tests for new features
+- Keep methods focused and small
+- Use descriptive variable and method names
+- Add PHPDoc blocks for public methods
+
+## Adding New Features
+
+When adding new features:
+
+1. Add the feature implementation in `src/Progressable.php`
+2. Add tests in `tests/ProgressableTest.php`
+3. Update `README.md` with usage examples
+4. Add entry to `CHANGELOG.md` under `[Unreleased]`
+
+## Reporting Bugs
+
+When reporting bugs, please include:
+
+- PHP version
+- Laravel version (if applicable)
+- Progressable version
+- Steps to reproduce
+- Expected behavior
+- Actual behavior
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing.