Normalizer Extension Bundle Laravel Package

Getting Started

1. Require the package via Composer and publish any config if the service provider exposes one.
2. Open AbstractBatch and any existing batch classes first. The v4 change is centered on the CACHE_LIFETIME constant there.
3. Decide per batch whether caching is useful. Set CACHE_LIFETIME to a positive number of seconds to cache; set it to null to disable caching entirely.
4. First use case: create a small batch class extending AbstractBatch, run it locally with CACHE_LIFETIME = null, verify the batch lifecycle, then enable caching for a read-heavy status/dashboard path.

Implementation Patterns

• Per-batch caching policy: Override CACHE_LIFETIME in each concrete batch class. Use short lifetimes for volatile batches and longer lifetimes for expensive, mostly-read batch summaries.
• Disable cache in development and tests: Set CACHE_LIFETIME = null in local/test environments to avoid stale state between runs. This is the safest default during development.
• Cache read-heavy status endpoints: If your UI polls batch progress frequently, a non-null CACHE_LIFETIME reduces repeated work. Keep the lifetime short enough that progress feels live.
• Invalidate on lifecycle events: When a batch completes, fails, or is cancelled, clear or refresh any cached state if your implementation caches derived data beyond the package’s own cache handling.
• Environment-driven configuration: If the package supports config or env overrides, drive CACHE_LIFETIME from config so staging/production can tune caching without code changes.
• Queue integration: Use caching around batch dispatch/status lookups, not around the job payload itself. Keep queued jobs deterministic and cache only derived batch metadata.

Gotchas and Tips

• v4.0.0 behavior change: CACHE_LIFETIME = null now means “no cache.” Audit existing batches that relied on null as “use default” or any previous implicit behavior. This is the main upgrade risk.
• Stale data expectations: With a non-null lifetime, batch status can be stale for up to that duration. Document this for any UI or API consumers.
• Cache driver quirks: Confirm your Laravel cache store supports the operations you rely on. If you use cache tags, ensure the configured store supports them.
• Debugging cache issues: Temporarily set CACHE_LIFETIME = null to bypass caching and isolate whether a problem is cache-related. Inspect cache keys and use Telescope or your cache store’s tooling.
• Testing: Prefer null in tests unless you are explicitly testing caching behavior. Add a focused test that asserts caching is skipped when CACHE_LIFETIME is null.
• Extension points: If the package exposes cache key or cache store resolution, override those rather than duplicating caching logic in every batch class. Keep the caching policy centralized where possible.