Primer Core Laravel Package

Getting Started

rareloop/primer-core is the framework layer behind Rareloop's Primer stack: it brings Laravel's Illuminate building blocks (collections, container/config, support helpers) into a non-Laravel host application, so day-to-day work feels like writing Laravel service code rather than raw PHP.

Minimum steps to get productive:

1. composer require rareloop/primer-core — with v5.2.0 you can now resolve against illuminate/collections v11 alongside v10, so let Composer pick based on your PHP version rather than hand-pinning.
2. Check which Illuminate major you actually landed on: composer show illuminate/collections. That single line tells you whether you're on the PHP 8.2+/Laravel 11 track or the PHP 8.1/Laravel 10 track.
3. Find the bootstrap entry point first (the file where the container/config is instantiated and service providers are registered). Read that before touching anything else — it dictates load order and is where most "why is this not registered?" confusion comes from.
4. First use case: replace a hand-rolled array/loop transformation in your theme with a collect() chain. It's zero-risk, exercises the collection version you just installed, and confirms the package is wired correctly before you touch container bindings.

If you are starting fresh, don't reach for the container or service providers on day one — collections and helpers are the lowest-friction surface and where most of the value is.

Implementation Patterns

Collections as the default data layer. Treat collect() as the boundary between your data source and your templates. Fetch (query, API, config), then map/filter/groupBy into a shape the template can render without conditionals. This keeps view logic declarative and makes the Illuminate version bump in 5.2.0 a non-event for your code.

Container bindings for cross-cutting concerns. Register shared services (config readers, HTTP clients, view renderers) once in the bootstrap/provider layer and resolve them by interface downstream. The payoff is testability: swap the binding in a test bootstrap rather than mocking globals.

Providers as the extension seam. Group registrations by feature (one provider per domain area) instead of a single monolithic bootstrap file. When you upgrade Illuminate majors, you can grep one provider at a time and validate it in isolation.

Version-agnostic code for the 5.2.0 window. If you maintain multiple sites on different PHP versions, write against the collection API common to v10 and v11 rather than branching on the installed version. The intersection is large; the differences are edge cases you can handle at the call site if you hit one.

Config over constants. Read tunables through the config layer so per-environment overrides work; hardcoded values in the bootstrap are the most common cause of "works locally, wrong in staging."

Integration tip: in a WordPress-hosted context, do the container bootstrap on a hook that fires early enough for providers but late enough that the host has loaded its own functions — mis-ordering here produces null dependencies that look like package bugs.

Gotchas and Tips

• PHP floor moved for the v11 path. illuminate/collections v11 requires PHP 8.2+. If your host runs 8.1, Composer will silently resolve to v10 and you'll be reading v11 docs against v10 behaviour. Confirm the resolved version before debugging anything collection-related.
• This release widens the constraint; it does not change code. v5.2.0 is a dependency-range change (adding collections v11 support). Treat it as low risk but still smoke-test your collection-heavy paths, because the resolved dependency may move under you even though primer-core itself didn't change.
• Lock file drift across projects. Because the constraint now spans two majors, two projects on the same primer-core version can end up on different Illuminate majors. Pin with composer.lock in CI, and don't share a lock file between a PHP 8.1 and a PHP 8.2 deployment target.
• Lazy collections and generators don't behave identically to eager ones for count(), repeated iteration, or dd(). If something looks empty in a debug dump but renders fine, that's usually a lazy collection being consumed once.
• Debugging registrations: if a binding resolves to null, log the provider registration order rather than the binding itself — the problem is almost always that the provider ran before its dependency existed.
• Extension point to prefer: subclassing or decorating the package's service classes is usually safer than editing vendor code, but check whether the class is final or takes constructor dependencies from the container before committing to that approach.
• Watch the changelog, not the version number. A 5.x bump here added a dependency major without touching the public API; assume the reverse is also possible and read release notes rather than inferring risk from semver drift.