pre-release polishment

.github/workflows/ci.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.2', '8.3']
+        php: ['8.2', '8.3', '8.4']
     name: Composer PHP ${{ matrix.php }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
@@ -25,10 +25,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.2', '8.3']
+        php: ['8.2', '8.3', '8.4']
     name: PHPUnit PHP ${{ matrix.php }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
@@ -45,36 +45,36 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.2', '8.3']
+        php: ['8.2', '8.3', '8.4']
     name: PHPStan PHP ${{ matrix.php }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
           coverage: none
       - run: composer update --no-progress --no-interaction
-      - run: vendor/bin/phpstan analyze src --level=5 --no-progress
+      - run: vendor/bin/phpstan analyze src --level=9 --no-progress
 
   phpstan_lowest:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: ['8.2', '8.3']
+        php: ['8.2', '8.3', '8.4']
     name: PHPStan Lowest PHP ${{ matrix.php }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
           coverage: none
       - run: composer update --prefer-lowest --no-progress --no-interaction
-      - run: vendor/bin/phpstan analyze src --level=5 --no-progress
+      - run: vendor/bin/phpstan analyze src --level=9 --no-progress
 
   codesniffer:
     runs-on: ubuntu-latest
     name: PHPCS
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - run: composer update --no-progress --no-interaction
       - run: vendor/bin/phpcs src --standard=PSR2 -n

.gitignore

@@ -5,3 +5,4 @@ composer.lock
 coverage.xml
 coverage*
 .phpunit.cache
+.DS_Store

CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to Multitron
+
+Thank you for your interest in contributing to Multitron! This document provides guidelines and instructions for contributing.
+
+## Code of Conduct
+
+Be respectful, professional, and constructive in all interactions.
+
+## How to Contribute
+
+### Reporting Bugs
+
+1. Check if the bug has already been reported in [Issues](https://github.com/riki137/multitron/issues)
+2. If not, create a new issue with:
+    - Clear, descriptive title
+    - Detailed description of the bug
+    - Steps to reproduce
+    - Expected vs actual behavior
+    - PHP version and environment details
+    - Minimal code example if possible
+
+### Suggesting Features
+
+1. Check existing [Issues](https://github.com/riki137/multitron/issues) and [Pull Requests](https://github.com/riki137/multitron/pulls)
+2. Create an issue describing:
+    - The problem you're trying to solve
+    - Your proposed solution
+    - Any alternatives you've considered
+    - Examples of how it would be used
+
+### Submitting Pull Requests
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/multitron.git
+   cd multitron
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   composer install
+   ```
+
+3. **Create a Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/your-bug-fix
+   ```
+
+4. **Make Your Changes**
+    - Follow existing code style (PSR-2)
+    - Add tests for new features
+    - Update documentation as needed
+    - Keep commits focused and atomic
+
+5. **Run Tests**
+   ```bash
+   vendor/bin/phpunit
+   vendor/bin/phpstan analyze src --level=9
+   vendor/bin/phpcs src --standard=PSR2 -n
+   ```
+
+6. **Commit Your Changes**
+   ```bash
+   git commit -m "Brief description of changes"
+   ```
+
+   Good commit message examples:
+    - `Add support for custom IPC adapters`
+    - `Fix memory leak in ProgressClient`
+    - `Update Laravel integration documentation`
+
+7. **Push and Create PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+   Then open a Pull Request on GitHub.
+
+## Development Guidelines
+
+### Code Style
+
+- Follow PSR-2 coding standard
+- Use strict types: `declare(strict_types=1);`
+- Use typed properties where possible
+- Prefer `readonly` for immutable properties
+- Prefer `final` classes
+- Document complex types with PHPDoc
+
+### Testing
+
+- Write tests for new features
+- Ensure existing tests pass
+- Aim for good code coverage
+- Test both success and failure cases
+
+### Documentation
+
+- Update README.md if adding user-facing features
+- Update relevant integration docs (Symfony, Laravel, Nette, Native)
+- Add PHPDoc comments for public APIs
+- Include code examples for complex features
+
+### Architecture
+
+- Maintain separation of concerns
+- Use dependency injection
+- Follow existing patterns in the codebase
+- Keep backwards compatibility in mind
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing.
+
+Thank you for making Multitron better! 🚀
+

README.md

@@ -5,7 +5,8 @@
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/riki137/multitron/ci.yml?branch=master&style=flat-square)](https://github.com/riki137/multitron/actions?query=workflow%3Aci+branch%3Amaster)
 [![Code Coverage](https://codecov.io/gh/riki137/multitron/branch/master/graph/badge.svg?style=flat-square)](https://codecov.io/gh/riki137/multitron)
-[![PHPStan Level 9](https://img.shields.io/badge/PHPStan-level%209-brightgreen.svg?style=flat-square)](https://github.com/phpstan/phpstan)
+![PHP Version](https://img.shields.io/packagist/php-v/riki137/multitron.svg)
+![PHPStan Level 9](https://img.shields.io/badge/PHPStan-level%209-brightgreen.svg?style=flat-square)
 
 **Multitron** is a powerful, high-performance **PHP task orchestrator** designed to simplify parallel processing, concurrency, and automation in PHP applications. Quickly execute complex tasks asynchronously, maximizing the efficiency and scalability of your workflows.
 
@@ -17,6 +18,24 @@
 
 ---
 
+## Table of Contents
+
+- [Why Choose Multitron?](#why-choose-multitron)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Example](#usage)
+  - [Running Tasks](#usage)
+  - [Central Cache](#central-cache)
+  - [Reporting Progress](#reporting-progress)
+  - [Partitioned Tasks](#partitioned-tasks)
+  - [Accessing CLI Options](#accessing-cli-options)
+  - [Custom Progress Output](#custom-progress-output)
+- [Contributing](#contribute-to-multitron)
+- [License](#license)
+
+---
+
 ## Why Choose Multitron?
 
 * 🔄 **Efficient Task Dependency Management**: Clearly define task dependencies with intuitive declarative syntax.
@@ -224,6 +243,69 @@ Implement the factory to send progress anywhere you like.
 
 ---
 
+## Troubleshooting
+
+### "ext-pcntl is required"
+Multitron requires the `pcntl` extension for process management. Install it:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install php-pcntl
+
+# macOS (usually included)
+# If missing, use Homebrew PHP
+brew install php
+```
+
+### Worker processes hang or timeout
+- Check the worker timeout setting (default 60s):
+  ```php
+  $factory->setWorkerTimeout(300.0); // 5 minutes
+  ```
+- Ensure your tasks don't have infinite loops
+- Check for deadlocks in IPC communication
+
+### "WorkerCommand not found" error
+Make sure you've registered the worker command:
+
+```php
+// Symfony - register extension in Kernel
+$container->registerExtension(new MultitronExtension());
+
+// Laravel - add to bootstrap/providers.php
+MultitronServiceProvider::class,
+
+// Native - add to application
+$app->add($factory->getWorkerCommand());
+```
+
+### Memory limit errors
+Adjust the memory limit:
+```bash
+php bin/console app:tasks -m 1G
+```
+
+Or set it in your task command initialization.
+
+### Tasks not running in parallel
+- Check concurrency setting: `php bin/console app:tasks -c 8`
+- Verify task dependencies aren't creating a serial execution path
+- Ensure you have enough CPU cores available
+
+### Progress not updating
+- Check the update interval: `php bin/console app:tasks -u 0.5`
+- In CI environments, use `--interactive=no` for plain output
+- Verify you're calling `$comm->progress->addDone()` in your tasks
+
+### Cache data not persisting between tasks
+- Ensure you're using `$comm->cache->write()` before `read()`
+- Remember to call `->await()` on read promises
+- Cache is process-scoped; it doesn't persist after the command finishes
+
+For more help, check existing [GitHub Issues](https://github.com/riki137/multitron/issues) or open a new one.
+
+---
+
 ## Contribute to Multitron!
 
 Your feedback, issues, and contributions are highly encouraged. Open a GitHub issue or start a pull request to help improve PHP concurrency and task management:
@@ -237,6 +319,3 @@ Your feedback, issues, and contributions are highly encouraged. Open a GitHub is
 
 Multitron is MIT licensed. See the [LICENSE](LICENSE) file for full details.
 
----
-
-**SEO Keywords:** PHP Task Orchestrator, Parallel Processing PHP, Symfony CLI Automation, Asynchronous PHP Tasks, Multitron PHP, PHP Concurrency, PHP Task Manager, Open-source PHP Library

SECURITY.md

@@ -0,0 +1,59 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Multitron, please report it privately:
+
+**Email:** popelis@efabrica.sk
+
+**Please include:**
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+**Response Time:**
+- We aim to acknowledge reports within 48 hours
+- We'll provide a more detailed response within 7 days
+- Security patches will be released as soon as possible
+
+## Security Considerations
+
+### Process Execution
+Multitron spawns worker processes using Inter-Process Communication (IPC). Ensure:
+- Task factories don't execute untrusted code
+- Command-line options are validated in your tasks
+- Worker processes run with appropriate system permissions
+
+### Inter-Process Communication
+- IPC data is serialized between processes
+- Validate data received from shared cache
+- Don't store sensitive data in the shared cache without encryption
+
+### Resource Limits
+- Set appropriate memory limits using `-m` option
+- Monitor worker process resource usage
+- Implement timeouts for long-running tasks
+
+## Best Practices
+
+1. **Validate Input:** Always validate and sanitize data in your tasks
+2. **Principle of Least Privilege:** Run workers with minimal required permissions
+3. **Keep Updated:** Use the latest stable version
+4. **Monitor Logs:** Review task output for suspicious activity
+5. **Secure Dependencies:** Keep dependencies updated
+
+## Disclosure Policy
+
+- Security issues will be disclosed after a patch is available
+- We'll credit researchers who report valid vulnerabilities (unless they prefer anonymity)
+- CVE IDs will be requested for significant vulnerabilities
+
+Thank you for helping keep Multitron secure! 🔒