Merge pull request #37 from Staffbase/code-cleanup

refactor: Code cleanup Pt1

Author: Ninerian

.github/copilot-instructions.md

@@ -0,0 +1,36 @@
+# GitHub Copilot instructions for plugins-sdk-php
+
+This guidance file helps Copilot generate code aligned with project standards and domain design for the Staffbase Plugin SDK for PHP.
+
+## General Copilot goals
+- Follow project coding style and PSR-4 namespace conventions.
+- Prefer using and extending the existing src/SSOToken, PluginSession, and RemoteCall infrastructure.
+- When creating new code, integrate with provided interfaces, traits, and classes (see src/SSOData, src/RemoteCall, src/Exceptions).
+- All code should work with PHP 8.3, strict_types, and Composer autoloading.
+- When suggesting test code, match the structure of test/ files and use PHPUnit 10+ only.
+
+## Style and static analysis
+- Conform to rules in .php-cs-fixer.dist.php (array_syntax short, strict_types, remove unused imports, use strict parameters).
+- Code should pass `composer run cs-fixer:check` and `composer run lint` on commit.
+- Code should pass PHPStan at level 4 (phpstan.neon.dist), including for new types, traits, and test cases.
+
+## Domain guidance
+- For SSO authentication, use and extend SSOToken, PluginSession, and SSODataTrait as the foundation — avoid duplicating token logic.
+- Remote call support should use AbstractRemoteCallHandler or interfaces from src/RemoteCall if you need plugin event handling (e.g., deletion).
+- When handling sessions, use PluginSession and its methods for SSO data. Avoid manual $_SESSION logic except for advanced cases.
+- Exceptions should inherit src/Exceptions base classes as relevant.
+
+## Recommended code generation practices
+- Prefer composition and interface-driven design (see src/SSOData, src/RemoteCall, src/Exceptions).
+- Follow README.md example patterns for token creation, session management, and error handling.
+- Place new classes in src/ with Staffbase\plugins\sdk\ namespace; place tests in test/ with Staffbase\plugins\test\ namespace.
+
+## Copilot DON'Ts
+- Do not add new dependencies unless absolutely required and justified in code comments.
+- Do not use deprecated PHP practices or legacy global state.
+- Do not bypass static analysis rules for quick fixes.
+- Do not create code outside of src/ and test/ unless explicitly requested. Never create example or playground code that is not integrated into the SDK or its tests.
+
+## Documentation
+- Consult CLAUDE.md at project root for further architectural guidance and standard commands.
+- Reference README.md and inline docblocks for API documentation style.

.github/workflows/php.yml

@@ -2,9 +2,14 @@ name: PHP Composer
 
 on:
   push:
-    branches: [ main ]
+    branches:
+      - 'main'
+      - '**/**'
+
   pull_request:
-    branches: [ main ]
+    branches:
+      - 'main'
+      - '**/**'
 
 jobs:
   run:
@@ -29,7 +34,10 @@ jobs:
 
     - name: Install dependencies
       if: steps.composer-cache.outputs.cache-hit != 'true'
-      run: composer update --prefer-dist --no-progress
+      run: composer install --prefer-dist --no-progress
+
+    - name: Linting
+      run: composer lint
 
     - name: Run test suite
       run: composer test

.gitignore

@@ -1,5 +1,43 @@
-.DS_Store
-.rnd
-composer.lock
-vendor
-.idea
+### PHP-CS-Fixer template
+# Covers PHP CS Fixer
+# Reference: https://cs.symfony.com/
+
+# Generated files
+.php-cs-fixer.cache
+
+# Local config See: https://cs.symfony.com/doc/config.html
+.php-cs-fixer.php
+
+### Composer template
+composer.phar
+/vendor/
+
+# Commit your application's lock file https://getcomposer.org/doc/01-basic-usage.md#commit-your-composer-lock-file-to-version-control
+# You may choose to ignore a library lock file http://getcomposer.org/doc/02-libraries.md#lock-file
+# composer.lock
+
+### PHPUnit template
+# Covers PHPUnit
+# Reference: https://phpunit.de/
+
+# Generated files
+.phpunit.result.cache
+.phpunit.cache
+clover.xml
+
+# PHPUnit
+/app/phpunit.xml
+/phpunit.xml
+
+
+# Build data
+/build/
+
+### PHPCodeSniffer template
+# CodeSniffer
+phpcs.xml
+
+/vendor/*
+/wpcs/*
+
+!/.gitignore

.php-cs-fixer.dist.php

@@ -0,0 +1,18 @@
+<?php
+
+$finder = PhpCsFixer\Finder::create()
+    ->exclude(['vendor', 'build'])
+    ->in(__DIR__);
+
+return (new PhpCsFixer\Config())
+    ->setRules([
+        '@PHP8x4Migration' => true,
+        '@PER-CS' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'declare_strict_types' => true,
+        'strict_param' => true,
+        'no_unused_imports' => true,
+    ])
+    ->setRiskyAllowed(true)
+    ->setFinder($finder)
+    ->setParallelConfig(PhpCsFixer\Runner\Parallel\ParallelConfigFactory::detect());

.phpactor.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "/phpactor.schema.json",
+    "language_server_phpstan.enabled": true,
+    "language_server_php_cs_fixer.enabled": true,
+    "indexer.exclude_patterns": [
+        "/vendor/**/Tests/**/*",
+        "/vendor/**/tests/**/*",
+        "/var/cache/**/*",
+        "/vendor/composer/**/*"
+    ],
+    "language_server.diagnostics_on_update": false,
+    "language_server_highlight.enabled": false
+}

CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+
+## Quick commands
+
+- Install dependencies: composer install
+- Run unit tests: composer test (runs phpunit)
+- Run tests with coverage: composer run test:coverage
+- Run static analysis: composer run phpstan (phpstan analyse --memory-limit=1G)
+- Run code style checks: composer run cs-fixer:check
+- Auto-fix code style: composer run cs-fixer:fix
+- Full check: composer run check (runs cs-fixer check, phpstan, and test coverage)
+- Lint (style + static analysis): composer run lint
+
+To run a single PHPUnit test (by file):
+- ./vendor/bin/phpunit path/to/TestFile.php
+
+To run a single test method:
+- ./vendor/bin/phpunit --filter testMethodName path/to/TestFile.php
+
+
+## Project overview — high level
+
+This repository provides a small PHP SDK for Staffbase plugin Single Sign-On (SSO) token parsing and validation.
+
+High-level structure:
+
+- src/: Core library code. Primary classes:
+  - src/SSOToken.php — main JWT parsing & validation wrapper for plugin SSO tokens (uses lcobucci/jwt)
+  - src/SSOTokenGenerator.php — utility to generate test tokens for unit tests
+  - src/PluginSession.php — session wrapper for persisting SSO data between requests
+  - src/RemoteCall/* — handlers and interfaces for app-initiated remote calls (delete-instance, etc.)
+  - src/SSOData/* — data interfaces/traits for shared and SSO specific claims
+  - src/Exceptions/* — domain exceptions (SSOAuthenticationException, SSOException, ...)
+  - src/Validation/* — custom validation constraints used by php-jwt/token validation
+  - src/AbstractToken.php — base token parsing/verification logic used by SSOToken and others
+
+- test/: PHPUnit test suite for the library. Tests instantiate SSOToken, SSOTokenGenerator and validate behavior.
+
+- composer.json: Composer metadata and scripts (lint, phpstan, tests, cs-fixer). Key runtime deps: lcobucci/jwt, lcobucci/clock.
+
+- phpstan.neon.dist: phpstan configuration (analyse src and test at level 4 by default).
+
+- README.md: user-facing documentation and examples (installation, usage examples, remote calls).
+
+
+## CI and hooks
+
+- GitHub Actions: a workflow badge exists in README, check .github/workflows for exact CI steps if needed.
+- Composer hooks: composer.json registers post-install and post-update hooks for composer-git-hooks. Pre-commit hooks in composer.extra.hooks run "composer fix" and "composer phpstan".
+
+
+## Notes for future Claude Code instances
+
+- Use Composer scripts defined in composer.json for all common operations (tests, lint, phpstan, cs-fixer). Prefer the scripts so local project configuration is respected.
+- When adding or editing PHP code, run CS Fixer and PHPStan locally (composer run fix; composer run phpstan) before running tests.
+- Tests are run with phpunit (vendor/bin/phpunit). For debugging a single test, prefer running vendor/bin/phpunit --filter.
+
+Key files to inspect for behavior changes:
+- src/SSOToken.php: constructor, token parsing and validation flow
+- src/AbstractToken.php: core token parsing/verification logic
+- src/Validation/HasInstanceId.php: custom constraint used by SSOToken
+- README.md and doc/api.md: user-visible behavior and API
+
+
+## When editing code
+
+- Prefer editing existing files rather than creating new ones unless a new module is required.
+- Follow PSR-4 autoloading in composer.json (namespace Staffbase\plugins\sdk\ -> src/)
+- Keep phpstan.neon.dist level consideration in mind
+
+
+## Contact and references
+
+- Project homepage: https://github.com/Staffbase/plugins-sdk-php
+- Composer entry: composer.json
+

codecov.yml

@@ -0,0 +1,29 @@
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 0%
+    patch:
+      default:
+        target: auto
+        threshold: 0%
+
+parsers:
+  gcov:
+    branch_detection:
+      conditional: yes
+      loop: yes
+      method: no
+      macro: no
+
+comment:
+  layout: "reach,diff,flags,tree"
+  behavior: default
+  require_changes: false

composer.json

@@ -15,22 +15,50 @@
 	"require": {
         "php": "^8.3 || ^8.4",
 		"lcobucci/jwt": "^5.5",
- 		"lcobucci/clock": "^3.3"
-
+		"lcobucci/clock": "^3.3"
 	},
 	"require-dev": {
+		"brainmaestro/composer-git-hooks": "^3.0",
+		"friendsofphp/php-cs-fixer": "^3.89",
 		"phpseclib/phpseclib": "^2.0",
-		"phpunit/phpunit": "^9.0"
+		"phpstan/extension-installer": "^1.4",
+		"phpstan/phpstan-phpunit": "^2.0",
+		"phpunit/phpunit": "^10.0"
 	},
 	"autoload": {
 		"psr-4": {
-			"Staffbase\\plugins\\sdk\\": "src",
-			"Staffbase\\plugins\\test\\": "test"
+			"Staffbase\\plugins\\sdk\\": "src/"
+		}
+	},
+	"autoload-dev": {
+		"psr-4": {
+			"Staffbase\\plugins\\test\\": "test/"
+		}
+	},
+	"config": {
+		"sort-packages": true,
+		"allow-plugins": {
+			"phpstan/extension-installer": true
 		}
 	},
 	"scripts": {
-		"test": "phpunit --colors='always' --debug $PHPUNIT_ARGS",
-		"lint": "phpcs --standard=PSR2 --extensions=php --ignore=*/vendor/* src test",
-		"fix": "phpcbf --standard=PSR2 --extensions=php --ignore=*/vendor/* src test"
+		"check": ["@cs-fixer:check", "@phpstan", "@test:coverage"],
+		"lint": ["@cs-fixer:check", "@phpstan"],
+		"fix": ["@cs-fixer:fix"],
+		"cs-fixer:check": "php-cs-fixer fix --dry-run --diff -v",
+		"cs-fixer:fix": "php-cs-fixer fix --diff -v",
+		"phpstan": "phpstan analyse --memory-limit=1G",
+		"test": "phpunit",
+		"test:coverage": "phpunit --coverage-text --coverage-clover=clover.xml",
+		"post-install-cmd": "cghooks add --ignore-lock",
+		"post-update-cmd": "cghooks update"
+	},
+	"extra": {
+		"hooks": {
+			"pre-commit": [
+				"composer fix",
+				"composer phpstan"
+			]
+		}
 	}
 }