Custom Module BETA Version

Getting Started with Custom Module Development

Welcome to WhatsmarkSaaS custom module development! This comprehensive guide will walk you through creating powerful, maintainable modules that extend your WhatsmarkSaaS platform with custom functionality.

What You'll Learn

By the end of this guide, you'll be able to:

Prerequisites

Before starting custom module development, ensure you have:

Requirements Checklist

Module Architecture Overview

WhatsmarkSaaS modules follow a structured architecture that ensures maintainability and compatibility:

Modules/YourModule/
├── Config/
│   └── config.php
├── Database/
│   ├── Migrations/
│   └── Seeders/
├── Http/
│   ├── Controllers/
│   ├── Middleware/
│   └── Requests/
├── Providers/
│   └── YourModuleServiceProvider.php
├── Resources/
│   ├── assets/
│   ├── lang/
│   └── views/
├── Routes/
│   ├── web.php
│   └── api.php
├── Tests/
├── composer.json
└── module.json

Step 1: Create Your First Module

Generate Module Structure

Use the built-in module generator to create your module skeleton:

Using Artisan CommandManual Creation

php artisan module:make YourModuleName

Configure Module Metadata

Edit the module.json file to define your module's metadata:

{
    "name": "YourModule",
    "alias": "yourmodule",
    "description": "Your module description",
    "keywords": ["whatsmarksaas", "module", "your-feature"],
    "version": "1.0.0",
    "active": 1,
    "order": 1,
    "providers": [
        "Modules\\YourModule\\Providers\\YourModuleServiceProvider"
    ],
    "files": []
}

Set Up Service Provider

Create your module's service provider in Providers/YourModuleServiceProvider.php:

<?php

namespace Modules\YourModule\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Database\Eloquent\Factory;

class YourModuleServiceProvider extends ServiceProvider
{
    protected string $moduleName = 'YourModule';
    protected string $moduleNameLower = 'yourmodule';

    public function boot(): void
    {
        $this->registerTranslations();
        $this->registerConfig();
        $this->registerViews();
        $this->loadMigrationsFrom(module_path($this->moduleName, 'Database/Migrations'));
    }

    public function register(): void
    {
        $this->app->register(RouteServiceProvider::class);

        // Register module config
        $this->mergeConfigFrom(
            module_path($this->moduleName, 'Config/config.php'), $this->moduleNameLower
        );
    }

    protected function registerConfig(): void
    {
        $this->publishes([
            module_path($this->moduleName, 'Config/config.php') => config_path($this->moduleNameLower . '.php'),
        ], 'config');
    }

    protected function registerViews(): void
    {
        $viewPath = resource_path('views/modules/' . $this->moduleNameLower);
        $sourcePath = module_path($this->moduleName, 'Resources/views');

        $this->publishes([
            $sourcePath => $viewPath
        ], ['views', $this->moduleNameLower . '-module-views']);

        $this->loadViewsFrom(array_merge($this->getPublishableViewPaths(), [$sourcePath]), $this->moduleNameLower);
    }

    protected function registerTranslations(): void
    {
        $langPath = resource_path('lang/modules/' . $this->moduleNameLower);

        if (is_dir($langPath)) {
            $this->loadTranslationsFrom($langPath, $this->moduleNameLower);
            $this->loadJsonTranslationsFrom($langPath);
        } else {
            $this->loadTranslationsFrom(module_path($this->moduleName, 'Resources/lang'), $this->moduleNameLower);
            $this->loadJsonTranslationsFrom(module_path($this->moduleName, 'Resources/lang'));
        }
    }

    private function getPublishableViewPaths(): array
    {
        $paths = [];
        foreach (config('view.paths') as $path) {
            if (is_dir($path . '/modules/' . $this->moduleNameLower)) {
                $paths[] = $path . '/modules/' . $this->moduleNameLower;
            }
        }
        return $paths;
    }
}

Step 2: Configure Routes

Web Routes

Create Routes/web.php for your module's web routes. This file should contain:

API Routes

Create Routes/api.php for API endpoints including:

Step 3: Create Controllers

Create controllers in Http/Controllers/ directory:

Ensure controllers follow Laravel conventions and keep them slim by moving business logic to service classes.

Step 4: Database Integration

Create Migrations

Generate migrations for your module:

php artisan module:make-migration create_yourmodule_table YourModule

Design your database schema considering:

Create Models

Create Eloquent models in the Models/ directory:

Step 5: Create Views

Create Blade templates in Resources/views/:

Ensure views follow your application's design system and accessibility standards.

Step 6: Module Configuration

Create Config/config.php with your module settings:

Step 7: Security Implementation

CSRF Exclusions

For webhook endpoints, add CSRF exclusions in your service provider. See the CSRF Token Validation guide for detailed implementation.

Middleware

Create custom middleware in Http/Middleware/ for:

Step 8: Testing Your Module

Create comprehensive tests in the Tests/ directory:

Step 9: Module Activation

Enable Your Module

# Activate the module
php artisan module:enable YourModule

# Run migrations
php artisan migrate

# Publish assets (if any)
php artisan module:publish YourModule

Verify Installation

# Check module status
php artisan module:list

# Test module routes
php artisan route:list | grep yourmodule