v3.0.0 — PHP 8.1 + Monolog 3 modernization (#132)

* Bump PHP min to 8.1 and Monolog to 3.0

* Modernize CloudWatch handler for PHP 8.1 and Monolog 3

- write() now takes Monolog\LogRecord (was array)
- Constructor promotion + readonly properties; full type coverage
- $level accepts int|string|Monolog\Level (default Level::Debug)
- New $createStream argument (10th, default true) — set false to skip
  DescribeLogStreams + CreateLogStream when the stream is provisioned
  out of band; lets users drop those IAM permissions
- PHPUnit config migrated to 10.x schema

* Switch lint to PSR-12 and add phpstan to CI matrix

* Update README, CHANGELOG, and CONTRIBUTING for 3.0

* Loosen aws/aws-sdk-php constraint to ^3.0

* Set 3.0.0 release date in CHANGELOG

Author: maxbanton

.github/workflows/php.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: ["8.2", "8.3", "8.4", "8.5"]
+        php: ["8.1", "8.2", "8.3", "8.4", "8.5"]
     steps:
       - uses: actions/checkout@v4
 
@@ -29,6 +29,9 @@ jobs:
       - name: Lint
         run: make PHP=${{ matrix.php }} lint
 
+      - name: Static analysis
+        run: make PHP=${{ matrix.php }} analyse
+
       - name: Tests
         run: make PHP=${{ matrix.php }} test
 

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-05-03
+
+### Added
+
+- `$createStream` constructor argument (10th, default `true`). Set to `false` to skip `DescribeLogStreams` + `CreateLogStream` when the log stream is provisioned out of band (e.g. via Terraform). Lets users drop the matching IAM permissions.
+- Full type coverage on the constructor and properties (constructor promotion, `readonly` for immutable state).
+- `phpstan` (level 8) runs in CI alongside lint and tests.
+
+### Changed
+
+- Coding standard upgraded from PSR-2 to PSR-12.
+- PHPUnit upgraded to `^10.5 || ^11.0`.
+
+### Removed
+
+- Support for PHP 7.x and 8.0. Minimum PHP is now `^8.1`.
+- Support for Monolog 2. Minimum Monolog is now `^3.0`.
+
+### Migration
+
+- Replace any `Monolog\Logger::DEBUG` (or other level constant) usage with `Monolog\Level::Debug`. The `$level` constructor argument continues to accept `int|string|Level` so string values like `'debug'` keep working.
+- Symfony service definitions referencing `!php/const Monolog\Logger::WARNING` must change to `!php/const Monolog\Level::Warning`.
+- Subclasses overriding `protected function write(array $record): void` must update the signature to `protected function write(\Monolog\LogRecord $record): void` and access fields via `->property` instead of `['key']`.
+- The constructor parameter order, names, and defaults of the existing 9 arguments are unchanged. Existing Symfony positional `arguments:` lists and Laravel `with`/`handler_with` named-key configs continue to work after the platform upgrades above.
+
 ## [2.1.0] - 2026-04-26
 
 ### Added
@@ -36,5 +61,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **No breaking public API changes.** Adds public `flush()` and overrides `reset()` to flush. Existing constructor and method signatures are unchanged; existing `^2.0` pins continue to work without modification.
 - Minimum PHP / Monolog versions unchanged (`^7.2 || ^8` / `monolog/monolog: ^2.0`). CI tests PHP 8.2 – 8.5; no code paths require newer PHP.
 
-[Unreleased]: https://github.com/maxbanton/cwh/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/maxbanton/cwh/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/maxbanton/cwh/compare/v2.1.0...v3.0.0
 [2.1.0]: https://github.com/maxbanton/cwh/compare/v2.0.4...v2.1.0

CONTRIBUTING.md

@@ -16,4 +16,18 @@
 
 Changes that are cosmetic in nature and do not add anything substantial to the stability, functionality, or testability will generally not be accepted.
 
+#### **Local development**
+
+Use the Makefile targets — they run inside Docker against the supported PHP matrix and exactly match what CI runs. Direct `phpunit`/`phpcs`/`phpstan` invocations on your host may pick up a different PHP version or dependency set:
+
+```bash
+make build-svc PHP=8.4    # build the dev container
+make install   PHP=8.4    # composer install inside it
+make lint                 # PSR-12 lint via phpcs
+make lint-fix             # auto-fix PSR-12 violations via phpcbf
+make analyse              # phpstan level 8
+make test                 # PHPUnit
+make matrix               # run install + lint + test across PHP 8.1–8.5 in parallel
+```
+
 Thanks!

Makefile

@@ -25,10 +25,10 @@ test-coverage:
 	$(DC) vendor/bin/phpunit --coverage-text --coverage-clover build/logs/clover.xml
 
 lint:
-	$(DC) vendor/bin/phpcs --standard=psr2 --ignore=Tests src/
+	$(DC) vendor/bin/phpcs --standard=PSR12 --ignore=Tests src/
 
 lint-fix:
-	$(DC) vendor/bin/phpcbf --standard=psr2 --ignore=Tests src/
+	$(DC) vendor/bin/phpcbf --standard=PSR12 --ignore=Tests src/
 
 analyse:
 	$(DC) vendor/bin/phpstan analyse --level=8 src/
@@ -40,7 +40,7 @@ shell:
 	$(DC) bash
 
 matrix:
-	@printf '8.2\n8.3\n8.4\n8.5\n' | xargs -n1 -P4 -I{} $(MAKE) PHP={} install ci
+	@printf '8.1\n8.2\n8.3\n8.4\n8.5\n' | xargs -n1 -P5 -I{} $(MAKE) PHP={} install ci
 
 clean:
 	$(COMPOSE) down -v

README.md

@@ -19,7 +19,8 @@ Please press **★ Star** button if you find this library useful.
 This library uses AWS API through AWS PHP SDK, which has limits on concurrent requests. It means that on high concurrent or high load applications it may not work on it's best way. Please consider using another solution such as logging to the stdout and redirecting logs with fluentd.
 
 ## Requirements
-* PHP ^7.3
+* PHP ^8.1
+* Monolog ^3.0
 * AWS account with proper permissions (see list of permissions below)
 
 ## Features
@@ -32,7 +33,7 @@ This library uses AWS API through AWS PHP SDK, which has limits on concurrent re
 Install the latest version with [Composer](https://getcomposer.org/) by running
 
 ```bash
-$ composer require maxbanton/cwh:^2.0
+$ composer require maxbanton/cwh:^3.0
 ```
 
 ## Basic Usage
@@ -41,8 +42,9 @@ $ composer require maxbanton/cwh:^2.0
 
 use Aws\CloudWatchLogs\CloudWatchLogsClient;
 use Maxbanton\Cwh\Handler\CloudWatch;
-use Monolog\Logger;
 use Monolog\Formatter\JsonFormatter;
+use Monolog\Level;
+use Monolog\Logger;
 
 $sdkParams = [
     'region' => 'eu-west-1',
@@ -67,7 +69,12 @@ $streamName = 'ec2-instance-1';
 $retentionDays = 30;
 
 // Instantiate handler (tags are optional)
-$handler = new CloudWatch($client, $groupName, $streamName, $retentionDays, 10000, ['my-awesome-tag' => 'tag-value']);
+$handler = new CloudWatch($client, $groupName, $streamName, $retentionDays, 10000, ['my-awesome-tag' => 'tag-value'], Level::Debug);
+
+// Set $createStream to false (10th argument) when the log stream is provisioned out of band
+// (e.g. via Terraform `aws_cloudwatch_log_stream`). This skips DescribeLogStreams + CreateLogStream
+// and lets you drop the matching IAM permissions.
+// $handler = new CloudWatch($client, $groupName, $streamName, $retentionDays, 10000, [], Level::Debug, true, true, false);
 
 // Optionally set the JsonFormatter to be able to access your log messages in a structured way
 $handler->setFormatter(new JsonFormatter());
@@ -106,12 +113,24 @@ $client = new CloudWatchLogsClient([
 ```
 
 ## Frameworks integration
- - [Silex](http://silex.sensiolabs.org/doc/master/providers/monolog.html#customization)
- - [Symfony](http://symfony.com/doc/current/logging.html) ([Example](https://github.com/maxbanton/cwh/issues/10#issuecomment-296173601))
- - [Lumen](https://lumen.laravel.com/docs/5.2/errors)
- - [Laravel](https://laravel.com/docs/5.4/errors) ([Example](https://stackoverflow.com/a/51790656/1856778))
-  
+ - [Symfony](https://symfony.com/doc/current/logging.html) ([Example](https://github.com/maxbanton/cwh/issues/10#issuecomment-296173601))
+ - [Laravel](https://laravel.com/docs/12.x/logging) ([Example](https://stackoverflow.com/a/51790656/1856778))
+
  [And many others](https://github.com/Seldaek/monolog#framework-integrations)
+
+## Migrating from 2.x to 3.x
+
+3.x is a breaking release that drops Monolog 2 and PHP 7.x support. The constructor parameter order, names, and defaults are preserved — existing Symfony YAML and Laravel `with`/`handler_with` configs continue to work after the platform upgrades below.
+
+**Required changes:**
+- Bump PHP to 8.1 or newer.
+- Bump Monolog to 3.x.
+- The `Monolog\Logger::DEBUG` (and other) constants were removed in Monolog 3. Use `Monolog\Level::Debug` instead — `int|string|Level` are all accepted by the `$level` constructor argument.
+- Symfony service definitions referencing `!php/const Monolog\Logger::WARNING` must change to `!php/const Monolog\Level::Warning`.
+- Laravel channels using `'level' => 'warning'` (string form) keep working unchanged.
+
+**New (optional):**
+- A 10th constructor argument `$createStream` (default `true`). Set to `false` to skip `DescribeLogStreams`/`CreateLogStream` for pre-provisioned streams; lets you drop those IAM permissions.
 
 # AWS IAM needed permissions
 if you prefer to use a separate programmatic IAM user (recommended) or want to define a policy, make sure following permissions are included:
@@ -122,7 +141,9 @@ if you prefer to use a separate programmatic IAM user (recommended) or want to d
 1. `DescribeLogStreams` [aws docs](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeLogStreams.html)
 1. `DescribeLogGroups` [aws docs](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_DescribeLogGroups.html)
 
-When setting the `$createGroup` argument to `false`, permissions `DescribeLogGroups` and `CreateLogGroup` can be omitted
+When setting the `$createGroup` argument to `false`, permissions `DescribeLogGroups` and `CreateLogGroup` can be omitted.
+
+When setting the `$createStream` argument to `false`, permissions `DescribeLogStreams` and `CreateLogStream` can be omitted. Use this when the log stream is provisioned out of band (e.g. via Terraform). If the stream does not exist at runtime, `PutLogEvents` will fail with `ResourceNotFoundException`.
 
 ## AWS IAM Policy full json example
 ```json

compose.yaml

@@ -1,4 +1,16 @@
 services:
+  php81:
+    build:
+      context: .
+      dockerfile: docker/Dockerfile
+      args:
+        PHP_VERSION: '8.1'
+    working_dir: /app
+    volumes:
+      - .:/app
+      - composer-cache:/tmp/composer
+      - vendor-81:/app/vendor
+
   php82:
     build:
       context: .
@@ -49,6 +61,7 @@ services:
 
 volumes:
   composer-cache:
+  vendor-81:
   vendor-82:
   vendor-83:
   vendor-84:

composer.json

@@ -21,19 +21,22 @@
     "source": "https://github.com/maxbanton/cwh"
   },
   "require": {
-    "php": "^7.2 || ^8",
-    "monolog/monolog": "^2.0",
-    "aws/aws-sdk-php": "^3.18"
+    "php": "^8.1",
+    "aws/aws-sdk-php": "^3.0",
+    "monolog/monolog": "^3.0"
   },
   "require-dev": {
-    "phpunit/phpunit": "^8.5 || ^9.4",
-    "squizlabs/php_codesniffer": "^3.5"
+    "phpstan/phpstan": "^1.11",
+    "phpunit/phpunit": "^10.5 || ^11.0",
+    "squizlabs/php_codesniffer": "^3.10"
   },
   "suggest": {
     "maxbanton/dd": "Minimalistic dump-and-die function for easy debugging"
   },
   "config": {
-    "preferred-install": "dist"
+    "allow-plugins": {},
+    "preferred-install": "dist",
+    "sort-packages": true
   },
   "autoload": {
     "psr-4": {

phpstan.neon.dist

@@ -0,0 +1,11 @@
+parameters:
+    level: 8
+    paths:
+        - src
+    treatPhpDocTypesAsCertain: false
+    ignoreErrors:
+        # User-facing $level accepts int|string|Level for ergonomics.
+        # Monolog\Logger::toMonologLevel() narrows internally; broader type is intentional.
+        -
+            message: '#Parameter \#1 \$level of static method Monolog\\Logger::toMonologLevel\(\) expects.*int\|Monolog\\Level\|string given\.#'
+            path: src/Handler/CloudWatch.php

phpunit.xml.dist

@@ -1,23 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd"
-    backupGlobals="false"
-    backupStaticAttributes="false"
-    bootstrap="vendor/autoload.php"
-    colors="true"
-    convertErrorsToExceptions="true"
-    convertNoticesToExceptions="true"
-    convertWarningsToExceptions="true"
-    processIsolation="false"
-    stopOnFailure="false">
- <coverage>
-    <include>
-      <directory>src</directory>
-    </include>
-  </coverage>
-  <testsuites>
-    <testsuite name="Handler Test Suite">
-      <directory suffix="Test.php">./tests/</directory>
-    </testsuite>
-  </testsuites>
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         backupGlobals="false"
+         backupStaticProperties="false"
+         processIsolation="false"
+         stopOnFailure="false">
+    <testsuites>
+        <testsuite name="Handler Test Suite">
+            <directory suffix="Test.php">./tests/</directory>
+        </testsuite>
+    </testsuites>
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
 </phpunit>