---
url: >-
  https://docs.corbitaltech.dev/products/whatsmark-saas/custom-module/getting-started.md
description: >-
  Complete guide to creating custom modules for WhatsmarkSaaS with best
  practices and examples
---

# 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.

::: info What You'll Learn
By the end of this guide, you'll be able to:

* Set up a complete custom module structure
* Implement proper service providers and configuration
* Create routes, controllers, and views
* Handle database migrations and models
* Implement security best practices
* Test your module effectively

:::

## Prerequisites

Before starting custom module development, ensure you have:

::: warning Requirements Checklist

* **WhatsmarkSaaS Platform**: Version 2.0 or higher installed and running
* **PHP Knowledge**: Familiarity with PHP 8.3 and Laravel 12+
* **Development Environment**: Local development setup with database access
  :::

## Module Architecture Overview

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

```text
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:

::: code-group

```bash [Using Artisan Command]
php artisan module:make YourModuleName
```

```text [Manual Creation]
If you prefer manual setup, create the directory structure shown above
and follow the configuration steps below.
```

:::

### Configure Module Metadata

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

```json{3-8}
{
    "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{10-25}
<?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:

* Admin routes with proper middleware
* User-facing routes
* Protected routes with authentication

### API Routes

Create `Routes/api.php` for API endpoints including:

* Public API endpoints
* Protected API routes with authentication
* Webhook endpoints (remember to exclude from CSRF)

## Step 3: Create Controllers

Create controllers in `Http/Controllers/` directory:

* **AdminController**: Handle admin functionality
* **UserController**: Handle user-facing features
* **ApiController**: Handle API requests and webhooks

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:

```bash
php artisan module:make-migration create_yourmodule_table YourModule
```

Design your database schema considering:

* Proper foreign key relationships
* Appropriate indexes for performance
* Nullable fields where needed
* JSON columns for flexible data storage

### Create Models

Create Eloquent models in the `Models/` directory:

* Define fillable attributes
* Set up model relationships
* Add custom scopes and accessors
* Implement proper data casting

## Step 5: Create Views

Create Blade templates in `Resources/views/`:

* **Admin views**: Dashboard, settings, management interfaces
* **User views**: User-facing interfaces
* **Layouts**: Extend existing layouts or create module-specific ones

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

## Step 6: Module Configuration

Create `Config/config.php` with your module settings:

* Module metadata (name, version)
* Feature flags for optional functionality
* Default configuration values
* Environment-specific settings

## Step 7: Security Implementation

### CSRF Exclusions

For webhook endpoints, add CSRF exclusions in your service provider. See the [CSRF Token Validation](./validate-csrf-token) guide for detailed implementation.

### Middleware

Create custom middleware in `Http/Middleware/` for:

* Module-specific access control
* Feature availability checks
* Request validation and transformation
* Security logging

## Step 8: Testing Your Module

Create comprehensive tests in the `Tests/` directory:

* **Feature Tests**: Test complete user workflows
* **Unit Tests**: Test individual classes and methods
* **API Tests**: Test API endpoints and responses
* **Security Tests**: Verify access controls and validation

## Step 9: Module Activation

### Enable Your Module

```bash
# Activate the module
php artisan module:enable YourModule

# Run migrations
php artisan migrate

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

### Verify Installation

```bash
# Check module status
php artisan module:list

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

## Next Steps

::: tip What's Next?

Now that you have a basic module set up, explore these advanced topics:

* [CSRF Token Validation](./validate-csrf-token) - Secure your webhook endpoints
* [Module API Development](../api/) - Build robust APIs
* Database Optimization - Improve performance
* Testing Strategies - Ensure code quality

***

Last Updated: October 2025 • Laravel Version: 12.x • WhatsmarkSaaS Module Development