Pyrocms Theme Laravel Package

Getting Started

This is an admin-panel skin for PyroCMS 3, not a front-end theme. If you are expecting to restyle public pages, this package will not do that — it overrides control-panel views and assets so the CMS back end looks and behaves differently for your editors and clients.

Minimum steps

1. Confirm your PyroCMS version first. The package was last released in December 2016, which places it in the PyroCMS 3.0 / Laravel 5.x era. Pin your PyroCMS constraint before requiring it, e.g. composer require websemantics/pyrocms-theme against an already-locked pyrocms/* version, and run composer why-not if resolution fails.
2. Check the package's composer.json for "type": "pyrocms-theme" and any extra.pyrocms registration block. PyroCMS addons are discovered through Composer metadata, so a composer dump-autoload is often needed before the theme appears.
3. Activate it as the control-panel theme — typically through Settings → Control Panel / Themes in the admin, or the addon management screen. If no UI toggle is exposed, look for a settings key or config value in the package's config/ directory.
4. Clear caches: php artisan view:clear, php artisan cache:clear, and re-publish assets if the theme ships an asset publish step.
5. Log out and back in, then hard-refresh the admin to rule out cached compiled CSS/JS.

Where to look first

• resources/views/ — the Blade layout, sidebar, navbar, dashboard and auth screens. This is where 90% of your customization work will happen.
• resources/assets/ (or resources/scss, resources/less, public/) — the skin's stylesheet and scripts. Find the variables file before touching anything else.
• composer.json → extra — tells you the theme's namespace and whether it declares a parent/base theme.
• The service provider in src/ — the extension point for view composers, asset registration, and config merging.

First use case

Set the theme as the admin skin on a client project and rebrand it: swap the logo, primary color, and login screen so the CMS matches the client's brand. Do this through a child theme or published overrides — never by editing files inside vendor/.

Implementation Patterns

Treat vendor code as read-only. The single most valuable habit with a package this old is to never patch vendor/websemantics/pyrocms-theme directly. Two safe patterns:

• Published overrides: if the theme registers a publishable view/asset path, publish and edit the copies. They survive composer update; vendor edits do not.
• Child theme addon: create your own pyrocms-theme addon that declares this one as its base/parent, and override only the views you care about. Blade's view finder falls through to the parent for anything you do not override, so you inherit upstream fixes for untouched partials while owning your changes.

Targeted partial overrides. Instead of replacing the whole layout, override the smallest view that achieves the goal:

• Login/auth screens → the auth view namespace.
• Branding → header/logo partial plus the variables file.
• Navigation → sidebar/navbar partials, especially if you need to hide sections from non-admin roles.
• Dashboard → the dashboard view and any widget partials.

Override the layout only when you genuinely need structural changes; layout overrides are the most likely to break when PyroCMS itself updates.

Data injection with view composers. Rather than hardcoding copy or URLs in Blade, bind a view composer in your own service provider and share a config array (brand name, support URL, logo path, accent color). This makes the same theme reusable across multiple client sites and lets you switch branding per environment — staging with a visible "STAGING" banner, production clean.

Per-environment theming. Because the active admin theme is a setting, you can keep production on the stock PyroCMS admin and enable this skin on staging while you iterate on it. Combine this with environment-specific config to avoid shipping half-finished UI to editors.

Asset layering. Do not rewrite the theme's SCSS/LESS from scratch. Load your overrides after the theme's compiled stylesheet and change variables/tokens. Keep custom JS in a separate file and initialize on DOM-ready rather than inlining script tags into overridden Blade partials — inline scripts inside overridden views are easy to duplicate accidentally when a layout renders a partial twice.

Streams/form styling. The bulk of day-to-day admin work in PyroCMS is Streams entry forms and listing tables. Add your own form and table styles as additive overrides so custom fields (WYSIWYG, repeater, relationship) still render correctly. Test with a Stream that has a wide relationship field and a repeater — those are the layouts most likely to overflow on the responsive breakpoints.

Role-aware chrome. If clients only ever use a few modules, use view composers or the sidebar partial to suppress unrelated navigation groups for non-admin roles. This is where an admin theme delivers the most perceived value: fewer buttons, less confusion.

Gotchas and Tips

Age and abandonment are the headline risk. Last release December 2016, 15 stars. There is effectively no upstream support. Before adopting: confirm it actually activates on your PyroCMS version, audit the Blade views for anything that touches auth or permissions, and pin both the theme and pyrocms/* in composer.lock. Budget for the possibility that a PyroCMS point upgrade breaks the skin and you own the fix.

Editing vendor files is a trap. composer update, composer install in CI, or a fresh deploy will silently revert your changes. If you catch yourself editing under vendor/, stop and move the change into a published override or child theme.

Assets get overwritten. Publishing with a force flag will clobber your customized CSS/JS. Keep a diff or, better, keep your overrides in a separate file that the layout loads last.

Cache layers bite twice. PyroCMS/Streams caches settings and compiled views on top of Laravel's own caches. When a change "doesn't appear," clear in this order: view:clear, cache:clear, then a hard browser refresh. A stale compiled Blade view is the most common false alarm.

View precedence confusion. If your override isn't taking effect, you may be overriding the wrong namespace or the wrong filename. Verify which file is actually rendering before rewriting it — check the view path in an exception stack trace, or temporarily log the resolved view. view:clear after every structural change.

Upgrades break layout overrides. Overriding the full layout means every PyroCMS core change to that layout is yours to merge. After any CMS upgrade, diff your overridden views against the originals. Partial-level overrides dramatically reduce this maintenance burden.

Responsive edge cases live in tables, not the dashboard. The dashboard usually looks fine; Streams listing tables and long multi-column entry forms are where the skin's responsive claims get tested. Check with a narrow viewport and a real dataset, not the empty state.

Composer discovery failures. If the theme doesn't appear in the admin, the usual culprits are: composer dump-autoload not run, the extra.pyrocms block missing or malformed, or a cached addon manifest. Clear caches and re-check the Composer metadata before assuming the package is incompatible.

License is fine, dependency chain is not. MIT is permissive, but assess the transitive dependencies the theme pulled in circa 2016 — an old front-end asset toolchain can be the real security surface, not the Blade files.

Extension points to prefer. When you need behavior, reach for: a view composer in your own service provider, the published config file, and Blade @extends/@section inheritance. When you need to change markup, reach for the smallest partial. Avoid fork-and-maintain the whole theme unless you are prepared to own it indefinitely.