Clara

A module management in Laravel

System requirements

• PHP: >=5.6
• Laravel Framework: >=5.4

Installation

Clara is packed as a composer package. So it can be installed quickly:

1. Require the composer package

   composer require megaads/clara

2. Register the provider:

   Megaads\Clara\Providers\ModuleServiceProvider

3. Register the facade:

   Megaads\Clara\Facades\ModuleFacade

4. Autoloading

By default, Module classes are not loaded automatically. You can autoload your modules in composer.json

{
    "autoload": {
        "psr-4": {            
            "App\\": "app/",
            "Modules\\": "app/Modules"            
        }
    },
    "extra": {
        "merge-plugin": {
            "include": [
                "app/Modules/*/module.json"
            ]
        }
    }
}

5. Publish Clara configurations

To override Clara default configuration options, you will need to publish Clara configuration file to the application's config directory.

php artisan vendor:publish --provider="Megaads\Clara\Providers\ModuleServiceProvider"

Module Management

Create module

php artisan module:make <ModuleName> ...

Naming conventions

Module names should follow UpperCamelCase syntax (without any space characters). For example: FacebookComment

and module namespace in kebab-case that correspond to a module name in CamelCase. For example: facebook-comment

Folder structure

app
│
└───Modules
    
    └───ModuleName
        │
        └───Config
        │      app.php
        │
        └───Controllers
        │      Controller.php
        │      ...
        │
        └───Helpers
        │      helper.php
        │      ...
        │
        └───Middlewares
        │      ExampleMiddleware.php
        │      ...
        │
        └───Models
        │      ...
        │
        └───Resources
        │      Views
        │      Assets
        │      ...
        │
        └───Routes
        │      routes.php
        │      ...
        │
        └───Kernel.php
        │
        └───module.json
        │
        └───start.php

• module.json: the module configuration file is based on composer.json form. All properties in the module.json will be merged to composer.json of the project.
• start.php: the module's start file that will be loaded every requests. So module actions, module views... can be registered in this file.

Module installing

Install a module using the module name

php artisan module:install <ModuleName>

Clara takes the name of the module that requested to search for it in the app repository that you have registered in config/clara.php configuration, after downloading the module files, Clara adds the module configuration to the module.json file

Install module list from module.json

php artisan module:install

This will searches and downloads the modules listed in module.json from the app repository into the app/Modules/ directory

Install a module from a zip file or an URL

php artisan module:install <ModuleZipFilePath> <ModuleZipFileURL> ...

Enable a module

php artisan module:enable <ModuleName> ...

Disable a module

php artisan module:disable <ModuleName> ...

Remove a module

php artisan module:remove <ModuleName> ...

Remove all modules

php artisan module:remove-all

Module Action

Fire a action

Using PHP

Module::action('action_name', [params]);

Using blade statement

@action('action_name', [params])

Handle a action

Module::onAction('action_name', function ($params) {  
      
}, PRIORITY);

Handle a action using a controller

Module::onAction('action_name', 'Modules\Example\Controllers\HomeController@action', PRIORITY);

By default, Clara supplies actions:

• module_made
• module_loaded
• module_disabled
• module_enabled
• module_removed
• module_removed_all

Module View

Register a view

Using PHP

Module::view('view_name', [params], IS_MULTI_LAYER);

Module::view('view_name', 'This is a view placeholder', IS_MULTI_LAYER);

Module::view('view_name', function() {
    return 'This is a view placeholder';
}, IS_MULTI_LAYER);

Using blade statement

@view('view_name', [params])

Handle a view

Module::onView('view_name', function ($params) {  
    return view('{module-namespace}:home.index');
}, PRIORITY);

Handle a view using a controller

Module::onView('view_name', 'Modules\ExampleModule\Controllers\HomeController@index', PRIORITY);

Module variable

Register a variable

Using PHP

$variable = Module::variable('handle', $default, PRIORITY);

Using blade statement

@variable('variable_name', 'handle', $default);

Handle a variable

Module::onVariable('hanlde', function ($params) {
}, PRIORITY, NUUM_OF_PARAM);

Module Assets

Clara will create a symbol link from module asset directory app/Modules/{ModuleName}/Resources/Assets to public/modules/{module-namespace} while a module was installed, made or enabled.

Include a module asset

Using PHP

<script type="text/javascript" src="<?= Module::asset('{module-namespace}/js/demo.js') ?>"></script>

Using blade statement

<script type="text/javascript" src="@asset('{module-namespace}/js/demo.js')"></script>

Create module asset link manually

php artisan module:asset:link <ModuleName>

Create module asset link manually for all activated modules

php artisan module:asset:link --all

Module Configurations

All of the configuration files for the module are stored in the {ModuleName}/Config directory

Accessing Configuration Values

Sometimes you may need to access configuration values at run-time. You may do so using the Config class

Config::get('{module-namespace}::app.message', 'hello world');

Module Utility Methods

Get all modules

$modules = Module::all();

Get the current module

$module = Module::this();

Get module options

$option = Module::option('option.name');

Set module option

$option = Module::option('option.name', 'option.value');

License

The Clara is open-sourced software licensed under the MIT license

Contact us / Instant feedback

Email: [email protected] | [email protected]

If you find a bug, please report it here on Github