README

Official PHP client for the public API of e-brocante.enum.fr — the French platform connecting flea-market organizers and stallholders (brocanteurs).

Code quality

✨ Overview

Idiomatic PHP client for the four public read-only endpoints of the e-brocante API:

🎪 Events — list & detail (flea markets, vide-greniers, antique markets, collector fairs)
👥 Organizers — list & profile

The API is free, REST + JSON, and strictly read-only (GET only). All transactional operations (booth reservations, payments, attendance register) live in the e-brocante.enum.fr web app, not in this SDK.

🔗 Site: https://e-brocante.enum.fr 📖 API docs: https://e-brocante.enum.fr/api/doc 🐛 Issues: https://code.e-cosplay.fr/shoko/e-brocante-php/issues

📦 Installation

composer require ecosplay/e-brocante

Or pull from the Gitea Composer registry (private/internal channel — useful when Packagist is unreachable):

{
  "repositories": [
    { "type": "composer", "url": "https://code.e-cosplay.fr/api/packages/shoko/composer" }
  ],
  "require": { "ecosplay/e-brocante": "^1.0" }
}

Or, before the package lands on Packagist, point Composer at the Gitea repository:

{
  "repositories": [
    { "type": "vcs", "url": "https://code.e-cosplay.fr/shoko/e-brocante-php" }
  ],
  "require": { "ecosplay/e-brocante": "^1.0" }
}

Requirements: PHP ≥ 8.3, ext-json, ext-curl, guzzlehttp/guzzle ^7.

🔑 Getting an API key

The API authenticates with two headers:

Header	Meaning
`X-KEY`	Your API key (`eb_prod_…` for live, `eb_test_…` for sandbox)
`X-BROC`	The email of the e-brocante account the call is made for

Step 1 — Create an account on e-brocante.enum.fr

Stallholder → https://e-brocante.enum.fr/register/broc
Organizer → https://e-brocante.enum.fr/register/orga

Step 2 — Generate an API key from your dashboard

Account type	API key page
Stallholder (`ROLE_BROC`)	https://e-brocante.enum.fr/espace-broc/api
Organizer (`ROLE_ORGA`)	https://e-brocante.enum.fr/espace-orga/api

On that page:

Click "Create a key"
Name it (e.g. "Website integration", "Mobile app")
Pick the mode:
- 🟢 Production → eb_prod_… → live data, real production
- 🟡 Test (sandbox) → eb_test_… → fake data (1 fake organizer + 3-7 fake events)
Copy the key — it is shown only once

⚠️ Store the key in environment variables / a secret manager. Never commit it in plain text.

🚀 Quick start

<?php
require 'vendor/autoload.php';

use ECosplay\EBrocante\Client;

$client = new Client(
    apiKey:    $_ENV['EBROCANTE_API_KEY'],   // eb_prod_...
    brocEmail: 'orga@example.com',
    mode:      'prod',
);

$events = $client->events->list([
    'city' => 'paris',
    'from' => '2026-06-01',
    'to'   => '2026-06-30',
]);

foreach ($events as $event) {
    printf("%s — %s on %s\n",
        $event->name,
        $event->city,
        $event->startAt->format('d/m/Y'),
    );
}

More runnable examples in samples/.

🟢 Live vs 🟡 Sandbox

The API offers two strictly separated modes:

Mode	URL prefix	Key prefix	Data	Stripe
🟢 `prod` (live)	`/api/prod/*`	`eb_prod_…`	Real organizers and events	Stripe live
🟡 `test` (sandbox)	`/api/test/*`	`eb_test_…`	Fake (generated on the fly)	Stripe test

Sandbox guarantees

✅ Always exactly 1 organizer in orga.list() (slug: test-orga)
✅ Always between 3 and 7 events in events.list() (deterministic per day)
✅ All events belong to the single test-orga
✅ Same filters / pagination / response shape as live
✅ Same HTTP codes and error structure

$client = new Client(apiKey: 'eb_test_xxx', brocEmail: 'tester@example.com', mode: 'test');

$orgas = $client->orga->list();
assert($orgas->count() === 1);
assert($orgas->data[0]->slug === 'test-orga');

$events = $client->events->list();
assert($events->count() >= 3 && $events->count() <= 7);

💡 Develop and test in mode: 'test' (CI, demos), then flip to mode: 'prod'. Data never crosses between modes.

⚡ Response cache

Responses are cached in-process by default (TTL 5 min). Override at construction time:

use ECosplay\EBrocante\Client;
use ECosplay\EBrocante\Cache\RedisConfig;

// 1️⃣ Local (default — 5 min)
$client = new Client(apiKey: '...', brocEmail: '...');

// 2️⃣ Local with custom TTL
$client = new Client(apiKey: '...', brocEmail: '...', cacheTtl: 3600);

// 3️⃣ Redis (multi-instance)
$client = new Client(
    apiKey:     '...',
    brocEmail:  '...',
    cacheType:  'redis',
    cacheRedis: new RedisConfig(host: 'redis.internal', db: 3),
    cacheTtl:   600,
);

// 4️⃣ Disabled — always fresh
$client = new Client(apiKey: '...', brocEmail: '...', cache: false);

// 5️⃣ One-shot bypass
$events = $client->events->list(['city' => 'paris'], skipCache: true);

// 6️⃣ Manual invalidation
$client->cache->purge();
$client->cache->purgeKey('events.list', ['city' => 'paris']);

🪵 Logging

The SDK emits PSR-3 records around every request, retry, and error. Three ways to wire a sink:

// A) Write JSON-lines log files (one per day) to a directory
$client = new Client(apiKey: '...', brocEmail: '...', logPath: '/var/log/ebrocante');

// B) Plug your own PSR-3 logger (Monolog, Symfony, Laravel, etc.)
$client = new Client(apiKey: '...', brocEmail: '...', logger: $monolog);

// C) Verbose plain-text trace to ./DEBUG.TXT (one line per action)
$client = new Client(apiKey: '...', brocEmail: '...', debug: true);
// or with a custom path
$client = new Client(apiKey: '...', brocEmail: '...', debug: true, debugFile: '/tmp/ebrocante.debug.log');

API keys are automatically redacted from log output.

📡 Available endpoints

The API is read-only — four methods:

SDK method	API endpoint	Description
`$client->events->list($filters)`	`GET /api/{mode}/events`	Paginated list of events (geo / date / category filters)
`$client->events->get($slug)`	`GET /api/{mode}/event/{slug}`	Event detail
`$client->orga->list($filters)`	`GET /api/{mode}/orga`	Paginated list of organizers
`$client->orga->get($slug)`	`GET /api/{mode}/orga/{slug}`	Organizer profile + upcoming events

Both events and orga resources expose an iter() generator that walks every page automatically.

🧪 Bundled mock API server

The package ships a small mock server in tools/mock-api/ that reproduces the four endpoints on http://127.0.0.1:3000. Use it for local development, integration tests, and CI without ever touching production.

composer mock-api                                # starts the server (Bun required)

# In another terminal:
php samples/01-list-events.php                   # hits the mock if EBROCANTE_BASE_URL is set

Point any Client at it via the baseUrl argument:

$client = new Client(
    apiKey:    'eb_mock_dev',
    brocEmail: 'dev@example.com',
    mode:      'prod',
    baseUrl:   'http://127.0.0.1:3000',
);

See tools/mock-api/README.md for fixtures and configuration.

📚 Documentation

Topic	Link
📖 API docs (Swagger)	https://e-brocante.enum.fr/api/doc
📥 OpenAPI 3.1 (JSON)	https://e-brocante.enum.fr/api/doc.json
Runnable examples	`samples/`
Changelog	`CHANGELOG.md`
AI agents policy	`AGENTS.md`

🤖 AI assistants

This SDK is compatible with AI coding assistants (Claude, ChatGPT, Copilot, Cursor, …) for read-only integration help. Modifying or republishing the SDK requires written authorization from the publisher. See AGENTS.md.

📜 License

The SDK is free to use. Redistribution, modification, distributed forks, and derivative works are forbidden without prior written agreement — contact@e-cosplay.fr.

See LICENSE for the full text.

🔗 Useful links

🌸 Platform: https://e-brocante.enum.fr
📖 API docs: https://e-brocante.enum.fr/api/doc
🔐 API keys (stallholder): https://e-brocante.enum.fr/espace-broc/api
🔐 API keys (organizer): https://e-brocante.enum.fr/espace-orga/api
🐛 Issues: https://code.e-cosplay.fr/shoko/e-brocante-php/issues
💬 Contact: contact@e-cosplay.fr
🏢 Publisher: Association E-Cosplay — https://e-cosplay.fr

ecosplay / e-brocante

Maintainers

Package info

Statistics

Security