Skip to content

Commit 75d32c1

Browse files
NinerianNinerian
committed
chore: add ai instructions
1 parent 85ca00c commit 75d32c1

2 files changed

Lines changed: 115 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# GitHub Copilot instructions for plugins-sdk-php
2+
3+
This guidance file helps Copilot generate code aligned with project standards and domain design for the Staffbase Plugin SDK for PHP.
4+
5+
## General Copilot goals
6+
- Follow project coding style and PSR-4 namespace conventions.
7+
- Prefer using and extending the existing src/SSOToken, PluginSession, and RemoteCall infrastructure.
8+
- When creating new code, integrate with provided interfaces, traits, and classes (see src/SSOData, src/RemoteCall, src/Exceptions).
9+
- All code should work with PHP 8.3, strict_types, and Composer autoloading.
10+
- When suggesting test code, match the structure of test/ files and use PHPUnit 10+ only.
11+
12+
## Style and static analysis
13+
- Conform to rules in .php-cs-fixer.dist.php (array_syntax short, strict_types, remove unused imports, use strict parameters).
14+
- Code should pass `composer run cs-fixer:check` and `composer run lint` on commit.
15+
- Code should pass PHPStan at level 4 (phpstan.neon.dist), including for new types, traits, and test cases.
16+
17+
## Domain guidance
18+
- For SSO authentication, use and extend SSOToken, PluginSession, and SSODataTrait as the foundation — avoid duplicating token logic.
19+
- Remote call support should use AbstractRemoteCallHandler or interfaces from src/RemoteCall if you need plugin event handling (e.g., deletion).
20+
- When handling sessions, use PluginSession and its methods for SSO data. Avoid manual $_SESSION logic except for advanced cases.
21+
- Exceptions should inherit src/Exceptions base classes as relevant.
22+
23+
## Recommended code generation practices
24+
- Prefer composition and interface-driven design (see src/SSOData, src/RemoteCall, src/Exceptions).
25+
- Follow README.md example patterns for token creation, session management, and error handling.
26+
- Place new classes in src/ with Staffbase\plugins\sdk\ namespace; place tests in test/ with Staffbase\plugins\test\ namespace.
27+
28+
## Copilot DON'Ts
29+
- Do not add new dependencies unless absolutely required and justified in code comments.
30+
- Do not use deprecated PHP practices or legacy global state.
31+
- Do not bypass static analysis rules for quick fixes.
32+
- 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.
33+
34+
## Documentation
35+
- Consult CLAUDE.md at project root for further architectural guidance and standard commands.
36+
- Reference README.md and inline docblocks for API documentation style.

‎CLAUDE.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
6+
## Quick commands
7+
8+
- Install dependencies: composer install
9+
- Run unit tests: composer test (runs phpunit)
10+
- Run tests with coverage: composer run test:coverage
11+
- Run static analysis: composer run phpstan (phpstan analyse --memory-limit=1G)
12+
- Run code style checks: composer run cs-fixer:check
13+
- Auto-fix code style: composer run cs-fixer:fix
14+
- Full check: composer run check (runs cs-fixer check, phpstan, and test coverage)
15+
- Lint (style + static analysis): composer run lint
16+
17+
To run a single PHPUnit test (by file):
18+
- ./vendor/bin/phpunit path/to/TestFile.php
19+
20+
To run a single test method:
21+
- ./vendor/bin/phpunit --filter testMethodName path/to/TestFile.php
22+
23+
24+
## Project overview — high level
25+
26+
This repository provides a small PHP SDK for Staffbase plugin Single Sign-On (SSO) token parsing and validation.
27+
28+
High-level structure:
29+
30+
- src/: Core library code. Primary classes:
31+
- src/SSOToken.php — main JWT parsing & validation wrapper for plugin SSO tokens (uses lcobucci/jwt)
32+
- src/SSOTokenGenerator.php — utility to generate test tokens for unit tests
33+
- src/PluginSession.php — session wrapper for persisting SSO data between requests
34+
- src/RemoteCall/* — handlers and interfaces for app-initiated remote calls (delete-instance, etc.)
35+
- src/SSOData/* — data interfaces/traits for shared and SSO specific claims
36+
- src/Exceptions/* — domain exceptions (SSOAuthenticationException, SSOException, ...)
37+
- src/Validation/* — custom validation constraints used by php-jwt/token validation
38+
- src/AbstractToken.php — base token parsing/verification logic used by SSOToken and others
39+
40+
- test/: PHPUnit test suite for the library. Tests instantiate SSOToken, SSOTokenGenerator and validate behavior.
41+
42+
- composer.json: Composer metadata and scripts (lint, phpstan, tests, cs-fixer). Key runtime deps: lcobucci/jwt, lcobucci/clock.
43+
44+
- phpstan.neon.dist: phpstan configuration (analyse src and test at level 4 by default).
45+
46+
- README.md: user-facing documentation and examples (installation, usage examples, remote calls).
47+
48+
49+
## CI and hooks
50+
51+
- GitHub Actions: a workflow badge exists in README, check .github/workflows for exact CI steps if needed.
52+
- 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".
53+
54+
55+
## Notes for future Claude Code instances
56+
57+
- 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.
58+
- When adding or editing PHP code, run CS Fixer and PHPStan locally (composer run fix; composer run phpstan) before running tests.
59+
- Tests are run with phpunit (vendor/bin/phpunit). For debugging a single test, prefer running vendor/bin/phpunit --filter.
60+
61+
Key files to inspect for behavior changes:
62+
- src/SSOToken.php: constructor, token parsing and validation flow
63+
- src/AbstractToken.php: core token parsing/verification logic
64+
- src/Validation/HasInstanceId.php: custom constraint used by SSOToken
65+
- README.md and doc/api.md: user-visible behavior and API
66+
67+
68+
## When editing code
69+
70+
- Prefer editing existing files rather than creating new ones unless a new module is required.
71+
- Follow PSR-4 autoloading in composer.json (namespace Staffbase\plugins\sdk\ -> src/)
72+
- Keep phpstan.neon.dist level consideration in mind
73+
74+
75+
## Contact and references
76+
77+
- Project homepage: https://github.com/Staffbase/plugins-sdk-php
78+
- Composer entry: composer.json
79+

0 commit comments

Comments
 (0)