README

A Laravel-inspired framework for building WHMCS addon modules with modern PHP practices and a familiar structure. This framework provides a robust foundation for developing WHMCS addons with features like routing, MVC architecture, database migrations, and hooks management.

Features

MVC Architecture
Route Management
Database Migrations
Model Generation
Controller Generation
Hook System
CLI Commands
Admin & Client Area Support
Helper Functions
Resource Management (CSS, JS, Views)

Installation

Create a new directory for your addon in the WHMCS modules/addons directory:

cd modules/addons
mkdir your_addon_name
cd your_addon_name

Clone this repository:

git clone https://github.com/yourusername/wam.git .

Install dependencies:

composer install

Set up your environment:

cp .env.example .env

Configure your .env file with appropriate database settings:

DB_PREFIX=mod_youraddonname
APPENV=local

Quick Installation

Navigate to your WHMCS modules/addons directory:

cd modules/addons

Create a new addon using Composer:

composer create-project asamserver/wam your_addon_name dev-main

Command Line Interface

The framework provides a CLI tool named asam for generating various components. Here are the available commands:

Basic Commands

# Create a new addon
php asam make:addon YourAddonName

# Generate a controller
php asam make:controller Admin/DashboardController

# Create a model
php asam make:model User

# Generate a migration
php asam make:migration users

# Run migrations
php asam migrate

# Create a hook
php asam make:hook ClientLogin

# Generate web routes
php asam make:web

Directory Structure

your_addon_name/
├── app/
│   ├── Controllers/
│   ├── Models/
│   ├── Hooks/
│   ├── Dispatcher/
│   ├── Helper/
│   └── Application.php
├── database/
├── resource/
│   ├── css/
│   ├── js/
│   └── views/
├── routes/
│   └── web.php
├── storage/
│   └── logs/
└── vendor/

Creating Controllers

Controllers handle the business logic of your addon. To create a new controller:

php asam make:controller Admin/DashboardController

Example controller structure:

namespace WHMCS\Module\Addon\YourAddon\app\Controllers;

class DashboardController extends BaseController
{
    public function index(array $vars)
    {
        return $this->renderView('admin.dashboard', [
            'title' => 'Dashboard'
        ]);
    }
}

Defining Routes

Routes are defined in the routes/web.php file:

use WHMCS\Module\Addon\YourAddon\app\Controllers\Admin\DashboardController;

$this->get('/admin/dashboard', DashboardController::class, 'index');
$this->get('/client/dashboard', ClientDashboardController::class, 'index');

Working with Models

Create models to interact with your database:

php asam make:model User

Example model usage:

namespace WHMCS\Module\Addon\YourAddon\app\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected $fillable = ['name', 'email'];
}

Database Migrations

Create and run database migrations:

# Create a migration
php asam make:migration create_users_table

# Run migrations
php asam migrate

Example migration:

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class CreateUsersTable extends Migration
{
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            $table->increments('id');
            $table->string('name');
            $table->string('email');
            $table->timestamps();
        });
    }
}

Working with Hooks

Create and manage WHMCS hooks:

php asam make:hook ClientLogin

Example hook:

namespace WHMCS\Module\Addon\YourAddon\app\Hooks;

class ClientLoginHook
{
    public function handle(array $params)
    {
        // Hook logic here
    }
}

Views and Templates

Views are stored in the resource/views directory. Render views from your controllers:

public function index(array $vars)
{
    return $this->renderView('admin.dashboard', [
        'title' => 'Dashboard',
        'data' => $someData
    ]);
}

Helper Functions

The framework provides various helper functions in app/Helper/Helper.php:

// Get current client ID
$clientId = YourAddon_getClientId();

// Generate random number
$random = YourAddon_generateRandomNumber();

Best Practices

Always use namespaces as defined in the framework
Follow the MVC pattern
Use migrations for database changes
Keep controllers thin and move business logic to services
Use dependency injection where possible
Log important events using the built-in logging system

Error Handling

The framework includes built-in error handling:

try {
    // Your code here
} catch (\Exception $e) {
    $this->hooksManager->log("Error: " . $e->getMessage(), 'ERROR');
}

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Support

For support, please open an issue in the GitHub repository or contact the maintainers.

asamserver / wam

Maintainers

Details