README

Themevel is a Laravel theme and asset management package. You can easily integrate this package with any Laravel based project.

Features

Custom theme path
Override theme
Parent theme support
Unlimited Parent view finding
Asset Finding
Theme translator support
Multiple theme config extension
Multiple theme changelog extension
Artisan console commands
Theme enable only Specific route via middleware
Almost everything customizable
Also Laravel 7.0+, 8.0+, 9.0+ Support

Installation

Themevel is a Laravel package so you can install it via Composer. Run this command in your terminal from your project directory:

composer require shipu/themevel

Wait for a while, Composer will automatically install Themevel in your project.

Configuration

Below Laravel 5.5 you have to call this package service in config/app.php config file. To do that, add this line in app.php in providers array:

Shipu\Themevel\Providers\ThemevelServiceProvider::class,

Below Laravel 5.5 version to use facade you have to add this line in app.php to the aliases array:

'Theme' => Shipu\Themevel\Facades\Theme::class,

Now run this command in your terminal to publish this package resources:

php artisan vendor:publish --provider="Shipu\Themevel\Providers\ThemevelServiceProvider"

Artisan Command

Run this command in your terminal from your project directory.

Create a theme directory:

php artisan theme:create your_theme_name


 What is theme title?:
 > 

 What is theme description? []:
 > 

 What is theme author name? []:
 >  

 What is theme version? []:
 > 

 Any parent theme? (yes/no) [no]:
 > y

 What is parent theme name?:
 >

List of all themes:

php artisan theme:list

+----------+--------------+---------+----------+
| Name     | Author       | Version | Parent   |
+----------+--------------+---------+----------+
| themeone | Shipu Ahamed | 1.1.0   |          |
| themetwo | Shipu Ahamed | 1.0.0   | themeone |
+----------+--------------+---------+----------+

Example folder structure:

- app/
- ..
- ..
- Themes/
    - themeone/
        - assets
            - css
                - app.css
            - img
            - js
        - lang
            - en
                -content.php
        - views/
            - layouts
                - master.blade.php
            - welcome.blade.php
        - changelog.yml        
        - theme.json
     - themetwo/

You can change theme.json and changelog.yml name from config/theme.php

// ..
'config' => [
    'name' => 'theme.json',
    'changelog' => 'changelog.yml'
],
// ..

json, yml, yaml, php, ini, xml extension supported.

For example:

// ..
'config' => [
    'name' => 'theme.json',
    'changelog' => 'changelog.json'
],
// ..

Then run theme:create command which describe above.

Now Please see the API List Doc.

View Finding Flow:

Suppose you want find welcome.blade.php

 - At first check your active theme 
 - If `welcome.blade.php not found in active theme then search parent recursively
 - If `welcome.blade.php not found in parents theme then search laravel default view folder resources/views

API List

set

For switching current theme you can use set method.

Theme::set('theme-name');

get

For getting current theme details you can use get method:

Theme::get(); // return Array

You can also get particular theme details:

Theme::get('theme-name'); // return Array

Theme::get('theme-name', true); // return Collection

current

Retrieve current theme's name:

Theme::current(); // return string

all

Retrieve all theme information:

Theme::all(); // return Array

has

For getting whether the theme exists or not:

Theme::has(); // return bool

getThemeInfo

For info about the specified theme:

$themeInfo = Theme::getThemeInfo('theme-name'); // return Collection

$themeName = $themeInfo->get('name');
// or
$themeName = $themeInfo['name'];

Also fallback support:

$themeInfo = Theme::getThemeInfo('theme-name'); // return Collection

$themeName = $themeInfo->get('changelog.versions');
// or
$themeName = $themeInfo['changelog.versions'];
// or you can also call like as multi dimension
$themeName = $themeInfo['changelog']['versions'];

assets

For binding theme assets you can use the assets method:

Theme::assets('your_asset_path'); // return string

It's generated at BASE_URL/theme_roots/your_active_theme_name/assets/your_asset_path

If your_asset_path does not exist then it's find to active theme immediate parent assets folder. Look like BASE_URL/theme_roots/your_active_theme_parent_name/assets/your_asset_path

When using helper you can also get assets path:

themes('your_asset_path'); // return string

If you want to bind specific theme assets:

Theme::assets('your_theme_name:your_asset_path'); // return string
// or 
themes('your_theme_name:your_asset_path'); // return string

Suppose you want to bind app.css in your blade. Then below code can be applicable:

<link rel="stylesheet" href="{{ themes('app.css') }}">

Specific theme assets:

<link rel="stylesheet" href="{{ themes('your_theme_name:app.css') }}">

lang

The lang method translates the given language line using your current theme localization files:

echo Theme::lang('content.title'); // return string
// or
echo lang('content.title'); // return string

also support

echo Theme::lang('content.title', [your replace array], 'your desire locale'); // return string
// or
echo lang('content.title', [your replace array], 'your desire locale'); // return string

If you want to bind specific theme assets:

echo Theme::lang('your_theme_name::your_asset_path'); // return string
// or 
echo lang('your_theme_name::your_asset_path'); // return string

How to use in Route

Route::get('/', function () {
    Theme::set('your_theme_name');
    return view('welcome');
});

This will firstly check if there is a welcome.blade.php in current theme directory. If none is found then it checks parent theme, and finally falls back to default Laravel views location.

If you want to specific theme view:

Route::get('/', function () {
    Theme::set('your_theme_name');
    return view('your_theme_name::welcome');
});

Set theme using route middleware

A helper middleware is included out of the box if you want to define a theme per route. To use it:

First register it in app\Http\Kernel.php:

protected $routeMiddleware = [
    // ...
    'theme' => \Shipu\Themevel\Middleware\RouteMiddleware::class,
];

Now you can apply the middleware to a route or route-group. Eg:

Route::group(['prefix' => 'admin', 'middleware'=>'theme:Your_theme_name'], function() {
    // ... Add your routes here 
    // The Your_theme_name will be applied.
});

Set theme using web middleware

A helper middleware is included out of the box if you want to define a theme per route. To use it:

First register it in app\Http\Kernel.php:

protected $middlewareGroups = [
    'web' => [
        // ...
        \Shipu\Themevel\Middleware\WebMiddleware::class,
    ],
    // ...
];

Theme set from config/theme.php .

Then in your controller you can call your view as you would normally do:

return view('home');  // This will load the home.blade.php from the the folder you set in your `config/theme.php`

Dependency Injection

You can also inject theme instance using ThemeContract, eg:

use Shipu\Themevel\Contracts\ThemeContract;

private $theme;

public function __construct(ThemeContract $theme)
{
    $this->theme = $theme
}

Troubleshooting

Clear config after runing vendor publish (see Config section) to save issues related to config caching by running:

php artisan config:cache

php artisan config:clear

Credits

Support for this project

Hey dude! Help me out for a couple of 🍻!

enver / themevel

Maintainers

Details