Laravel Ready | Theme Manager

🔥 Concept

This dynamic theme manager brings theme support to Laravel projects. Theme Manager manages multiple theme at same time and you won't lose build-in Laravel features. This package uses custom middleware for overwriting view path with selected theme.

Add theme-manager middleware alias to your web or custom route chain. Then Theme Manager can manipulate the views.

Installation

⚠️ This package compatible only Laravel 8 and above.

To get the latest version of Laravel Theme Manager, simply require the project using Composer :

> composer require laravel-ready/theme-manager

Publish configs

Run artisan command:

                            
$ php artisan vendor:publish --tag=theme-manager-config

and you can find theme-manager.php file in config folder.

Middleware

Add theme-manager middleware alias to your base route in {route}.php or app/Providers/RouteServiceProvider.php

First way routes/{web}.php

                            
Route::prefix('/')->middleware(['theme-manager', 'another-mw'])->group(function (){
    Route::get('', [LandingController::class, 'index'])->name('home');

    Route::get('my-page', [LandingController::class, 'anyPage'])->name('my-page');
});

Second way RouteServiceProvider.php

                            
public function boot()
{
    $this->configureRateLimiting();

    $this->routes(function () {
        ...

        Route::middleware(['web', 'theme-manager'])
            ->namespace("{$this->namespace}\\Web")
            ->group(base_path('routes/web.php'));

        Route::middleware(['web', 'theme-manager'])
            ->namespace("{$this->namespace}\\Admin")
            ->group(base_path('routes/admin.php'));

    });
}

🚀 Usage

Middleware

Theme Manager works with theme and group pair. We can define default themes in routes and also you can restrict with the route specific theme groups.

⚠️ Parameter ordering does not matter.

Parameter	Description	Usage
`theme`	Specify theme alias	`theme-manager:theme=my-theme`
`group`	Specify group alias	`theme-manager:group=admin`
`restrict_group`	Restrict route with target group	`theme-manager:restrict_group=admin`

Combined usage examples:

theme-manager:theme=my-theme, group=admin, restrict_group=admin
theme-manager:theme=my-theme, group=admin
theme-manager:group=admin, theme=my-theme

If you want to add a theme you must add group alias because all themes depends to own group. Also to use multiple default theme you first must define group. See multiple and default theme sections for more example.

Service

Theme loading and other options are depends to your logic. You can use ThemeManager service in controller, custom middleware etc.

Scan installed themes

ThemeManager::scanThemes(); returns list of theme groups and their themes. Theme Manager, after themes scanned themes adds to cache. When you add new theme you should rescan the themes. Just pass true as parameter or use ThemeManager::reScanThemes(); method.

Get current theme

ThemeManager::getCurrentTheme(); returns current theme details.

Get target theme

ThemeManager::getTheme(); returns requested theme details.

Set current theme

setTheme is required two parameters. Target theme and theme group. ThemeManager::setTheme('my-theme', 'theme-group')

Views

We can call regular views with return View('welcome'). If you want to call the theme view use theme:: alias like return View('theme::welcome') in controller. theme:: alias is universal gateway for Theme Manager. After you use setTheme method Theme Manager finds theme views then Laravel renders. Also you can't use like theme::theme-name.... You can only define themes with ThemeManager service class and middleware.

                            
class AnyController extends Controller
{
    public function __construct() {
        ThemeManager::addDefaultTheme(['web:red-swan', 'admin:admin-who']);

        $theme = request()->query('theme', 'green-energy');

        ThemeManager::setTheme($theme, 'web');
    }

    public function index(){
        return View('web.welcome');
    }

    public function anyPage(){
        ...

        return View('theme::pages.any-page');
    }
}

Directives

Directive	Description	Parameters
`@asset`	Get theme asset URL	`0`: Asset path, `1`: Print theme version number (default `true`)
`@assetLoad`	Get theme asset content as string	`0`: Asset path, `1`: Fallback asset (default `null`)
`@svg`	Get SVG content as string	`0`: SVG file name, `1`: Class name (default `null`), `2`: CSS style (default `null`)

@asset
- @asset('css/base.css')
- @asset('css/base.css', true|false)
- @asset('js/app.js')
- @asset('images/user/avatar-01.jpg')
- @asset('favicons/favion.ico')
@assetLoad
- @assetLoad('css/base.css')
- @assetLoad('html/any-template.html')
- @assetLoad('images/svg/sunshine.svg', 'images/svg/moonshine.svg')
@svg
- @svg('chevron-left')
- @svg('chevron-right', 'mx-auto')
- @svg('chevron-down', 'mx-auto', 'fill: green; top: 20px; position: relative;')

The above asset paths css, js, html are not reserved or any custom paths are depends to your theme webpack.mix.js configs and design approach.

⚠️ Published theme specific assets must be in project-folder/src/public/themes/{group-alias}/{theme-alias}/ folder because Theme Manager uses this path for directives.

Default Theme

We can define default themes with config file and service class.

Config file

Open theme-manager.php file then set default_theme value. default_theme supports single and multiple themes.

                            
<?php

return [
    ...

    'default_theme' => 'web:red-swan',

    ...
];

or in array

                            
<?php

return [
    ...

    'default_theme' => [
        'web:red-swan',
        'admin:admin-who'
    ],

    ...
];

Service class

...

✳️ Theme

Folder Structure

In your root folder create themes folder then add your themes to own group folder. Also you can change themes folder path with package configs (must be in root folder). Theme folder structure must be like this:

                            
.
└── src
    ├── app
    ├── public
    ├── ...
    ├── {themes}
        ├── web
        │    ├── my-awesome-theme
        │    ├── your-awesome-theme
        │    ├── ...
        ├── admin
        │    ├── banana
        │    ├── cerry
        │    ├── apple
        │    ├── orange
        │    ├── ...
        ├── other-group
        │    ├── other-theme
        │    ├── other-other-theme
        │    ├── ...
        ├── ...

In this case web, admin and other-group is theme group. We use groups for specific purposes. Then we can add specific themes to own group folder. You should publish this package configs, see installation part.

Commands

You can manage themes with commands.

List installed themes

> php artisan theme-manager:list

Result:

                            
⚠️  Check the "theme-config.json" file in the own theme folder for more information.

+-------+---------+--------------+--------------+-------+-----------------------------------+-----------------+---------+
| Index | Default | Name         | Alias        | Group | Description                       | Authors         | Version |
+-------+---------+--------------+--------------+-------+-----------------------------------+-----------------+---------+
|  [1]  | Yes     | Admin Who?   | admin-who    | admin | Dolore officia adipisicing ven... | EgoistDeveloper | 0.0.0   |
|  [2]  | -       | Gentelella   | gentelella   | admin | Gentelella Admin is a free to...  | EgoistDeveloper | 3.1.3   |
|  [3]  | -       | Dark Night   | dark-night   | web   | Find the perfect lights in dar... | EgoistDeveloper | 1.1.3   |
|  [4]  | -       | Green Energy | green-energy | web   | Green energy is any energy typ... | EgoistDeveloper | 4.1.3   |
|  [5]  | Yes     | Red Swan     | red-swan     | web   | The awesome red swan web site...  | EgoistDeveloper | 1.0.1   |
+-------+---------+--------------+--------------+-------+-----------------------------------+-----------------+---------+