folklore/laravel-folklore
A Laravel package from folklore that integrates with your app via Composer. It follows standard Laravel package conventions for configuration and setup; see the repository README for installation steps and usage details.
folklore/laravel-folklore is not a general-purpose package: it is the shared foundation the Folklore team layers under every Laravel site they build. Treat it as an internal toolbox with a core you always use (entities, repositories, JsonDataCast, pages and blocks, medias, users/auth) and optional modules you enable only when a project needs them (Customer.io, Google Maps/Places/Drive, PubNub broadcaster, PubSubHubbub, organisations, Panneau fields/resources, view composers, make:* generators). If you are outside Folklore, the day-to-day value is mostly in borrowing the patterns; if you are inside, it is the baseline you inherit on day one.
Minimal steps:
AGENTS.md and composer.json require PHP ^8.3 and Laravel 11–13. Trust composer.json, not the description. As of v1.1.7 the Guzzle constraint is ^7.15.2|^8.0.1 — Guzzle 8 is only accepted by Laravel 13, so your Laravel version decides your Guzzle major for you.composer require folklore/laravel-folkloreextra.laravel.providers in the package's composer.json rather than assuming a class name. If it is not auto-discovered, register it in bootstrap/providers.php.php artisan migrate. There is a src/migrations directory and src/stubs, so publishing is the intended flow; publish selectively so you do not drag in tables for modules you will not use.Where to look first, in order:
src/Folklore/Contracts — the interfaces that define the whole architecture. This is the map.src/Folklore/Entities and src/Folklore/Repositories — the base classes you will actually extend.src/Folklore/Eloquent — JsonDataCast, the single most reusable piece in the package.src/migrations — the schema the entities expect.First use case: take a model that has a JSON column and a bit of structured, possibly translated, content, extend the base Entity, back it with a repository bound to its contract, and cast the JSON column with JsonDataCast. That is the smallest slice that exercises the core and shows you the house style.
Entity + repository, wired through the container. The core convention is a contract in Folklore\Contracts, an entity extending the base entity, and a repository implementing the contract. Bind the contract to the repository in a service provider and inject the contract everywhere. Day to day this means: controllers and jobs never touch Eloquent directly, they take the repository interface; tests swap the binding for a fake or use the in-memory SQLite harness. Follow the existing pairs in the package instead of inventing a new layering.
JsonDataCast for structured attributes. Use it for JSON columns holding arrays, settings blobs, or translation maps rather than hand-rolling json_decode in accessors. The win is consistent array access and dirty-tracking behaviour across every entity in the codebase. If you need custom shape, extend or wrap the cast rather than adding per-model accessors — otherwise you lose the uniformity that makes the package worth having.
Pages and blocks for editorial content. When a site's content is composed rather than fixed-schema, model it as pages containing blocks. Blocks are the unit of reuse: a block type is written once, then placed on many pages. Reach for this before you invent a bespoke CMS table.
Medias on top of folklore/laravel-mediatheque. Do not add a separate upload library. laravel-mediatheque is the dependency the package builds on, so uploads, conversions and media entities come from there and the folklore layer just integrates them with entities and pages. Check the mediatheque docs for the actual API; the folklore side is the glue.
Users and the repository auth provider. The package ships a repository auth driver. Point config/auth.php at it when users live behind a repository rather than a plain Eloquent model, and make sure your user contract binding is in place before the auth manager resolves the driver — the classic failure is a provider that boots fine and then throws on the first Auth::attempt().
Outbound HTTP goes through the MakesRequests helpers. Optional modules that talk to third parties use the shared request helpers rather than instantiating their own Guzzle client, so version differences and error handling are solved once. Call requestJson() / requestData() from your own integrations instead of opening a raw client: since v1.1.7 these no longer blow up when a Guzzle request exception carries no response (too many redirects, connection failure), and on Laravel 11 they hand back a Laravel response rather than a PSR-7 one. Write your consuming code against Laravel's response contract.
Optional modules are opt-in and config-gated. Enable a module by publishing/configuring it, not by hoping it is inert. Concretely: Customer.io for outbound messaging, Google (Maps/Places/Drive) for geo and file integration, the PubNub broadcaster when you need real-time, PubSubHubbub for feed pings, organisations for multi-tenant-ish grouping, Panneau fields/resources when the admin is built with laravel-panneau, view composers for shared view data, and the make:* generators to scaffold new entities/repositories in the house style.
Generators before copy-paste. The make:* commands exist so new entities and repositories match the conventions. Use them, then edit — a hand-written entity that drifts from the base class is the most common source of subtle breakage.
Additive by default. The package explicitly serves existing sites. When you extend it, prefer opt-in changes whose defaults preserve current behaviour, and deprecate before removing. This shapes how you integrate: never patch the vendor tree, and prefer adding a new module or a new contract over changing an existing signature.
The docs lie about the version. "Laravel 5 package" in the description versus PHP ^8.3 / Laravel 11–13 in composer.json. Verify requirements from composer.json and the CI matrix, and pin a version in your app. With zero stars and zero dependents there is no community to catch a bad release — read CHANGELOG and the UPGRADE guide, and diff the vendor directory after every bump.
Do not pin Guzzle above your Laravel. v1.1.7 widened the constraint to ^7.15.2|^8.0.1, but only Laravel 13 accepts Guzzle 8; Laravel 11 and 12 sites stay on Guzzle 7 and see no behavioural change. If you force Guzzle 8 into a Laravel 12 app you are off the tested matrix. Also, the bumped minimums exist for a reason: both include the fix for GHSA-v5mv-p594-2x33, which the media download host checks depend on. A guzzlehttp/guzzle constraint loosened below 7.15.2 or 8.0.1 re-opens that hole — don't.
Exceptions without a response are now survivable. With Guzzle 8, only exceptions that actually carry a response expose one. Anything you write that catches a Guzzle exception and immediately calls ->getResponse() will fatal on redirect loops and connect failures; guard for a null response, or go through requestJson() / requestData() and let them normalise the error path. Remember the return type shifts between Laravel versions (Laravel response on 11, PSR-7 in some paths) — type-hint loosely.
Google Places referer header is now empty when app.url is null. Creating the service no longer throws under Guzzle 8 in that case, and it behaves like Guzzle 7 did: an empty referer. If Places restrictions are configured on the Google side, an unset app.url can silently start failing requests rather than failing at construction — set app.url in every environment where you use the Places module.
Migration and stub publishing collides. Published migrations get timestamped and copied into your app; a package update that changes a published migration will not re-run it. Decide up front which migrations you own, and keep the published set as small as possible. Same for stubs — if you edit a published stub, remember it no longer tracks upstream.
Boot-time side effects are the failure mode of a toolbox. If something behaves oddly at boot (unexpected config, a broadcaster registered, a client instantiated), suspect an optional module that got enabled implicitly. The package's own rule is that unused modules must be free; when debugging, disable modules one config key at a time rather than bisecting your app.
Repository bindings must be resolvable early. Auth, view composers and broadcasters all resolve from the container during boot or on the first request. Bind contracts in register(), not boot(), and avoid resolving repositories inside a provider constructor.
Testing. The package's own suite runs on Orchestra Testbench with SQLite in memory — mirror that for anything you build on top, because it is the path of least resistance and matches CI. If you switch to MySQL with DB_DRIVER=mysql, know that the database is wiped before each test; never point that at anything but a disposable schema. Add a regression test with every bug fix; that is a stated requirement, not a preference. If your app touches the HTTP helpers, also run against the lowest Guzzle you accept — CI does this for the package and it is where version-specific breakage shows up first.
Static analysis is baselined, and that is a trap. phpstan-baseline.neon lists existing Larastan errors. Never append new errors to it — fix them. If you fix baselined ones, regenerate with vendor/bin/phpstan analyse --generate-baseline --memory-limit=2G. After a dependency update, if Larastan reports unmatched baseline entries, run vendor/bin/testbench package:discover and vendor/bin/phpstan clear-result-cache before regenerating. This is exactly what a Guzzle bump triggers: new stubs and signatures surface as unmatched entries, not as new errors. Run composer format (Pint, laravel preset) before committing, and set git config blame.ignoreRevsFile .git-blame-ignore-revs so the mass-Pint commit does not poison git blame.
Language discipline. All code, comments, docblocks, exception/log/console messages, commits, PRs and docs are English — even when the discussion is in French. User-facing strings go through trans('...'), never hardcoded. This bites in reviews, not at runtime.
Extension points, ranked. Contracts (implement, don't fork) → container bindings → published config → published stubs → event/view-composer hooks. Reaching below that, into vendor source, means you have found a missing extension point; open an issue against the roadmap issue rather than patching locally.
Contributing back. Active development is on the v1.1 branch, not main. Create a sub-issue of the roadmap issue before starting, reference it in the PR, and expect CI across PHP 8.3/8.4 × Laravel 11–13 plus the Panneau, MySQL and lowest-Guzzle matrix to be the gate. Local green tests are necessary, not sufficient — if you touched HTTP, check the job log's printed Guzzle version before believing the result.
How can I help you explore Laravel packages today?