Laravel Themes Manager

The ThemeFinder::find() method scans the configured themes directory to identify and instantiate available theme packages. It looks for directories containing a composer.json file (up to 2 levels deep) and ignores node_modules and vendor directories.

For each discovered package, it extracts metadata from composer.json to create a Theme object. The following metadata is mapped:

• name: The unique identifier for the theme.
• version: The theme version (defaults to 0.1).
• description: A brief description of the theme.
• extra.theme.parent: The parent theme identifier.
• extra.theme: An array of additional theme configuration.
• extra.theme.screenshot: A path or URL to a theme screenshot.

The method returns an Illuminate Support\ Collection of Theme objects, keyed by the theme's name.

use Hexadog\ThemesManager\ThemeFinder;

// Returns a collection of Theme objects keyed by their name
$themes = ThemeFinder::find();

foreach ($themes as $name => $theme) {
    echo "Found theme: " . $name . " (Version: " . $theme->getVersion() . ")\n";
}

The ThemesManager class is the primary entrypoint for controlling which theme is currently active in your Laravel application. You can retrieve all available themes, check for existence, or switch the active theme.

• all(): Returns a Collection of all scanned themes.
• has(?string $name): Checks if a theme with the specified name exists.
• get(?string $name): Retrieves a specific Theme instance by name. If no name is provided, it returns all themes.
• set(string $name): Sets a new active theme. This method disables the current theme before enabling the new one. It throws a ThemeNotFoundException if the theme does not exist.
• current(): Returns the currently enabled Theme instance.
• enable(string $name, bool $withEvent = true): Enables a specific theme by name.
• disable(string $name, bool $withEvent = true): Disables a specific theme by name.

// Get all themes
$themes = $themesManager->all();

// Check if a theme exists
if ($themesManager->has('my-theme')) {
    // Switch to the theme
    $themesManager->set('my-theme');
}

// Get the currently active theme
$currentTheme = $themesManager->current();

The ThemeLoader middleware is responsible for detecting and applying the active theme to an incoming HTTP request.

Behavior:

• Exclusions: It automatically skips theme loading if the request expects JSON ($request->expectsJson()) or if the application is running in the console (app()->runningInConsole()).
• Explicit Theme: If a theme name is passed as a parameter to the middleware, it sets that theme using ThemesManager::set($theme).
• Fallback Theme: If no theme is explicitly provided, the middleware attempts to load the theme defined in the themes-manager.fallback_theme configuration key.

To use it, register the middleware in your app/Http/Kernel.php or within your route definitions.

// Example: Applying a specific theme to a route group
Route::middleware(['theme:dark'])->group(function () {
    // Routes in this group will use the 'dark' theme
});

The ThemesManager provides helper methods to generate HTML tags for assets (CSS, JS, Images) belonging to the currently active theme. This ensures that paths are correctly resolved to the theme's directory.

• asset(string $asset, bool $absolute = true): Returns the URL for a theme asset.
• style(string $asset, bool $absolute = true): Returns a <link> HTML tag for a CSS stylesheet.
• script(string $asset, string $mode = '', bool $absolute = true, string $type = 'text/javascript', string $level = 'functionality'): Returns a <script> HTML tag. Includes data-type and data-level attributes.
• image(string $asset, string $alt = '', string $class = '', array $attributes = [], bool $absolute = true): Returns an <img> HTML tag with support for alt text, classes, and custom attributes.
• mix(string $asset, string $manifestDirectory = ''): Returns the path to a versioned asset using Laravel Mix, resolved against the current theme's URL.

// CSS link tag
echo $themesManager->style('css/app.css');

// JavaScript script tag
echo $themesManager->script('js/app.js', '', true, 'module', 'core');

// Image tag
echo $themesManager->image('images/logo.png', 'Company Logo', 'img-fluid', ['id' => 'logo']);

// Laravel Mix integration
$url = $themesManager->mix('js/app.js');