Save this content to: AGENTS.md

# beem-php — Agent Guide

Core Beem SDK for PHP. Framework-agnostic, zero runtime dependencies (only `ext-json` and `ext-curl`).

## Important: read-only mirror

This repository is an automated split of the Beem monorepo (`sdks/php/beem-php`). Do not push here — changes land in the monorepo and are mirrored on every push to `main`. If you are editing this checkout directly, your changes will be lost on the next sync.

## Layout

```
src/
  Beem.php               # Static facade — the public entry point (init, startTransaction, captureException, flush)
  Client.php             # Holds config + transport, buffers events, owns the current transaction
  Configuration.php      # Validates and normalizes init() options
  Dsn.php                # Parses DSN strings (https://<public_key>@<host>/<project>)
  Transaction.php        # A traced unit of work; creates Spans
  Span.php               # A timed operation inside a Transaction
  ExceptionCapture.php   # Converts Throwables into event payloads
  Transport/
    Transport.php        # Transport interface
    HttpTransport.php    # curl-based batch sender with shutdown flush
tests/                   # Pest tests
```

## Commands

```bash
composer install
composer test      # Pest
composer analyse   # PHPStan level 6
composer cs:check  # php-cs-fixer (dry-run)
composer cs:fix    # php-cs-fixer
```

## Conventions

- PHP 8.2+, `declare(strict_types=1)` in every file, PSR-4 under `Beem\`.
- No runtime composer dependencies — keep the core dependency-free; framework glue belongs in beem-symfony / beem-laravel.
- All code, comments, and commit messages in English. Commits follow Conventional Commits (`feat:`, `fix:`, `chore:`…).
- Every behavior change needs a Pest test and must pass PHPStan level 6.
- Events are buffered in-process; flushing happens on `flush()`, full batch, or shutdown. Preserve that contract — consumers rely on shutdown flush.