Sprinkle Core Laravel Package

Getting Started

• Install via the UserFrosting 6 skeleton (recommended) or add userfrosting/sprinkle-core to an existing UserFrosting 6 app with Composer. This is a UserFrosting sprinkle built on Slim 4 + Illuminate components, not a drop-in Laravel package.
• Confirm UserFrosting\Sprinkle\Core\Core is listed in app/sprinkles.json. The skeleton includes it; if you removed it, core services, middleware, migrations, and Bakery commands will not be wired.
• Run php bakery to see available commands, then php bakery migrate to create core tables. If you plan to use database sessions, this creates/uses the sessions table.
• Look first at:
  • vendor/userfrosting/sprinkle-core/config/ for default configuration (sessions, database, logs, cache, errors).
  • vendor/userfrosting/sprinkle-core/src/ for services, middleware, and session handlers.
  • vendor/userfrosting/sprinkle-core/schema/ for migrations.
  • vendor/userfrosting/sprinkle-core/routes/ for core routes.
• First practical use case: switch from file to database sessions. In your app config, set the session handler to database (see the core session config for the exact key), run php bakery migrate, then inject the session service into a controller and confirm reads/writes land in the sessions table. This is the same path you will use for multi-node deployments.

Implementation Patterns

• Config layering: Core ships YAML config; override it in app/config/ rather than editing vendor files. Sprinkle order in app/sprinkles.json controls merge precedence. Keep secrets in .env. Run php bakery clear-cache after config changes.
• Dependency injection: Prefer constructor injection for core services such as the Eloquent Connection, session service, translator, renderer, and logger. In older or container-aware code, resolve through the container ($this->ci->get(...)), but keep that at the edges.
• Database and migrations: Use Eloquent models for day-to-day data access. Define migrations in your sprinkle’s schema/ directory using the schema builder, and run them with php bakery migrate. Treat core migrations as read-only; add your own tables/columns in your sprinkle.
• Sessions: Use file sessions for single-node apps and database or Redis sessions for multi-node/containerized deployments. Store flash messages, CSRF state, and small auth-related values—not large payloads. If you expose “online users,” read from the session table’s activity timestamp rather than assuming a write on every request.
• Routes and middleware: Define Slim routes in your sprinkle. Core middleware handles sessions, CSRF, error rendering, and request logging. Add custom middleware in your sprinkle and register it there; avoid modifying core middleware directly.
• Errors and logging: Configure log channels and error handling in app config. Core’s error middleware renders HTML or JSON based on the request’s Accept header, so API and browser clients get appropriate responses.
• Extension points: Create your own sprinkle for custom services, config, routes, migrations, and middleware. Extend core classes (for example, a custom session handler) rather than patching vendor code.

Gotchas and Tips

• 6.0.3 session behavior: Core now uses timestamp-aware file and database session handlers, so unchanged session payloads are not rewritten. The timestamp is still updated so garbage collection and “last activity” semantics keep working. Do not assume write() runs on every request.
• Custom session handlers: If you extend or replace the core file/database handlers, implement the timestamp-update path (for example, Symfony’s SessionUpdateTimestampHandlerInterface / updateTimestamp) or extend the core handler. A custom handler that only implements write() may stop receiving calls when session data is unchanged.
• Database sessions: Verify your sessions table still has the activity timestamp column expected by the handler (the default migration includes it). If you customized the table and removed that column, timestamp updates may fail or be skipped.
• File sessions: The handler may use touch() to update mtime without rewriting the file. Ensure the web/PHP user has permission to touch session files. On NFS or shared volumes, file mtime can be unreliable; prefer database or Redis sessions in those environments.
• Caching: Config and route changes are easy to miss if caches are warm. Run php bakery clear-cache after changing session, database, or route configuration.
• Sprinkle order: Core should load before sprinkles that depend on its services. Later sprinkles override earlier config, so put app-specific overrides in your own sprinkle or app/config/.
• Debugging: Use php bakery debug and the application log (commonly logs/userfrosting.log) first. Enable debug mode only locally. For session issues, inspect the configured handler, the sessions table or session directory, and whether the request is actually starting a session.
• Upgrading to 6.0.3: This is a patch release with no documented breaking changes. Run composer update userfrosting/sprinkle-core, clear caches, and run php bakery migrate if any new migrations appear. The main behavioral change is fewer session writes, which is a performance win but can surprise code that relied on write-side effects.