Laravel Docket Laravel Package

Getting Started

Because laravel-docket is at 0.1.0, treat the first hour as reconnaissance rather than integration. Pre-1.0 releases routinely rename methods between patches, so your goal is to understand the surface area before you wire it into anything that ships.

Start with the install and a read of the service provider:

composer require bjthecod3r/laravel-docket:^0.1.0
php artisan vendor:publish --provider="BJTheCod3r\LaravelDocket\DocketServiceProvider"

Pin the constraint explicitly (^0.1.0, or better 0.1.*) rather than using dev-main. At this version there is no stability guarantee, and a wildcard constraint will silently pull a breaking 0.2.0 into CI.

Where to look first, in this order:

1. src/DocketServiceProvider.php — reveals whether configuration is merged, whether a singleton is bound, and whether a facade alias is registered.
2. config/docket.php (after publishing) — the real contract. Every key here is a behaviour you may need to override per environment.
3. The facade class, if one exists — the docblocks are usually the only accurate API reference at 0.1.0.
4. tests/ in the package source — more reliable than the README for edge-case behaviour on a young release.

First use case: pick a single, non-critical write path — an audit trail on one model, or a record of one background job completing — and run it end to end in a local environment. Confirm the persistence target, the failure mode when the store is unavailable, and whether the write is synchronous. Do not start with anything inside a payment or authorization flow.

Implementation Patterns

Wrap the package behind your own interface. This is the single highest-value pattern at 0.1.0. Define a small contract in your domain — DocketRecorder with one or two methods — and implement it with a thin adapter over the package. When the package renames a method in 0.2.0, you edit one adapter class instead of grepping the codebase.

interface DocketRecorder
{
    public function record(string $event, array $payload = []): void;
}

Register entries from domain events, not controllers. Hook into Laravel's event system and let a listener call your adapter. This keeps the package out of your HTTP layer entirely and means console commands and queued jobs produce the same docket entries for free.

Use it in queued contexts deliberately. If entries are written as part of a job, decide whether a docket failure should fail the job. Wrap the call in try/catch and log, unless the entry is the point of the job. An observability-style package should rarely be the reason a job retries out.

Test with an in-memory or fake target. Check whether the package offers a fake or an in-memory driver; if it does not at 0.1.0, bind your DocketRecorder interface to a spy implementation in tests and assert against that. Never assert on the package's internal storage in feature tests — that couples your suite to a pre-1.0 schema.

Bind per environment. Point the package at a real store in staging and production, and disable it or use a no-op driver in local and test. This is usually a single config key, and it eliminates a class of "tests fail when the docket table is missing" noise.

Integration tip: if the package exposes a middleware or a model trait, prefer the middleware. Traits add a method to every model they touch and are harder to remove later than a route-level middleware or a global listener.

Gotchas and Tips

Pre-1.0 semver is not a promise. Anything below 1.0.0 may break in a patch release. Pin exact or patch-level constraints, and read the diff of every upgrade rather than trusting composer update output. The 0.1.0 release notes are a bare changelog link, which is a signal that subsequent releases may be similarly terse — plan to read the commits yourself.

Config caching bites early. If you publish the config and then change it, remember php artisan config:cache in any environment that caches. A stale cached config on a young package is the most common "it works locally" failure. Clear it after every publish or config edit.

Migrations may not be auto-loaded. Check whether the service provider calls loadMigrationsFrom. If it does not, you will need to publish and run them manually; if it does, be aware that package migrations run on every migrate and can conflict with a table name you already own. Verify the table name before deploying.

Watch for synchronous writes on hot paths. If docket entries are written inline, adding one to a request that runs on every page load will show up in your p95. Move to a queue or sample the entries if the volume is high.

Debugging: when nothing appears to be recorded, check in this order — is the feature enabled in config/docket.php, is the store reachable, is the write inside a transaction that later rolled back, and is the package swallowing exceptions internally. That last one is worth confirming directly in the source, because silent-failure-on-write is common in telemetry-style packages and will cost you an afternoon.

Extension points worth checking for: a driver/contract binding you can swap in AppServiceProvider, a Docket::macro() hook if the class is macroable, and any event the package dispatches on write. Any of these lets you customise behaviour without forking, which matters a great deal when the upstream API is still moving. If none exist, vendor the package under a packages/ path with a path repository so you can patch it locally without waiting on a release.

Upgrade ritual: before bumping, run your test suite against the new version on a branch, and diff the published config file (vendor:publish --force into a temp path) to spot new keys with defaults that differ from your in-repo copy.