CLAUDE

CLAUDE.md — PHP SDK Wiki

This directory is the published, public wiki for the PHP SDK. It contains two categories of pages.

Shared Docs vs PHP-Specific Docs

• Shared docs (lowercase-hyphenated filenames, e.g. rule-evaluation.md, data-management.md, segments.md, bucketing-algorithm.md, and everything listed under "Core Concepts (Shared)" / "How-To Guides (Shared)" in AI_Index.md) — Do not edit these files here. They are synced automatically from a canonical source in a private backend repo (path within that repo: public/js/tracking/full-stack-docs/, with concepts/ and guides/ subdirs). The same files also appear in the JS SDK wiki. Any edit made here will be overwritten on the next sync.

• PHP-specific docs (CamelCase filenames, e.g. Quickstart.md, Installation.md, Initialization.md, Configuration.md, ReturnTypes.md, CodeExamples.md, SegmentsManager.md, Testing.md) — These are PHP-only and are edited directly in this wiki.

Decision Rule Before Editing Anything

1. Check the filename.
   • Lowercase-hyphenated → shared → edit the canonical source in the backend repo (public/js/tracking/full-stack-docs/) instead.
   • CamelCase → PHP-specific → edit here.
2. AI_Index.md and this CLAUDE.md are wiki-specific and edited here.

Writing Rules for Shared Docs (Public Audience)

This wiki is public. The JS SDK wiki is also public. The backend wiki and the backend repo are private. When editing any shared doc at its canonical source (in the backend repo, under public/js/tracking/full-stack-docs/):

1. Never reference the private backend wiki or any private repo. No links to backend.wiki/*, no "see the backend wiki for details." If the content is needed, inline it; otherwise omit.
2. Never reference internal backend filesystem paths (backend/public/..., backend/apiDoc/..., backend/src/..., etc.) — readers don't have that tree. Use package names (@convertcom/js-sdk-data, @convertcom/js-sdk-types, @convertcom/js-sdk-rules, and their PHP equivalents) and class/method names. For public specs, link to a known-valid URL (e.g. https://api.convert.com/doc/v2/...).
3. Never invent URLs — and never write a link to a page in THIS wiki as a full URL. Guessed GitHub wiki URLs are a common failure: org, repo, slug and casing are all easy to get wrong. Link to another page here by bare page name — [RuleManager](rule-evaluation), [Configuration](Configuration), anchors included ([Configuration](Configuration#retries)). GitHub resolves a bare name against the wiki it is rendering, so it looks and behaves exactly like the full URL for a reader on github.com, and it cannot carry a wrong org or repo because it names neither. It is also the only form that works for a reader inside a Claude session: this wiki ships inside the Convert Claude plugin as a read-only mirror, and a skill's link table routes an absolute URL to "external" — so the page sitting on disk beside it is never opened, and for the wikis whose source repo is private the fallback fetch returns 404. Only a link to a different wiki stays absolute (https://github.com/convertcom/<repo>/wiki/<Page>), because there a bare name would resolve inside this wiki and land on the wrong page. If you do not know an external URL is correct, do not write it.
4. Prefer package-level references over file paths and line numbers. js-sdk-data -> DataManager::matchRulesByField ages better than packages/data/src/DataManager.php:366-370.

The canonical source directory has its own CLAUDE.md restating these rules for anyone editing in place.