Performist Bundle Laravel Package

Getting Started

Start by confirming the package version and reading the v1.3.0 release section plus the README section on context objects and custom attributes. The release is additive, so existing context usage should continue to work; the first thing to inspect is how the package exposes attribute reads/writes on a context object (methods, array access, or a facade).

Minimal setup:

1. Update the dependency:

   composer require <vendor>/<package>:^1.3
   

2. Publish/refresh config only if the package documents config changes for v1.3.0:

   php artisan vendor:publish --tag=<package>-config
   php artisan config:clear
   

3. Open the package’s context class or facade and look for the new custom-attribute API. Confirm whether attributes are set via a method such as withAttribute(), put(), or array access, and whether reads are get()/property access.

First use case: attach request-scoped metadata to the context in middleware, then read it from a log processor or queued job. For example, set a tenant ID or correlation ID on the context during the request, and include it in structured logs without passing it through every service method.

Implementation Patterns

Use context attributes for cross-cutting request metadata rather than domain data. Good candidates are tenant IDs, trace/correlation IDs, feature-flag snapshots, locale, actor IDs, and integration request identifiers. Domain entities and large payloads belong in services/models, not context attributes.

Common workflows:

• Middleware hydration: Build or enrich the context early in the request lifecycle. Set attributes once and read them downstream. Keep middleware small and avoid doing expensive resolution there.
• Job and queue propagation: If the package serializes context into jobs, use attributes to carry trace IDs and tenant IDs into queued work. Rehydrate deliberately in handle() rather than assuming the full request context exists.
• Logging integration: Add selected attributes to Laravel’s log context so every log line carries request metadata. Prefer a small, stable set of keys rather than dumping the whole context.
• Service-layer access: Inject or resolve the context where needed, but avoid making every class depend on it. Use it at boundaries: controllers, middleware, jobs, and infrastructure concerns.
• Testing: Assert attribute values after exercising middleware or actions. If the package provides a fake or test helper for context, use it; otherwise clear context between tests to avoid leakage.

Integration tips:

• If the package wraps Laravel’s Context facade, align custom attribute names with existing Context::add() usage to avoid two parallel metadata systems.
• Keep attribute keys namespaced, e.g. tenant.id, trace.id, to reduce collisions with package internals or future attributes.
• Treat the context as read-mostly after the request enters the application layer. Mutating it deep in domain code makes debugging harder.
• For long-running workers, explicitly reset or rebuild context per job/request if the package does not do so automatically.

Gotchas and Tips

• Additive release, but verify merge semantics: v1.3.0 adds custom attribute management. Confirm whether setting an existing key replaces or merges the value, especially for array attributes.
• Serialization limits: Context is often serialized into logs, jobs, or traces. Avoid storing closures, models, large arrays, or sensitive values. Prefer scalars and small arrays.
• Long-running processes: Under Octane, queue workers, or other long-lived processes, stale attributes can leak between requests/jobs. Clear or rebuild context at the start of each unit of work.
• Config caching: After updating, run php artisan config:clear and re-cache in deployment. If the new attribute behavior is configurable, test with cached config enabled.
• Debugging: If attributes are not visible downstream, check the order of middleware, whether context was rebuilt after your middleware ran, and whether the package resets context during request termination.
• Key hygiene: Use consistent, documented attribute keys. Avoid ad hoc keys scattered across the codebase; centralize constants or helper methods.
• Sensitive data: Context attributes frequently end up in exception trackers and logs. Do not place tokens, passwords, or full request payloads in context.
• Extension points: Look for documented ways to register attribute resolvers, formatters, or context decorators. If none exist, wrap context access in a small application service rather than coupling directly to package internals.
• Upgrade check: Although v1.3.0 appears non-breaking, run the test suite and verify any custom context serialization or logging integrations after upgrading.