AI_Index

PHP SDK Wiki — AI Agent Index

This index helps AI agents find the right documentation page without reading the entire wiki. Read this file first, then load only the specific pages relevant to your task.

Page Origin

This wiki contains two types of pages:

• Shared docs (lowercase-hyphenated filenames) — Synced from the canonical source in the backend repo at backend/public/js/tracking/full-stack-docs/ (concepts/ and guides/ subdirs). These cover cross-SDK concepts and are identical across the JS and PHP SDK wikis. Do not edit them here — edits will be overwritten on the next sync.
• PHP-specific docs (CamelCase filenames) — Written for this SDK only: quickstart, installation, configuration, return types, code examples, segments manager, testing.

Getting Started

Page	When to read
How Convert Works	High-level overview of the Convert platform and SDKs
Architecture Overview	System architecture, module relationships, data flow
Data Model Reference	Entity relationships: Experience, Variation, Feature, Variable, Goal, Audience, Location
Quickstart Overview	Cross-SDK quickstart concepts before diving into PHP-specific setup
Requirements & Constraints	SDK limitations, environment requirements, known constraints

PHP SDK Reference

Page	When to read
Quickstart	Step-by-step PHP setup and first experiment
Installation	Install via Composer with PSR dependencies
Initialization	ConvertSDK::create() factory, synchronous init, PSR discovery
Configuration Options	Full SDK config reference with PSR integration
Return Types & DTOs	PHP readonly DTOs (BucketedVariation, BucketedFeature) and backed enums (FeatureStatus, RuleError, LogLevel, SegmentsKeys, ConversionSettingKey, RuleType)
Code Examples	Complete PHP examples for all SDK methods, including setPreview() and event subscription
Segments Manager	PHP-specific segment evaluation, custom segments, default reporting segments

Core Concepts (Shared)

Page	When to read
Experiences & Variations	A/B test structure, variation assignment, activation
Feature Flags	Feature flag evaluation, variable values, feature status
Bucketing Algorithm	Hash-based visitor assignment, traffic allocation, deterministic bucketing
Rule Evaluation & Targeting	Audience matching, location matching, scheduling rules
Segments	Visitor segmentation logic and custom segments
Data Management	Data access layer, project config, entity lookups
Event System	Event pub/sub, lifecycle hooks, custom events
API Communication & Tracking	HTTP communication, config fetching, event tracking, queue management

How-To Guides (Shared)

Page	When to read
Running Experiences	End-to-end guide: activate experiments, get variations for a visitor
Running Features	Feature flag usage: evaluate flags, get variable values
Tracking Conversions	Goal tracking, conversion events, revenue tracking
Visitor Context & Properties	Visitor identification, custom properties, cross-session persistence
Persistent DataStore	Custom data store integration for visitor state persistence
QA & Preview	Debug tokens (draft/paused configs) and zero-trace preview links — pairs with setPreview()
Mutually Exclusive Experiments	The bucketed_into_experience_key audience rule, ordering, and persistence requirements
Server-Side Experimentation	Bucketing and conversion patterns for server-capable SDKs
From Tracking Script to SDK	Mapping Convert UI audience, location, and goal concepts to SDK calls
Direct Tracking Endpoint	Calling /v1/track without an SDK — including the ConvertAgent/ User-Agent requirement
Troubleshooting	Common issues, debugging techniques, diagnostic steps

Contributing

Page	When to read
Testing	PHPUnit setup, cross-SDK parity tests, static analysis

PHP-Specific Notes

Topic	Key difference from JS SDK
Initialization	ConvertSDK::create($config) — static factory, synchronous
HTTP	PSR-18 client, auto-discovered via php-http/discovery
Caching	PSR-16 cache serves dual purpose: config caching + visitor data persistence
Logging	PSR-3 LoggerInterface; LogLevel is an int-backed enum (Trace=0 … Silent=5)
Queue flush	register_shutdown_function — no setTimeout/timers
Return types	Readonly DTOs (BucketedVariation, BucketedFeature) and backed enums
Data persistence	PSR-16 cache automatically wired as DataStore (no DataStoreManager queue)
Event subscription	Core::on() takes a string — pass SystemEvents::Ready->value, not the enum (EventManager::on() accepts either)
Preview	$context->setPreview($experienceId, $variationId) + PreviewParam::parse(); synchronous, no await
User-Agent	Every request is sent as ConvertAgent/1.0, applied last so it cannot be overridden

Module Dependency Map

ConvertSDK::create()
  ├── creates → Core
  ├── auto-discovers → PSR-18 HTTP Client
  ├── wires → PSR-16 Cache as DataStore
  └── registers → shutdown handler for queue flush
Core
  ├── creates → Context
  ├── fetches config via → ApiManager
  ├── fires events via → EventManager
  └── uses → DataManager
Context
  ├── runs experiments via → ExperienceManager
  ├── runs features via → FeatureManager
  ├── accesses data via → DataManager
  ├── evaluates segments via → SegmentsManager
  ├── resolves preview targets via → PreviewResolver
  └── releases queues via → ApiManager
DataManager
  ├── buckets via → BucketingManager
  ├── matches rules via → RuleManager
  ├── enqueues tracking via → ApiManager
  └── fires events via → EventManager
PreviewResolver
  ├── looks up in-config experiences via → DataManager
  └── fetches absent ones via → ApiManager::getConfigForExperience()  (?exp=, 60s memoized)