README

CMS personnel

Required

Composer
PHP >= 8.1
Laravel >= 10

Installation

Require this package with composer.

composer require goldenscarab/modulus2

Laravel 9 uses autoload files, so doesn't require you to manually add the ServiceProvider.

Publishing

php artisan vendor:publish --provider="Goldenscarab\Modulus\App\Providers\PublishesServiceProvider" --force
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"

Installing front dependencies

bash vendor/goldenscarab/modulus2/assets_install.sh

Configuration assets

Replace require('./bootstrap') in file resources/js/app.js by

import './modulus.js'

Add in file resources/css/app.css (create file if necessary)

@import "./modulus.css"

Update your vite.config.js with

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue'
import path from "path";

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        vue()
    ],
    resolve: {
        alias: {
            "~": path.resolve("node_modules"),
            "@resources": path.resolve("resources"),
            "@vendor": path.resolve("vendor"),
            "@modulus": path.resolve("vendor/goldenscarab/modulus2"),
            "@theme": path.resolve("vendor/goldenscarab/modulus2/src/resources/theme/architectui")
        },
    },
    build: {
        //sourcemap: true,
    },
});

Compile assets

npm run dev

Configuration

Fichier modulus.php

Éditer le fichier config/modulus.php comme dans l'exemple :

<?php

return [

    /**
     * Classe définissant la couleur du bandeau haut
     * default: bg-focus header-text-light
     * background: bg-primary, bg-secondary, bg-success, bg-info, bg-warning, bg-danger, bg-light, bg-dark, bg-focus, bg-alternate
     * text: header-text-light, header-text-dark
     */
    'color_header' => 'bg-focus header-text-light',

    /**
     * Classe definissant la couleur du menu
     * default: bg-dark sidebar-text-light
     * background: bg-primary, bg-secondary, bg-success, bg-info, bg-warning, bg-danger, bg-light, bg-dark, bg-focus, bg-alternate
     * text: sidebar-text-light, sidebar-text-dark
     */
    'color_sidebar' => 'bg-dark sidebar-text-light',

    /**
     * Icone du nom de l'application
     * default: <i class="fa fa-puzzle-piece align-middle"></i>
     */
    'app_icon' => '<i class="fa fa-puzzle-piece align-middle"></i>',

    /**
     * Nom de l'application
     * default: <b>M</b>odulus
     */
    'app_name' => '<b>M</b>odulus',

    /**
     * Préfixe des url de Modulus
     * default: /backend
     */
    'url_prefix' => '/',

    /**
     * Namespace des constroleurs à surcharger
     * default: Goldenscarab\\Modulus\\App\\Http\\Controllers\\App\\DashboardController@index
     * - DashboardController
     * - App\\Http\\Controllers\\DashboardController@index
     */
    'dashboard_action' => 'App\\Http\\Controllers\\HomeController@index',

    /**
     * Menu à afficher dans l'interface
     *
     * Constuction :
     *  - Nom du groupe
     *      - Element 1
     *          - Sous élement 1.1
     *          - Sous élement 1.2
     *          - Sous élement 1.3
     *      - Element 2
     *          - Sous élement 2.1
     *          - Sous élement 2.2
     *          - Sous élement 2.3
     *
     * Exemple :
     *  'menu' => [
     *   [
     *       'name' => 'Group',
     *       'items' => [
     *           [
     *               'icon' => 'pe-7s-home',
     *               'name' => 'Menu name',
     *               'subitems' => [
     *                    [ 'name' => 'Item 1', 'route' => 'test.item'],
     *                    [ 'name' => 'Item 2', 'link' => '/'],
     *                    [ 'name' => 'Item 3', 'route' => 'test.item'],
     *                ]
     *           ]
     *       ]
     *   ],
     */
    'menu' => [
        [
            "items" => [
                [
                    "icon" => "pe-7s-home",
                    "name" => "Tableau de bord",
                    "url" => "/"
                ]
            ]
        ],
        [
            "items" => [
                [
                    "icon" => "pe-7s-diamond",
                    "name" => "Test",
                    "subitems" => [
                        [ 'name' => 'Item 1', 'route' => 'private.test.foos.index'],
                    ]
                ]
            ]
        ]
    ],

    /**
     * Message du footer
     */
    'msg_footer_right' => 'La simplicité dans le sur mesure',
    'msg_footer_left' => '<strong>Copyright &copy; ' .  date('Y')  . ' <a href="https://www.goldenscarab.fr" target="_blanc">Goldenscarab.</a></strong>&nbsp;All rights reserved.',

    'hashids_salt' => env('HASHIDS_SALT', 'modulus'),
    'hashids_length' => env('HASHIDS_LENGTH', 16),
];

Routes

Vous pouvez personnaliser l'url de base d'accès à Modulus, depuis le fichier de config config/modulus.php. Si vous souhaitez personnaliser l'URL de Modulus à la racine du nom de domaine, penser à nettoyer la route par défaut du fichier routes/web.php

Vous pouvez aussi personnaliser le Tableau de Bord en changeant le paramètre namespace_custom du fichier config/modulus.php Ainsi vous redirigez la route DashboardController@index vers le namespace de votre choix. Exemple :

php artisan make:controller DashboardController

Dans le fichier config/modulus.php

'dashboard_action' => 'App\\Http\\Controllers\\DashboardController@index',

Il ne reste plus qu'à personnaliser la methode index du controller fraichement créé pour afficher un nouveau Dashboard. App\Http\Controller\DashboardController@index

public function index()
{
    $breadcrumb = [
        '<i class="fa fa-home me-2"></i> Accueil' => '#'
    ];

    return Inertia::render('Dashboard')->with([
        'page_title'    => 'Tableau de bord',
        'page_subtitle' => 'Test',
        'page_icon'     => 'pe-7s-home',
        'breadcrumb'    => $breadcrumb
    ]);
}

Pour la vue, vous pouvez utilisez le modèle suivant :

<template>
    <div>
        <h1>Mon dashboard ici</h1>
    </div>
</template>

Insomnia

Installation du middleware

php artisan inertia:middleware

// App\Http\Middleware\HandleInertiaRequests
protected $rootView = 'modulus::app';

Middlewares

Ajouter au fichier app/Http/Kernel.php :

dans la variable $middlewareGroups > 'web', la ligne suivante :

\App\Http\Middleware\HandleInertiaRequests::class,

dans la variable $middlewareAliases, les lignes suivantes :

/* Middlewares ajoutés */
'auth.active' => \Goldenscarab\Modulus\App\Http\Middleware\RedirectIfNotActive::class,
'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,

App

Éditer le fichier .env à la racine de l'application pour y configurer l'accès à la base de données

Migrations

Après avoir configuré l'accès à la base de données, il est temps de créer les tables et de peubler avec les premières données la base de données

php artisan migrate --seed

Modules

Vous pouvez créer votre application sous forme de modules. Un exemple de module se trouve dans le dossier /Modules

Pour permettre l'auto-chargement des classes des modules, il est néccessaire le modifier le fichier composer.json comme ci-dessous :

{
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Modules\\": "Modules/"
        }
    }
}

Authentification

Afin de permettre un fonctionnement normal des API, il est necessaire de décommenter la ligne suivante dans le fichier Kernel.php

'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class, // Sanctum
    \Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],

Si des erreur 401 ou 403 surviennent, verifier les points suivants :

APP_URL dans le fichier .env contient la bonne URL avec le bon PORT
Les migrations ont bien été faites avec les seeders : php artisan migrate --seed

JWT

Deux attributs doivent être ajoutés dans le fichier .env

JWT_SECRET=secret
JWT_EXPIRATION=7200

Eviter les erreurs 429 (Too Many Request)

Editer le fichier Kernel.php Dans $middlewareGroups, remplacer \Illuminate\Routing\Middleware\ThrottleRequests::class.':api' par \Goldenscarab\Modulus\App\Http\Middleware\ModulusThrottleMiddleware::class.':api'

protected $middlewareGroups = [
    'web' => [
        //...
    ],

    'api' => [
        //...
        //\Illuminate\Routing\Middleware\ThrottleRequests::class.':api',
        \Goldenscarab\Modulus\App\Http\Middleware\ModulusThrottleMiddleware::class.':api',
    ],
];

Vous pouvez ensuite personnaliser le api_max_rate depuis le fichier de config : modulus.php

Visualisation des exceptions dans Modulus

Ajouter dans le fichier \App\Exceptions\Handler.php les lignes suivante, dans la méthode register :

    ...
    /**
     * Register the exception handling callbacks for the application.
     */
    public function register(): void
    {
        $this->reportable(function (Throwable $e) {
            try {
                ModulusException::store($e);
            } catch (Exception $e) {

            }
        });
    }
    ...

Security

If you discover any security related issues, please email contact@goldenscarab.fr instead of using the issue tracker.

Credits

Sylvain CARRE

License

The MIT License (MIT). Please see License File for more information.

goldenscarab / modulus2

Maintainers

Details