Initial version by marcospassos · Pull Request #1 · croct-tech/plug-php

marcospassos · 2026-06-03T18:29:15Z

Summary

Add initial implementation.

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
I have added tests that prove my fix is effective or that my feature works
New and existing unit tests pass locally with my changes
Any dependent changes have been merged and published in downstream modules
I have checked my code and corrected any misspellings

Copilot

Pull request overview

Introduces the initial implementation of the Croct “Plug” PHP SDK, including visitor identity/session management, token issuance/signing, PSR-based HTTP transport, and content/query APIs, along with a comprehensive PHPUnit test suite and updated package/CI/documentation scaffolding.

Changes:

Add core SDK implementation (tokens, sessions, request context, API client, evaluator/content fetcher, cookie storage/configuration, and varying-response observer).
Add PHPUnit tests covering identity handling, JWT/token behavior, API requests, cookie behavior, and metadata parsing.
Update project metadata and tooling (Composer package details, coding standards, PHPStan/PHPCS, GitHub Actions workflow, README, and license).

Reviewed changes

Copilot reviewed 70 out of 77 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/VaryingResponseObserverTest.php	Tests callback invocation behavior of the varying-response decorator.
tests/UuidTest.php	Tests UUID generation, validation, parsing, and equality.
tests/TokenTest.php	Tests token issuance, parsing, validity, signing, and error cases.
tests/SessionTest.php	Tests session-driven client ID/token lifecycle and signing behavior.
tests/RequestContextTest.php	Tests request context extraction from globals and PSR-7 requests.
tests/PsrApiClientTest.php	Tests request construction, headers, and error mapping in the API client.
tests/InMemoryIdentityStoreTest.php	Tests in-memory persistence of client ID and user token.
tests/HttpEvaluatorTest.php	Tests evaluator payload construction and exception/fallback behavior.
tests/HttpContentFetcherTest.php	Tests content fetch payloads, endpoint selection, and fallbacks.
tests/Fixtures/InstalledContentProvider.php	Fixture content provider used in discovery tests.
tests/FetchResponseTest.php	Tests response parsing and metadata handling.
tests/FetchOptionsTest.php	Tests fetch options fluent API and immutability.
tests/Exception/ApiExceptionTest.php	Tests API exception construction from problem/transport errors.
tests/EvaluationOptionsTest.php	Tests evaluation options fluent API and immutability.
tests/EcKeyFactory.php	Test utility for generating/verifying ES256 signatures.
tests/CroctTest.php	End-to-end wiring tests for the main SDK entry point.
tests/CookieTest.php	Tests cookie model serialization and attribute exposure.
tests/CookieStorageTest.php	Tests cookie-backed identity storage and emission behavior.
tests/CookieConfigurationTest.php	Tests cookie configuration defaults and browser-cookie mapping.
tests/Content/SlotMetadataTest.php	Tests slot metadata parsing/validation.
tests/Content/NullContentProviderTest.php	Tests null content provider behavior.
tests/Content/ExperimentMetadataTest.php	Tests experiment metadata parsing/validation.
tests/Content/ExperienceMetadataTest.php	Tests experience metadata parsing/validation.
tests/Content/ArrayContentProviderTest.php	Tests array-backed content provider behavior.
tests/ApiKeyTest.php	Tests API key parsing, validation, signing, and export/redaction.
tests/.gitkeep	Keeps `tests/` tracked.
src/VaryingResponseObserver.php	Decorator to signal when responses vary per visitor.
src/Uuid.php	UUID value object with v4 generation and parsing/validation helpers.
src/Token.php	Visitor JWT model: issue/parse/sign/validate and claim accessors.
src/Session.php	Identity/session manager: client ID + token reissue/upgrade/signing.
src/RequestContext.php	Request-derived context (URL/referrer/IP/UA/locale) and evaluation context builder.
src/PsrApiClient.php	PSR-18/PSR-17 API transport with auth/context headers and error mapping.
src/Plug.php	Public SDK interface for identity, evaluation, and content fetching.
src/InMemoryIdentityStore.php	Simple in-memory identity persistence implementation.
src/IdentityStore.php	Identity persistence abstraction.
src/HttpHeader.php	Enum of SDK HTTP headers.
src/HttpEvaluator.php	API-backed CQL evaluator with fallback/exception translation.
src/HttpContentFetcher.php	API-backed content fetcher with endpoint switching and fallbacks.
src/FetchResponse.php	Slot fetch response wrapper with optional metadata.
src/FetchOptions.php	Immutable options for content fetching.
src/Exception/MalformedTokenException.php	Exception type for token parsing/corruption.
src/Exception/EvaluationException.php	Exception type for evaluation failures.
src/Exception/CroctException.php	Marker interface for SDK-thrown exceptions.
src/Exception/ContentException.php	Exception type for content fetching failures.
src/Exception/ConfigurationException.php	Exception type for invalid configuration.
src/Exception/ApiException.php	Exception type for transport/API-level failures.
src/Evaluator.php	Evaluator abstraction.
src/EvaluationOptions.php	Immutable options for query evaluation.
src/Croct.php	Main SDK entry point/wiring with discovery defaults.
src/CookieStorage.php	Cookie-backed identity store with response cookie emission support.
src/CookieConfiguration.php	Cookie names/lifetimes/attributes + browser cookie mapping.
src/Cookie.php	Cookie value object + Set-Cookie header rendering.
src/ContentFetcher.php	Content fetcher abstraction.
src/Content/SlotMetadata.php	Slot metadata model and parsing/validation.
src/Content/NullContentProvider.php	Null provider fallback (no generated content).
src/Content/ExperimentMetadata.php	Experiment metadata model and parsing/validation.
src/Content/ExperienceMetadata.php	Experience metadata model and parsing/validation.
src/Content/ContentSource.php	Enum describing the source of served content.
src/Content/ContentProvider.php	Content provider abstraction.
src/Content/ArrayContentProvider.php	Array-backed content provider implementation.
src/ApiKey.php	API key model including optional private key and ES256 signing.
src/ApiClient.php	API client abstraction.
src/.gitkeep	Keeps `src/` tracked.
README.md	Updates README to product-specific SDK introduction and links.
phpunit.xml.dist	Renames test suite for the SDK.
phpstan.neon.dist	Adjusts PHPStan configuration (checked exceptions list, etc.).
phpcs.xml.dist	Updates coding standard paths and adds targeted exclusions.
LICENSE	Adds MIT license text.
composer.json	Converts template package into `croct/plug-php` with runtime/test dependencies and scripts.
.github/workflows/validate-branch.yaml	Adds reusable workflow-based validation.
.github/workflows/release-drafter.yaml	Removes release drafter workflow from template.
.github/workflows/branch-validations.yaml	Removes legacy in-repo validation workflow.
.github/assets/header-light.svg	Adds README header asset (light).
.github/assets/header-light-mobile.svg	Adds README header asset (light mobile).
.github/assets/header-dark.svg	Adds README header asset (dark).
.github/assets/header-dark-mobile.svg	Adds README header asset (dark mobile).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

denis-rossati

LGTM aside from Renan's review

Copilot

Pull request overview

Copilot reviewed 78 out of 85 changed files in this pull request and generated 5 comments.

+            $options = [
+                'expires' => $cookie->getExpiration() ?? 0,
+                'path' => $cookie->getPath(),
+                'domain' => $cookie->getDomain() ?? '',
+                'secure' => $cookie->isSecure(),
+                'httponly' => $cookie->isHttpOnly(),
+            ];


renan628 · 2026-06-09T13:30:35Z

+    /**
+     * Headers that must not be forwarded upstream.
+     */
+    private const UNFORWARDED_REQUEST_HEADERS = [


Cookie and Authorization should be here?

I don't think so. It should forward whenever we get as the script would get that.

# Conflicts: # composer.json

HttpEvaluator uses mb_strlen() and CroctScriptProvider/ApiKey use hash(), so declare ext-mbstring and ext-hash as runtime requirements to prevent incompatible installs. Addresses PR review feedback. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Validate the preserved token ID when re-signing a token issued under a different key. Token::parse() does not validate the "jti" claim, so a tampered cookie carrying a non-UUID token ID would make withTokenId() throw and break session resolution; fall back to a fresh UUID instead. Also save and restore $_SERVER/$_GET/$_COOKIE in the request/cookie tests so they no longer leak superglobal state across the suite. Addresses PR review feedback. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

marcospassos requested a review from Copilot June 3, 2026 18:29

marcospassos added the feature New feature label Jun 3, 2026

Copilot started reviewing on behalf of marcospassos June 3, 2026 18:29 View session

Copilot AI reviewed Jun 3, 2026

View reviewed changes

Comment thread src/Session.php Outdated

Comment thread src/Token.php

Comment thread src/Cookie.php Outdated

Comment thread README.md Outdated

marcospassos force-pushed the initial-version branch from caeb118 to f3d36c9 Compare June 3, 2026 20:50

Update workflow

7318276

marcospassos force-pushed the initial-version branch from 8828ae9 to 7318276 Compare June 3, 2026 21:29

renan628 reviewed Jun 3, 2026

View reviewed changes

Comment thread src/HttpContentFetcher.php Outdated

Comment thread src/RequestContext.php Outdated

Comment thread src/HttpEvaluator.php

Comment thread src/RequestContext.php Outdated

Comment thread src/PsrApiClient.php Outdated

denis-rossati approved these changes Jun 4, 2026

View reviewed changes

marcospassos added 3 commits June 4, 2026 13:59

Apply review

6655a87

Update badges

abcbc2c

Update badges

d5a82c9

marcospassos requested review from Fryuni and renan628 June 4, 2026 19:37

renan628 approved these changes Jun 5, 2026

View reviewed changes

marcospassos added 2 commits June 5, 2026 11:41

Make get options static

dfdf608

Add abstrations

db1a74c

denis-rossati reviewed Jun 8, 2026

View reviewed changes

Comment thread composer.json

Wip

9629976

Fryuni approved these changes Jun 8, 2026

View reviewed changes

Wip

e22f328

marcospassos requested review from Fryuni, Copilot, denis-rossati and renan628 June 8, 2026 21:25

Copilot started reviewing on behalf of marcospassos June 8, 2026 21:25 View session

Copilot AI reviewed Jun 8, 2026

View reviewed changes

renan628 approved these changes Jun 9, 2026

View reviewed changes

renan628 reviewed Jun 9, 2026

View reviewed changes

denis-rossati approved these changes Jun 9, 2026

View reviewed changes

marcospassos and others added 5 commits June 9, 2026 12:21

Merge remote-tracking branch 'origin/master' into initial-version

cf82e21

# Conflicts: # composer.json

Wip

6a1500d

Add PHP Stan and Psalm plugins

5c9ad81

renan628 approved these changes Jun 9, 2026

View reviewed changes

Add test for plugin

44ddd6c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial version#1

Initial version#1
marcospassos wants to merge 14 commits into
masterfrom
initial-version

marcospassos commented Jun 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

denis-rossati left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

renan628 Jun 9, 2026

Uh oh!

marcospassos Jun 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

marcospassos commented Jun 3, 2026

Summary

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

denis-rossati left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

renan628 Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

marcospassos Jun 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants