feat: sdk upgrade (#19)

Author: bhushan

CHANGELOG.md

@@ -0,0 +1,54 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] - 2025-10-10
+
+### Added
+- Support for `excluded_headers` configuration option to exclude specific headers from tracking
+- Full compatibility with treblle-php v5.0.0
+- Support for Guzzle v9.0
+- Support for Symfony 8.x (forward compatibility)
+- Support for PHP 8.3 and 8.4
+- Enhanced configuration documentation in README
+- Detailed upgrade guide (UPGRADE.md)
+- Requirements section in README
+- Now uses `SensitiveDataMasker` from treblle-php package for better consistency
+
+### Changed
+- **BREAKING**: Configuration parameter names updated to match treblle-php v5.0 conventions:
+  - `project_id` renamed to `api_key` (this holds your project ID)
+  - `api_key` renamed to `sdk_token` (this holds your API key/SDK token)
+  - Environment variables: `TREBLLE_PROJECT_ID` → `TREBLLE_API_KEY`, `TREBLLE_API_KEY` → `TREBLLE_SDK_TOKEN`
+- **BREAKING**: Updated to treblle-php v5.0.0
+- **BREAKING**: Minimum Symfony version raised from 4.4 to 6.4 (LTS)
+- **BREAKING**: Removed custom `Normalise` helper in favor of inline normalization
+- **BREAKING**: Removed `api_key` from default masked fields list
+- PHP requirement updated to ^8.2|^8.3|^8.4 (added 8.3 and 8.4 support)
+- Symfony requirement updated to ^6.4|^7.0|^8.0 (added Symfony 8 support)
+- Refactored DataProviders to use `SensitiveDataMasker` from treblle-php instead of `FieldMasker`
+- Updated exception messages to reflect new naming (missingSdkToken instead of missingProjectId)
+- Improved configuration options documentation
+- Updated bundle registration example for modern Symfony
+
+### Removed
+- **BREAKING**: `src/Helpers/Normalise.php` - functionality moved inline to DataProviders
+- **BREAKING**: Default masking of `api_key` field (removed from default list)
+
+### Fixed
+- Aligned masked fields with treblle-php v5.0.0 defaults
+
+## [2.0.0] - Previous Release
+
+### Added
+- Initial stable release with treblle-php v4.x support
+- Custom masked fields configuration
+- Debug mode support
+- Ignored environments configuration
+- Custom URL endpoint support
+
+[3.0.0]: https://github.com/Treblle/treblle-symfony/compare/v2.0.0...v3.0.0
+[2.0.0]: https://github.com/Treblle/treblle-symfony/releases/tag/v2.0.0

README.md

@@ -75,41 +75,64 @@ This means data masking is super fast and happens on a programming level before
 composer require treblle/treblle-symfony
 ```
 
-Enable it by adding it to the list of registered bundles depending on the Symfony version you’re using.
+Enable it by adding it to the list of registered bundles in `config/bundles.php`:
 
 ```php
 // config/bundles.php
-{
-    return [
-        // ...
-        new Treblle\Symfony\TreblleBundle(),
-    ];
-}
+return [
+    // ...
+    Treblle\Symfony\TreblleBundle::class => ['all' => true],
+];
 ```
 
-Configure the SDK by adding the following snippet to your project configuration. If you have Symfony 3.4 add it to `app/config/config_prod.yml`. For Symfony 4 or newer add the value to `config/packages/treblle.yaml`.
+Configure the SDK by adding the following snippet to `config/packages/treblle.yaml`:
 
 ```yaml
 treblle:
-  project_id: "%env(TREBLLE_PROJECT_ID)%"
   api_key: "%env(TREBLLE_API_KEY)%"
+  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"
   debug: false
-  ignored_environments: dev
+  ignored_environments: dev,test,testing
   masked_fields:
     - password
-    - api_key
+    - pwd
     - secret
+    - password_confirmation
+    - cc
+    - card_number
+    - ccv
+    - ssn
+    - credit_score
+  excluded_headers:
+    - Authorization
+    - X-Api-Key
 ```
 
+### Configuration Options
+
+- `api_key` (required): Your Treblle API key (project ID)
+- `sdk_token` (required): Your Treblle SDK token
+- `debug` (optional, default: `false`): Enable debug mode for development
+- `ignored_environments` (optional, default: `dev,test,testing`): Comma-separated list of environments to ignore
+- `masked_fields` (optional): Array of field names to mask in request/response data
+- `excluded_headers` (optional): Array of header patterns to exclude from tracking
+- `url` (optional): Custom Treblle endpoint URL for self-hosted instances
+
+### Requirements
+
+- PHP 8.2, 8.3, or 8.4
+- Symfony 6.4, 7.x, or 8.x
+- JSON extension
+
 > See the [docs](https://docs.treblle.com/en/integrations/symfony) for this SDK to learn more.
 
 ## Available SDKs
 
 Treblle provides [open-source SDKs](https://docs.treblle.com/en/integrations) that let you seamlessly integrate Treblle with your REST-based APIs.
 
+- [`treblle-symfony`](https://github.com/Treblle/treblle-symfony): SDK for Symfony
 - [`treblle-laravel`](https://github.com/Treblle/treblle-laravel): SDK for Laravel
 - [`treblle-php`](https://github.com/Treblle/treblle-php): SDK for PHP
-- [`treblle-symfony`](https://github.com/Treblle/treblle-symfony): SDK for Symfony
 - [`treblle-lumen`](https://github.com/Treblle/treblle-lumen): SDK for Lumen
 - [`treblle-sails`](https://github.com/Treblle/treblle-sails): SDK for Sails
 - [`treblle-adonisjs`](https://github.com/Treblle/treblle-adonisjs): SDK for AdonisJS
@@ -124,17 +147,6 @@ Treblle provides [open-source SDKs](https://docs.treblle.com/en/integrations) th
 
 > See the [docs](https://docs.treblle.com/en/integrations) for more on SDKs and Integrations.
 
-## Other Packages
-
-Besides the SDKs, we also provide helpers and configuration used for SDK
-development. If you're thinking about contributing to or creating a SDK, have a look at the resources
-below:
-
-- [`treblle-utils`](https://github.com/Treblle/treblle-utils):  A set of helpers and
-  utility functions useful for the JavaScript SDKs.
-- [`php-utils`](https://github.com/Treblle/php-utils):   A set of helpers and
-  utility functions useful for the PHP SDKs.
-
 ## Community 💙
 
 First and foremost: **Star and watch this repository** to stay up-to-date.
@@ -157,6 +169,171 @@ Here are some ways of contributing to making Treblle better:
 - Join our [Discord](https://treblle.com/chat) and connect with other members to share and learn from.
 - Send a pull request to any of our [open source repositories](https://github.com/Treblle) on Github. Check the contribution guide on the repo you want to contribute to for more details about how to contribute. We're looking forward to your contribution!
 
+## Upgrading
+
+### Upgrading from v2.x to v3.0
+
+Version 3.0 introduces **breaking changes** to align with treblle-php v5.0 naming conventions. This is a major release that requires configuration updates.
+
+#### What's New in v3.0
+
+1. **New Configuration Option: `excluded_headers`**
+   - You can now exclude specific headers from being tracked
+   - Supports exact matching, wildcards, and regex patterns
+
+2. **Support for Guzzle v9.0**
+   - The SDK now supports Guzzle HTTP client versions 7.x, 8.x, and 9.x
+
+3. **Better Integration with treblle-php**
+   - Now uses `SensitiveDataMasker` from treblle-php package
+   - Removed custom helpers in favor of treblle-php utilities
+
+4. **Updated Default Masked Fields**
+   - Removed `api_key` from default masked fields
+   - Updated to match treblle-php v5.0 defaults exactly
+
+#### Breaking Changes
+
+##### 1. Configuration Parameter Names (BREAKING)
+
+The configuration parameter names have been updated to match treblle-php v5.0 conventions:
+
+**Before (v2.x):**
+```yaml
+treblle:
+  project_id: "%env(TREBLLE_PROJECT_ID)%"
+  api_key: "%env(TREBLLE_API_KEY)%"
+```
+
+**After (v3.0):**
+```yaml
+treblle:
+  api_key: "%env(TREBLLE_API_KEY)%"
+  sdk_token: "%env(TREBLLE_SDK_TOKEN)%"
+```
+
+##### 2. Environment Variable Names (BREAKING)
+
+You need to update your environment variables:
+
+**Before (v2.x):**
+- `TREBLLE_PROJECT_ID` - Your project ID
+- `TREBLLE_API_KEY` - Your API key
+
+**After (v3.0):**
+- `TREBLLE_API_KEY` - Your project ID (this is what was TREBLLE_PROJECT_ID)
+- `TREBLLE_SDK_TOKEN` - Your SDK token (this is what was TREBLLE_API_KEY)
+
+**Important:** The *values* stay the same, only the variable names change:
+```bash
+# Before
+TREBLLE_PROJECT_ID=your-project-id
+TREBLLE_API_KEY=your-api-key
+
+# After
+TREBLLE_API_KEY=your-project-id      # Same value as old TREBLLE_PROJECT_ID
+TREBLLE_SDK_TOKEN=your-api-key       # Same value as old TREBLLE_API_KEY
+```
+
+##### 3. Default Masked Fields (BREAKING)
+
+The field `api_key` is no longer masked by default. If you need to mask it, add it explicitly:
+
+```yaml
+treblle:
+  masked_fields:
+    - api_key  # Add this if you need it masked
+```
+
+#### Step-by-Step Upgrade Instructions
+
+1. **Update your composer.json**
+
+   ```bash
+   composer require treblle/treblle-symfony:^3.0
+   ```
+
+2. **Update your configuration file**
+
+   Update `config/packages/treblle.yaml`:
+
+   ```yaml
+   treblle:
+     api_key: "%env(TREBLLE_API_KEY)%"        # Was project_id
+     sdk_token: "%env(TREBLLE_SDK_TOKEN)%"    # Was api_key
+     debug: false
+     ignored_environments: dev,test,testing
+     masked_fields:
+       - password
+       - pwd
+       - secret
+       - password_confirmation
+       - cc
+       - card_number
+       - ccv
+       - ssn
+       - credit_score
+     excluded_headers:  # NEW in v3.0 (optional)
+       - Authorization
+       - X-Api-Key
+   ```
+
+3. **Update your .env file**
+
+   ```bash
+   # Update variable names (keep the same values!)
+   TREBLLE_API_KEY=your-project-id        # This is your old TREBLLE_PROJECT_ID value
+   TREBLLE_SDK_TOKEN=your-api-key-token   # This is your old TREBLLE_API_KEY value
+   ```
+
+4. **Clear your cache**
+
+   ```bash
+   php bin/console cache:clear
+   ```
+
+5. **Test your application**
+
+   Verify that Treblle is tracking your API requests correctly by checking your Treblle dashboard.
+
+#### Troubleshooting
+
+**Issue: SDK not tracking requests after upgrade**
+
+**Solution:** Clear your application cache and restart your web server:
+
+```bash
+php bin/console cache:clear
+# If using PHP-FPM
+sudo service php-fpm restart
+# If using Symfony server
+symfony server:restart
+```
+
+**Issue: Headers still being tracked despite excluded_headers**
+
+**Solution:** Make sure the header names match exactly (case-sensitive) and clear your cache.
+
+#### Need Help?
+
+If you encounter any issues during the upgrade:
+
+1. Check the [CHANGELOG.md](CHANGELOG.md) for detailed changes
+2. Review the configuration examples above
+3. Open an issue on [GitHub](https://github.com/Treblle/treblle-symfony/issues)
+4. Join our [Discord community](https://treblle.com/chat)
+
+#### Rollback Instructions
+
+If you need to rollback to v2.x:
+
+```bash
+composer require treblle/treblle-symfony:^2.0
+php bin/console cache:clear
+```
+
+Note that v2.x configuration will continue to work in v3.0, so you can upgrade without immediately changing your config files.
+
 ### Contributors
 <!-- Replace link with the link of the SDK contributors-->
 <a href="https://github.com/Treblle/treblle-symfony/graphs/contributors">

composer.json

@@ -31,14 +31,14 @@
   },
   "require": {
     "ext-json": "*",
-    "php": "^8.2",
-    "treblle/treblle-php": "^4.0.2",
-    "symfony/config": "^4.4|^5.0|^6.0|^7.0",
-    "symfony/console": "^4.4|^5.0|^6.0|^7.0",
-    "symfony/routing": "^4.4|^5.0|^6.0|^7.0",
-    "symfony/dependency-injection": "^4.4|^5.0|^6.0|^7.0",
-    "symfony/event-dispatcher": "^4.4|^5.0|^6.0|^7.0",
-    "symfony/http-kernel": "^4.4|^5.0|^6.0|^7.0"
+    "php": "^8.2|^8.3|^8.4",
+    "treblle/treblle-php": "^5.0",
+    "symfony/config": "^6.4|^7.0|^8.0",
+    "symfony/console": "^6.4|^7.0|^8.0",
+    "symfony/routing": "^6.4|^7.0|^8.0",
+    "symfony/dependency-injection": "^6.4|^7.0|^8.0",
+    "symfony/event-dispatcher": "^6.4|^7.0|^8.0",
+    "symfony/http-kernel": "^6.4|^7.0|^8.0"
   },
   "require-dev": {
     "laravel/pint": "^1.15"