Skip to content

Commit 19ff19c

Browse files
gaetan-hexadoggaetan-hexadog
committed
first commit
0 parents  commit 19ff19c

34 files changed

+2424
-0
lines changed

‎.gitignore

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
vendor/
2+
.idea/
3+
composer.lock
4+
.php_cs.cache
5+
build/
6+
.DS_Store
7+
*.cache

‎.gitlab-ci.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
image: registry.git.hexadog.com/docker/php:7.4
2+
3+
stages:
4+
- test
5+
6+
codestyle:
7+
stage: test
8+
script:
9+
- phpcs --config-set show_warnings 0
10+
- phpcs --extensions=php ./src

‎README.md

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
<p align="center">Laravel Themes Manager</p>
2+
3+
<p align="center">
4+
<a href="https://packagist.org/packages/hexadog/laravel-themes-manager">
5+
<img src="https://poser.pugx.org/hexadog/laravel-themes-manager/v" alt="Latest Stable Version">
6+
</a>
7+
<a href="https://packagist.org/packages/hexadog/laravel-themes-manager">
8+
<img src="https://poser.pugx.org/hexadog/laravel-themes-manager/downloads" alt="Total Downloads">
9+
</a>
10+
<a href="https://packagist.org/packages/hexadog/laravel-themes-manager">
11+
<img src="https://poser.pugx.org/hexadog/laravel-themes-manager/license" alt="License">
12+
</a>
13+
</p>
14+
15+
## Introduction
16+
<code>hexadog/laravel-themes-manager</code> is a Laravel package which was created to let you developing multi-themes Laravel application.
17+
18+
## Installation
19+
This package requires PHP 7.3 and Laravel 7.0 or higher.
20+
21+
To get started, install Themes Manager using Composer:
22+
```shell
23+
composer require hexadog/laravel-themes-manager
24+
```
25+
26+
The package will automatically register its service provider.
27+
28+
To publish the config file to config/themes-manager.php run:
29+
```shell
30+
php artisan vendor:publish --provider="Hexadog\ThemesManager\Providers\PackageServiceProvider"
31+
```
32+
33+
## Configuration
34+
This is the default contents of the configuration:
35+
```php
36+
<?php
37+
38+
return [
39+
/*
40+
|--------------------------------------------------------------------------
41+
| Path to lookup theme
42+
|--------------------------------------------------------------------------
43+
|
44+
| The root path containing themes collection.
45+
|
46+
*/
47+
'directory' => env('THEMES_DIR', 'themes'),
48+
49+
/*
50+
|--------------------------------------------------------------------------
51+
| Symbolic path
52+
|--------------------------------------------------------------------------
53+
|
54+
| you can change the public themes path used for assets
55+
|
56+
*/
57+
'symlink_path' => 'themes',
58+
59+
/*
60+
|--------------------------------------------------------------------------
61+
| Fallback Theme
62+
|--------------------------------------------------------------------------
63+
|
64+
| If you don't set a theme at runtime (through middleware for example)
65+
| the fallback theme will be used automatically.
66+
|
67+
*/
68+
'fallback_theme' => null,
69+
];
70+
```
71+
72+
## Usage
73+
There is multiple ways to work with Themes Manager. You can either set a new theme manually, using Web Middleware or Route Middleware.
74+
75+
### Manually Set Theme
76+
Use one of the following method to set a theme any time:
77+
```php
78+
ThemesManager::set('one');
79+
80+
// or
81+
Theme::set('one');
82+
```
83+
84+
### Web Middleware
85+
Create a new Middleware in <code>app/Http/Middleware</code> and configure your Laravel application to use it. This middleware must extends <code>Hexadog\ThemesManager\Http\Middleware\ThemeLoader</code> middleware.
86+
87+
Here is an example of middleware which set a theme based on the request url. It activated `admin` theme if current request url matches the `http(s)://mydomain/admin` pattern and use the fallback theme otherwise.
88+
```php
89+
<?php
90+
91+
namespace App\Http\Middleware;
92+
93+
use Closure;
94+
use Hexadog\ThemesManager\Http\Middleware\ThemeLoader as HexadogThemeLoader;
95+
96+
class ThemeLoader extends HexadogThemeLoader
97+
{
98+
public function handle($request, Closure $next)
99+
{
100+
// Check if request url starts with admin prefix
101+
if (!is_null(Request()->getPathInfo()) && Str::startsWith(ltrim(Request()->getPathInfo(), '/'), 'admin') {
102+
// Set a specific theme for matching urls
103+
$theme = 'backend';
104+
}
105+
106+
// Call parent Middleware handle method
107+
parent::handle($request, $next, $theme);
108+
}
109+
}
110+
```
111+
112+
Edit <code>App\Http\Kernel.php</code> file to add your new middleware into the list of middlewares used by your application.
113+
```php
114+
<?php
115+
116+
namespace App\Http;
117+
118+
use Illuminate\Foundation\Http\Kernel as HttpKernel;
119+
120+
class Kernel extends HttpKernel
121+
{
122+
/**
123+
* The application's global HTTP middleware stack.
124+
*
125+
* These middleware are run during every request to your application.
126+
*
127+
* @var array
128+
*/
129+
protected $middleware = [
130+
// ...
131+
\App\Http\Middleware\ThemeLoader::class,
132+
];
133+
134+
// ...
135+
}
136+
```
137+
138+
## Route Middleware
139+
Edit App\Http\Kernel.php file to add the route middleware into the list of middlewares used by your application.
140+
```php
141+
// Within App\Http\Kernel Class...
142+
143+
protected $routeMiddleware = [
144+
// ...
145+
'theme' => \Hexadog\ThemesManager\Http\Middleware\ThemeLoader::class,
146+
];
147+
```
148+
149+
Once the middleware has been defined in the HTTP kernel, you can use the middleware method to assign a theme to a route (or a group of routes):
150+
```php
151+
// Use theme named "one" for set of routes
152+
Route::middleware('theme:one')->group(function() {
153+
// Your routes definition here
154+
});
155+
156+
// Use Theme names "two" for another set of routes
157+
Route::middleware('theme:two')->group(function() {
158+
// Your routes definition here
159+
});
160+
```
161+
162+
## Assets
163+
A theme can have its own assets (images, stylesheets, javascript, ...). Theme's specific assets should be stored within <code>themes/themeVendor/themeName/public</code> folder of the theme.
164+
165+
When a theme is activted, this directory is linked (using symbolic link) into <code>public/themes</code> folder of the Laravel application so assets will be available publicly.
166+
167+
### Asset url
168+
Ask the theme manager to generate the stylesheet HTML tag:
169+
```php
170+
{!! Theme::asset('css/app.min.css') !!}
171+
172+
// or using helper
173+
{!! theme_asset('css/app.min.css') !!}
174+
```
175+
176+
This call will return the url of requested asset:
177+
```
178+
/themes/hexadog/default/css/app.min.css
179+
```
180+
181+
### Style
182+
Ask the theme manager to generate the stylesheet HTML tag:
183+
```php
184+
{!! Theme::style('css/app.min.css') !!}
185+
186+
// or using helper
187+
{!! theme_style('css/app.min.css') !!}
188+
```
189+
190+
This call will generate the following code:
191+
```html
192+
<link href="/themes/hexadog/default/css/app.min.css">
193+
```
194+
195+
### Script
196+
Ask the theme manager to generate the script HTML tag:
197+
```php
198+
{!! Theme::script('js/app.min.js') !!}
199+
200+
// or using helper
201+
{!! theme_script('js/app.min.js') !!}
202+
```
203+
204+
This call will generate the following code:
205+
```html
206+
<script src="/themes/hexadog/default/js/app.min.js"></script>
207+
```
208+
209+
### Image
210+
Ask the theme manager to generate the image HTML tag:
211+
```php
212+
{!! Theme::image('img/logo.png', 'My Theme logo') !!}
213+
214+
// or using helper
215+
{!! theme_image('img/logo.png', 'My Theme logo') !!}
216+
```
217+
This call will generate the following code:
218+
```html
219+
<img src="/themes/hexadog/default/img/logo.png" alt="My Theme logo" />
220+
```
221+
222+
## Blade Directives
223+
This package provides some blade helpers:
224+
225+
### Display page title
226+
```php
227+
@pagetitle('My page') // display "My page - Site Name"
228+
229+
// Only display page title without site name
230+
@pagetitle('My page', false) // display "My page"
231+
232+
// Customize page title, site name separator
233+
@pagetitle('My page', true, ' | ') // display "My page | Site Name"
234+
```
235+
236+
## Artisan Command
237+
This package provides some artisan commands in order to manage themes.
238+
239+
### Create Theme
240+
You can easily create a new Theme by using the following command and follow the steps:
241+
```shell
242+
php artisan theme:make
243+
```
244+
245+
This command will create a new Theme directory with all necessary files within the `themes` folder.
246+
247+
### List Themes
248+
List all existing themes in your application with their details.
249+
```shell
250+
php artisan theme:list
251+
```
252+
253+
## View
254+
Themes Manager will prepend theme views paths to the existing Laravel View Finder locations. This way you can easily override any default view (even any third package published views).
255+
256+
Suppose you request to display `welcome.blade.php` view
257+
```php
258+
return view('welcome');
259+
```
260+
261+
1. View will be searched into the current active theme `resources/views` folder
262+
2. If the view is not found in active theme then search into parents themes recursively
263+
3. If the view is still not found then search laravel default view folder `resources/views`
264+
265+
## Related projects
266+
- [Laravel Theme Installer](https://github.com/hexadog/laravel-theme-installer): Composer plugin to install `laravel-theme` packages outside vendor directory .
267+
268+
## License
269+
270+
Laravel Themes Manager is open-sourced software licensed under the [MIT license](LICENSE).

‎composer.json

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{
2+
"name": "hexadog/laravel-themes-manager",
3+
"description": "Laravel Themes management package",
4+
"license": "MIT",
5+
"support": {
6+
"issues": "https://github.com/hexadog/laravel-themes-manager/issues",
7+
"source": "https://github.com/hexadog/laravel-themes-manager"
8+
},
9+
"authors": [
10+
{
11+
"name": "Gaetan",
12+
"email": "gaetan@hexadog.com"
13+
}
14+
],
15+
"minimum-stability": "stable",
16+
"require": {
17+
"hexadog/laravel-theme-installer": "^1.0",
18+
"illuminate/view": "^7.0|^8.0"
19+
},
20+
"require-dev": {
21+
"phpunit/phpunit": "^7.0|^8.0|^9.0",
22+
"orchestra/testbench": "~5.2"
23+
},
24+
"autoload": {
25+
"psr-4": {
26+
"Hexadog\\ThemesManager\\": "src"
27+
},
28+
"files": [
29+
"helpers/helpers.php"
30+
]
31+
},
32+
"autoload-dev": {
33+
"psr-4": {
34+
"Hexadog\\ThemesManager\\Test\\": "tests"
35+
}
36+
},
37+
"extra": {
38+
"laravel": {
39+
"providers": [
40+
"Hexadog\\ThemesManager\\Providers\\PackageServiceProvider"
41+
],
42+
"aliases": {
43+
"Theme": "Hexadog\\ThemesManager\\Facades\\ThemesManager"
44+
},
45+
"dont-discover": []
46+
}
47+
}
48+
}

‎config/config.php

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
return [
4+
/*
5+
|--------------------------------------------------------------------------
6+
| Path to lookup theme
7+
|--------------------------------------------------------------------------
8+
|
9+
| The root path contains themes collections.
10+
|
11+
*/
12+
'directory' => env('THEMES_DIR', 'themes'),
13+
14+
/*
15+
|--------------------------------------------------------------------------
16+
| Symbolic path
17+
|--------------------------------------------------------------------------
18+
|
19+
| you can change the public themes path used for assets
20+
|
21+
*/
22+
'symlink_path' => 'themes',
23+
24+
/*
25+
|--------------------------------------------------------------------------
26+
| Fallback Theme
27+
|--------------------------------------------------------------------------
28+
|
29+
| If you don't set a theme at runtime (through middleware for example)
30+
| the fallback theme will be used automatically.
31+
|
32+
*/
33+
'fallback_theme' => null,
34+
];

0 commit comments

Comments
 (0)