SDK PHP (Laravel + Symfony)

Le SDK Pionne pour PHP. Trois usages : standalone, Laravel (auto-detect via service provider), Symfony (event subscriber).

Installation

composer require pionne/pionne

Auto-context

PHP_VERSION — version PHP
php_uname() — OS, hostname
URL de la requête, méthode HTTP, route name
User ID si auth (Laravel Auth::user(), Symfony Security::getUser())

Auto-breadcrumbs

Queries DB (Laravel : via DB::listen(), Symfony : via Doctrine middleware)
Requêtes HTTP sortantes (middleware Guzzle automatique)
Logs Log::info() / error_log()

Frameworks

Le service provider est auto-discover. Configure via env vars :

PIONNE_TOKEN=pio_live_…
PIONNE_ENVIRONMENT=production
PIONNE_RELEASE=1.0.0

Et dans config/services.php :

'pionne' => [
    'token' => env('PIONNE_TOKEN'),
    'environment' => env('PIONNE_ENVIRONMENT', 'production'),
    'release' => env('PIONNE_RELEASE'),
    'sample_rate' => 1.0,
    'scrub_pii' => true,
],

Pour Laravel 11+, hook dans bootstrap/app.php :

use Pionne\Laravel\PionneHandler;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->report(function (Throwable $e) {
            PionneHandler::report($e);
        });
    })->create();

Pour Laravel 10 et avant, dans App\Exceptions\Handler :

use Pionne\Pionne;

public function report(Throwable $e): void
{
    Pionne::captureException($e);
    parent::report($e);
}

Les jobs de queue sont auto-instrumentés — toute exception non gérée dans un Job est capturée.

Active le bundle dans config/bundles.php :

return [
    // ...
    Pionne\Symfony\PionneBundle::class => ['all' => true],
];

Configure dans config/packages/pionne.yaml :

pionne:
  token: '%env(PIONNE_TOKEN)%'
  environment: '%env(PIONNE_ENVIRONMENT)%'
  release: '%env(PIONNE_RELEASE)%'
  sample_rate: 1.0
  scrub_pii: true

Et dans .env :

PIONNE_TOKEN=pio_live_…
PIONNE_ENVIRONMENT=production
PIONNE_RELEASE=1.0.0

Le bundle enregistre automatiquement un EventSubscriber sur KernelEvents::EXCEPTION. Les messages Symfony Messenger sont aussi auto-instrumentés.

<?php
require_once __DIR__ . '/vendor/autoload.php';

use Pionne\Pionne;

Pionne::init([
    'token' => 'pio_live_…',
    'environment' => 'production',
    'release' => '1.0.0',
]);

try {
    doSomething();
} catch (\Throwable $e) {
    Pionne::captureException($e);
}

API

Pionne::init(['token' => '…', 'environment' => '…']);
Pionne::captureException($e, ['tags' => ['feature' => 'checkout']]);
Pionne::captureMessage('Cache miss', ['level' => 'warning']);
Pionne::setUser(['id' => 'user_42']);
Pionne::setTags(['region' => 'eu-west-1']);
Pionne::setEnabled(false);
Pionne::addBreadcrumb(['category' => 'db', 'message' => 'SELECT ...']);

Queue jobs

Laravel queue : auto-instrumenté (events JobFailed)
Symfony Messenger : auto-instrumenté (subscriber sur WorkerMessageFailedEvent)
Custom worker : wrap manuellement

try {
    $job->handle();
} catch (\Throwable $e) {
    Pionne::captureException($e, [
        'tags' => ['job' => get_class($job)],
        'contexts' => ['job' => ['attempts' => $job->attempts()]],
    ]);
    throw $e;
}

Géographie (opt-in)

Pionne peut résoudre la ville/région/pays approximatif du serveur et l’attacher à chaque event sous contexts.geo — comme Sentry. Désactivé par défaut pour la vie privée.

Pionne::init([
    'token' => 'pio_live_…',
    'sendGeography' => true, // ← opt-in
]);

Pour Laravel, un simple flag dans .env suffit (le service provider le passe à init()) :

PIONNE_GEOGRAPHY=true

Au boot, un seul appel cURL vers https://ipapi.co/json/ (timeout 4 s) attache contexts.geo = { city, region, country, country_code } à tous les events suivants. Si le lookup échoue (firewall sortant, rate-limit), le SDK continue silencieusement sans géo. Pour un fournisseur custom : 'geographyEndpoint' => 'https://geo.tonapi.com/'.

Sur un cluster auto-scalé, préfère mettre la région du conteneur en tag ('tags' => ['region' => getenv('AWS_REGION')]) plutôt qu’un lookup IP.

Anti-token-theft

Le pinning de Bundle ID est mobile uniquement (iOS/Android/RN/Flutter) — il protège contre la décompilation d’un APK/IPA. Sur Laravel/Symfony, ton token vit dans .env (gitignored) ou dans un secrets manager : il n’est jamais shippé à un client, donc la menace n’existe pas.

Le champ “Bundle ID” est masqué dans l’app mobile pour les projets Laravel/Symfony — le remplir manuellement causerait un 403 sur 100 % des events (le SDK n’envoie pas de app_id). Pour distinguer plusieurs déploiements, utilise les tags :

Pionne::init([
    'token' => env('PIONNE_TOKEN'),
    'tags'  => [
        'deployment' => env('APP_DEPLOYMENT', 'prod'),
        'region'     => env('AWS_REGION', 'eu-west-3'),
    ],
]);

Plus de détails : Bundle ID Pinning → Backends sans bundle_id.

Voir aussi

Index des SDKs — tous les SDKs Pionne
API Ingest — protocole HTTP brut