Event Hub Php Sdk Laravel Package

Getting Started

Install

composer require northwestern-sysdev/event-hub-php-sdk

This is an internal Northwestern (NIT Administrative Systems) SDK with no dependents and no meaningful public adoption. Before you build on it, confirm how your team is expected to consume it — it may be distributed via a private Composer repository / VCS entry rather than Packagist:

"repositories": [
  { "type": "vcs", "url": "https://github.com/NIT-Administrative-Systems/SysDev-EventHub-PHP-SDK" }
]

Pin an explicit version ("northwestern-sysdev/event-hub-php-sdk": "1.x" or a commit hash) from day one; there is no ecosystem pressure to keep this semver-clean.

Where to look first

1. README.md — likely the only prose documentation. Expect it to describe connection config + a publish call.
2. composer.json — required PHP version, PSR-4 namespace, and transitive deps (the HTTP or Kafka client it wraps tells you the delivery model).
3. src/ — find the main client/producer class and its constructor. That constructor is the config surface.
4. tests/ — the fastest source of real usage examples if the README is thin.
5. Any config/ or *.example / .env.example shipped in the repo.

Minimal first use case

The canonical job for this SDK is: publish a domain event from a Laravel service to Northwestern's EventHub after a state change is committed. Start with one low-risk event — e.g. user.profile.updated fired from a single service method — so you can validate connectivity, auth, and payload shape without coupling the whole app.

Practical first steps:

php artisan vendor:publish --provider="...EventHubServiceProvider"

(Verify the provider FQCN and publish tag against src/ — do not assume a --tag exists.)

Then set broker/credential values in .env and write a throwaway artisan command (php artisan eventhub:ping) that constructs the client, publishes a single test event, and prints the result. Getting that green end-to-end in a sandbox environment is the real "hello world" here; nothing else matters until connectivity and auth are proven.

Implementation Patterns

Bind the client as a singleton. Construct the SDK client once in a service provider from config('eventhub.*') and resolve it via the container. Do not new it inside controllers or jobs — connections and auth handshakes are expensive and Octane/queue workers will punish you for it.

$this->app->singleton(EventHubClient::class, fn ($app) => new EventHubClient(
    config('eventhub.endpoint'),
    config('eventhub.credentials'),
    // ...
));

Wrap it behind your own interface. This is the single highest-value pattern given the SDK's maturity. Define App\Contracts\EventPublisher with publish(DomainEvent $event): void, implement it with the SDK, and never let the SDK type leak into your domain code. Swapping transports later (or faking in tests) becomes a one-line binding change.

Publish after commit, never inside the transaction. A publish that succeeds while the DB transaction later rolls back produces a phantom event downstream. Use DB::afterCommit(fn () => ...) or dispatch a queued listener from a model event.

Queue the publish. Anything that talks to a broker over the network does not belong in the request/response cycle. Pattern:

• Service commits the change and dispatches a PublishDomainEvent job.
• Job implements ShouldQueue, with $tries, $backoff, and a failed() handler that logs and alerts.
• Include a stable event_id / idempotency key in the payload so consumers can dedupe.

Outbox pattern for anything important. If losing an event is unacceptable, write the serialized event to an outbox_events table in the same transaction as the business change, then have a scheduled command or dedicated queue worker drain and publish it. This is the only robust answer to "the broker was down for six minutes."

Standardize the envelope. Pick one shape and enforce it centrally in your EventPublisher implementation: event_id, event_type (domain.entity.action), schema_version, occurred_at, correlation_id, producer (app name + env), payload. Doing this at the boundary means individual call sites stay trivial and downstream consumers get a uniform contract.

Per-environment topics. Derive topic names from app()->environment() (e.g. dev.orders.order.created) rather than hardcoding. Never let a staging deploy publish into a production topic — this is the single most common way an EventHub integration causes an incident.

Testing pattern. Bind a RecordingEventPublisher (an array of published events) in TestCase::setUp(). Assert on $publisher->published() rather than on broker state. CI should never contact a real broker; if the SDK offers a test/fake mode, treat it as a bonus, not a substitute for your own boundary fake.

Integration tips. Register a health check that verifies the publisher is resolvable and (optionally) that the broker is reachable, so deploys fail fast rather than at first publish. Keep JSON schemas for your events in the repo and validate payloads before they reach the SDK — schema errors are far cheaper to debug on your side.

Gotchas and Tips

Zero stars, zero dependents, thin docs. Treat the source as the specification. Before relying on any behaviour (retry policy, serialization format, default timeout), read the actual implementation. Budget time for that reading; do not infer semantics from method names.

Config caching will bite you. If the SDK reads env() directly rather than through config(), php artisan config:cache in production will silently yield null credentials. Grep the SDK source for getenv / env( and, if present, move those values into a published config file and pass them explicitly to the constructor.

Synchronous publish on the request path adds broker latency to your p95. If the SDK blocks, a slow or partitioned broker becomes a slow Laravel app. Set explicit timeouts and, if the SDK exposes them, low retry counts — a fast failure you can queue beats a 30-second hang.

At-least-once is the realistic default. Assume duplicates and design consumers to be idempotent on event_id. Assume reordering is possible unless you are deliberately setting a partition key (typically the aggregate/entity id) and have verified the SDK forwards it.

Errors get swallowed in fire-and-forget wrappers. Confirm whether the SDK throws on publish failure or returns a falsey result. If it returns a result object, check it — code that ignores the return value is the number-one source of "we thought we were publishing events for three weeks."

Large payloads fail, and usually unhelpfully. Keep events small: ids plus the fields consumers need, not whole Eloquent models. Serializing a model with loaded relations is a common way to blow a size limit and also leaks internal schema to consumers.

Octane and long-lived workers. A singleton client held across Octane requests or a long-running queue worker may hold a stale connection. Look for a reconnect/health mechanism, or bind the client as scoped if the SDK is not connection-safe. Add a supervisor restart policy for queue workers as a cheap safety net.

Credential rotation and secrets. Broker credentials likely expire. Store them in your secret manager, surface rotation failures as explicit startup errors, and never commit the SDK's sample credential files. A silent auth failure at 2 a.m. is the worst failure mode for an event pipeline.

Version pinning and upgrades. With no community to catch regressions, read git log / tags before bumping and run your integration test against the sandbox environment. Consider vendoring a fork if you need a patch the maintainers won't ship quickly.

Extension points worth checking. Look for an injectable logger/PSR-3 logger, a custom serializer or message transformer, and middleware/interceptor hooks. If a serializer hook exists, use it for your envelope rather than hand-building payloads at every call site; if not, that is your strongest argument for wrapping the SDK behind your own interface.

Debugging checklist when a publish silently disappears: (1) is config('eventhub.*') actually populated after config:cache? (2) is the environment/topic mapping correct? (3) did the transaction commit? (4) is the job being retried and then discarded by $tries exhaustion? (5) is the consumer group or subscription actually attached on the other end? Log at the publish boundary with event_id and event_type so you can answer all five from one grep.