Quarx Laravel Package

Getting Started

Quarx is a Laravel 5-era package that installs a self-contained admin panel plus a set of content repositories for pages, blogs, events, galleries, images, and user-defined "modules." The newest tag is v2.3.0, which formally adds Laravel 5.4 support — but that is the ceiling. Treat an install today as either (a) maintenance on an existing Laravel 5.x app, or (b) a reference implementation you fork and modernize. Do not drop it into a fresh Laravel 10/11 project; the dependency chain (laravelcollective/html, Bootstrap 3, jQuery, PHP 7-only syntax) will not resolve, and the project remains unmaintained past this release.

Prerequisites for a real install

• PHP 7.0–7.1, Laravel 5.1–5.4 (5.4 is the officially supported top end as of v2.3.0).
• A working APP_KEY, DB connection, and the web middleware group.
• laravelcollective/html (Quarx's admin forms depend on it).

Minimal install sequence

composer require yab/quarx
# Laravel <5.5: register Yab\Quarx\QuarxServiceProvider in config/app.php providers
php artisan vendor:publish --provider="Yab\Quarx\QuarxServiceProvider"
php artisan migrate
php artisan db:seed --class=QuarxSeeder   # demo content + admin user
php artisan storage:link                  # if you use the image/gallery modules

Then expose the admin routes. In the 5.x style this is a facade call inside routes/web.php:

Quarx::routes(); // mounts the dashboard under the configured backend prefix (default /quarx)

Log in at /quarx/dashboard with the seeded admin credentials, change the password, then change the backend prefix in config/quarx.php before anyone finds it.

Where to look first, in this order

1. config/quarx.php — backend route prefix, module registry, pagination, upload paths, theme/view overrides. This file is the whole package's control surface.
2. database/migrations/ published from the package — you need to know which tables Quarx owns (pages, blogs, events, galleries, images, files, the revisions/history table introduced in v2.3.0, plus its users/roles tables) so you do not collide.
3. The published views under resources/views/vendor/quarx — this is your override layer.
4. Yab\Quarx\Repositories\* — the actual read APIs your front-end controllers will call.

First use case: a "page" rendered by your own front end

Create a page in the dashboard, then serve it from your app — Quarx is decoupled, so nothing is rendered publicly until you write the controller:

// routes/web.php
Route::get('{slug}', 'PageController@show');

// PageController
public function show($slug)
{
    $page = app(\Yab\Quarx\Repositories\PageRepository::class)
        ->findPageBySlug($slug);           // verify method name against the repo source

    abort_if(!$page || !$page->is_published, 404);

    return view('pages.show', compact('page'));
}

{{-- resources/views/pages/show.blade.php --}}
<h1>{{ $page->title }}</h1>
{!! $page->body !!}   {{-- see Gotchas: sanitize this --}}

Implementation Patterns

Treat Quarx as a persistence + authoring layer, not a router. The package's value is the admin CRUD, image handling, and module scaffolding. Your application owns URLs, layouts, caching, sitemaps, and SEO. Keep a thin ContentController per content type that pulls from repositories and hands plain models to Blade.

Repository injection is the sanctioned read path. Resolve repositories from the container (PageRepository, BlogRepository, EventRepository, GalleryRepository, ImageRepository) rather than querying models directly. That keeps you insulated if you later fork and change the schema, and it is where any published/date filtering lives. Always inspect the repo class for the exact method names — the API is not documented well and drifted between tags.

Content-type checklist when wiring a new front-end section

Versioning and revert (v2.3.0+). The admin now records content history and exposes revert actions. Two ways to use this: leave it as an editorial safety net, or surface it as a front-end "post history" / audit trail by reading the revision table through your own model. Do not assume the revert is transactional across relations (gallery/image associations, module data) — revert the primary record, then verify related rows. If you expose revert outside the admin, wrap it in your own authorization and log the actor; the built-in action assumes a trusted admin session.

Custom modules are the extension mechanism. Quarx ships a module scaffold: each module is a directory with its own controllers, models, migrations, views, and an admin menu entry, registered through config/quarx.php. v2.3.0 adds a module composer packager that generates the composer.json/autoload wiring for you and fixes several module-generation defects — use it rather than hand-editing namespaces, and commit the generated composer.json so a fresh composer install reproduces the same autoload map. The workflow is:

1. Scaffold the module via the admin's module builder (preferred in v2.3.0+) or by copying an existing module directory.
2. Verify the generated PSR-4 namespace landed in composer.json, then run composer dump-autoload — this is the step people forget, and the symptom is a silent "module not found" in the admin nav.
3. Write the migration, run it, and register the module in the config array.
4. Build the admin views by extending Quarx's layout partials so the module inherits the nav, flash messages, and CSRF handling.
5. Build your public-facing controller in the app, not in the module, if you want the content decoupled.

Image and gallery handling. Uploads go through the admin into the configured storage path; the DB stores the path and metadata. In your front end, resolve paths through the repository/helper rather than string-concatenating /uploads/..., so a disk or folder change is a one-line config edit. If you need responsive derivatives, generate them at upload time or in a queue job — Quarx predates Laravel's Storage::url() conventions being universal, so assume older path conventions.

Internal analytics (v2.3.0+). The new analytics component is a lightweight in-panel report over Quarx's own tables. It is useful for "what got edited/published" style visibility, not for traffic analysis — there is no client-side collection, no bot filtering, and no retention policy. Do not point stakeholders at it as a GA/Matomo replacement, and check whether it writes to its own table before your first migrate on a shared database.

Auth and roles. Quarx's admin gating is role-based on its own user/role tables. If your app already has users, decide early whether to share the users table or run Quarx's separately. Sharing is convenient but means migrating role columns into your schema; running separately means two logins. Integration tip: bind a custom middleware on the Quarx route group that maps your app's admin flag onto Quarx's role check, rather than duplicating accounts.

Deployment pattern that works. Migrate + seed once on a fresh environment; thereafter Quarx migrations are just normal app migrations. Because the package is abandoned, copy published migrations into your own database/migrations and stop relying on package-published files — otherwise a future composer update or a fresh checkout on a different machine can produce a different schema than production. Do this before you start accumulating revision rows from v2.3.0, since history data is the hardest to reconstruct.

If you need a JSON API (the "decoupled" promise), do not rely on Quarx's routes. Write an api.php group of read-only endpoints backed by the same repositories and cache the responses. That gives you a stable contract you control, independent of the abandoned package.

Gotchas and Tips

The unmaintained status is the headline gotcha. v2.3.0 is a real feature release, not a revival: no security process, no PHP 8 support, no Laravel 6+ support, and a dependency graph that includes abandoned packages. Before committing, run composer why-not laravel/framework in a scratch project; if it refuses to resolve, that is your answer. For new work, port the content schema and admin CRUD to Filament or Nova (or adopt Statamic if you want a batteries-included CMS) and keep Quarx only as a data source during migration.

Rollback no longer archives (v2.3.0 breaking-ish change). Older versions zipped the current state before a rollback; v2.3.0 removed that. Any existing runbook or admin habit that assumed "the archive is my safety net" is now wrong — take a database dump (or snapshot the affected rows) yourself before invoking rollback, especially in production. This is the one change most likely to bite silently.

XSS is on you. Quarx stores rich HTML from a WYSIWYG editor and expects {!! !!} rendering. Sanitize on output (HTML Purifier or an allow-list sanitizer) or, better, sanitize on save with a model mutator — the admin is trusted, but imports, API writes, and compromised accounts are not. Reverts replay stored HTML, so an unsanitized history entry stays dangerous after rollback.

History tables grow without pruning. Every edit in v2.3.0+ adds a revision row. On a long-lived install with large body/excerpt columns this bloats the DB and slows admin listings. Add a pruning job or a retention window before the table surprises you, and index whatever column the history screens sort by.

Config changes need a cache clear. php artisan config:clear after editing config/quarx.php, and re-publish assets (vendor:publish --tag=...) after any package-level view/asset change. A stale bootstrap/cache/config.php is the most common cause of "my route prefix didn't change." The new analytics and history screens register through the same config array — if they don't appear, suspect the config cache first.

Route and asset collisions. The admin mounts at a configurable prefix; if you already have /admin, you will shadow or be shadowed. Check with php artisan route:list | grep quarx after install. Similarly, published assets land in public/ and can overwrite your own css/js folders — publish to a scoped subdirectory and verify the layout partials point there.

Table name collisions. Quarx's migrations create images, files, a revisions table, and possibly users/roles. If your app already has those, rename Quarx's tables in the migration before the first migrate, and update the corresponding models' $table properties. Retrofitting this after data exists is painful — do it before v2.3.0 history starts filling up.

Module autoloading still fails quietly. The composer packager reduces the failure rate but "parts of module generating" is what the changelog says was fixed — not all of it. A namespace mismatch between the module directory and composer.json, a stale autoload map, or a forgotten entry in the modules config all present as "module missing from the admin menu" with no error. Debug by dumping the module registry array from the config, running composer dump-autoload -o, and checking storage/logs/laravel.log for the class-not-found.

Blade view overrides are the safest customization point. Publish views to resources/views/vendor/quarx and edit there instead of touching vendor/. It survives composer install, and it is the one customization path that stays clean if you later fork the package into packages/quarx.

Prefer forking to patching in place. Since upstream is dead, do composer require once to pull the source, then move it to a local path repository ("repositories": [{"type": "path", "url": "packages/quarx"}]) and maintain it there. You get version control over your changes, can bump the Laravel constraint yourself, and CI no longer depends on Packagist availability. Tag your fork at v2.3.0 as the baseline so the release's behavior changes are visible in your history.

Debugging workflow. Log in to the dashboard and reproduce with APP_DEBUG=true; Quarx's admin surfaces exceptions in its own layout rather than the Laravel whoops page, which can hide the stack trace — check storage/logs/laravel.log directly. For repository queries, DB::listen() in a service provider is faster than guessing which method fired. When testing history/revert, diff the row before and after rather than trusting the flash message.

Migration off-ramp. The schema is plain enough to extract. Snapshot the Quarx tables (including history), write Eloquent models in your app that map to them, point front-end controllers at the new models, then rebuild the admin in Filament. Capture the v2.3.0 revision table in the snapshot — it is editorial audit data you will want after the switch. Do this in that order — content reads first, authoring second — so the site stays live throughout.