Add examples for using classes

[markhughes]

I'm finding it difficult to find any examples of how to use the internal classes outlined here. It also seems to be missing WHMCS\Database\Capsule but has what I'm looking for here (these docs seem all over the place!).

Currently I'm trying to look for a method to create an invoice with the type AddFunds. There doesn't seem to be any easy way to do this via the API or available methods.

Perhaps I can create a new invoice and use a new WHMCS\Billing\Invoice\Item class on the WHMCS\Billing\Invoice class? I can't even find information about the constructors, so these could just be 'dummy' classes for holding information. But again, there is no information available.

E.g. can I create an invoice like this:

$addFundsInvoice = new WHMCS\Billing\Invoice;
// there is no addLine()?
$addFundsLine = new WHMCS\Billing\Invoice\Item;

// ... something? 

I've done heavy research online and have been made aware of the methods like createInvoices($userid); but I feel these might be going away (are they?) because WHMCS seems to be stepping away from using functions and using classes.

This seems like a solution but it also doesn't seem like the safest way to go about it:

$userid = ...;
$amount = ...;

// I think true here = no email?
include_once(WHMCS_ROOT_PATH . "/includes/processinvoices.php");
$invoiceid = createInvoices(userid, true);

Capsule::table("tblinvoiceitems")
	->insert([
		"userid" => $userid, 
		"type" => "AddFunds", 
		"relid" => $invoiceid, 
		"description" => $_LANG['addfunds'], 
		"amount" => $amount, 
		"taxed" => "0", 
		"duedate" => "now()", 
		"paymentmethod" => "paypal"
	]);

Looking forward to some help here :)

[markhughes]

So some deeper research. Using cache'd versions of old doc pages I was able to find these:

use WHMCS\User\Client;
use WHMCS\Billing\Invoice;
	
/** @var \WHMCS\User\Client $currentUser */
$currentUser = Client::find($_SESSION['uid']);
// if you modify this you must use $currentUser->save() after

/** @var \WHMCS\Billing\Invoice $invoice */
$invoice = Invoice::find(3);
	
/** @var \Illuminate\Database\Eloquent\Collection $invoice->items() */
$invoiceItems = $invoice->items()->get();

/** @var \WHMCS\Billing\Invoice\Item $item */
foreach($invoiceItems as $item) {
	print_r($item);
}

Everything now is trial and failure. This also seems much better than using the internal API calls.

[markhughes]

For anybody trying to do something similar, this is my solution so far.

<?php
	
use Carbon\Carbon;
	
use WHMCS\Database\Capsule;
use WHMCS\User\Client;
use WHMCS\Billing\Invoice;
use WHMCS\Billing\Invoice\Item;
	
// @var \WHMCS\User\Client $currentUser 
$currentUser = Client::find($_SESSION['uid']);
	
if ($currentUser == null) {
	// not logged in
	header("Location: /");
	exit();
}
	
// this is for example purposes, you may want to do your own thing here 
$amount = 0;
if (isset($_POST["amount"])) {
	$amount = floatval($_POST["amount"]);
} else if(isset($_GET["amount"])) {
	$amount = floatval($_GET["amount"]);
} else {
	exit("no val"); 
}
	
// find gateway, defaults to paypal
// TODO: fetch default from WHMCS config
$paymentMethod = $currentUser->defaultgateway;
if ($paymentMethod == "") $paymentMethod = "paypal";

// Create invoice - I think some of these things should have defaults, but they don't
$invoice = new Invoice;
$invoice->clientId = $currentUser->id;
$invoice->dateCreated = Carbon::now()->startOfDay(); // should default to this
$invoice->dateDue = Carbon::now()->startOfDay(); // should default to this
$invoice->subtotal = $amount;
$invoice->status = "Unpaid"; // should default to this
$invoice->total = $amount;
$invoice->paymentmethod = $paymentMethod; // should default to client default

// Save it so we can have an id 
$invoice->save();

// create invoice item
$invoiceItem = new Item;
$invoiceItem->type = "AddFunds";
$invoiceItem->description = "Add Funds";
$invoiceItem->amount = $amount;
$invoiceItem->taxed = false;
$invoiceItem->userid = $currentUser->id;
$invoiceItem->invoiceid = $invoice->id;
$invoiceItem->save();
		
// TODO: not sure if this applies as we assigned it in $invoiceItem->invoiceid 
$invoice->items()->saveMany([$invoiceItem]);
$invoice->save();
	
$invoiceid = $invoice->id;
	
// We have integrations that work with invoices on creation so call this hook
run_hook("InvoiceCreated", [
	"invoiceid" => $invoiceid
]);
	
header("Location: /invoice/{$invoiceid}");

[mattpugh]

Hi there,

All of the model classes in WHMCS leverage the Eloquent ORM library, the database component from Laravel. Documentation for working with Eloquent Models can be found @ https://laravel.com/docs/5.2/eloquent

I will certainly however pass back to the team that further documentation and code examples demonstrating usage of the models would be helpful.

Matt

[markhughes]

Hey Matt, yep seems so. I've decided that I've had to build an abstract layer on-top so I can use setters/getters, and clients construct/save a bit more automatically.

Unless there are setters and getters that I can't see?

[davidneimeyer]

@markehme What type of get/set do you require? With Eloquent based models, you can get/set column specific data by referencing a like named public member, so unless you have a particular need, you can get/set already without methods.

Table Foo

ID	foo	bar
1	A	a

$model = Foo::find(1);
$model->bar = 'aaaaa';
$model->save()

$newModel = new Foo();
$newModel->foo = 'B';
$newModel->bar = 'b';
$newModel->save();

$myBar = Foo::where('foo', '=', 'A')->first()->bar; // 'aaaaa'

Update table Foo entries

ID	foo	bar
1	A	aaaaa
2	B	b

Most WHMCS models will not have the columns "fillable", so you won't just be able to pass an array of key/values to the constructor. If you really feel the need to have get/set methods (for instance, for chaining assignment or for providing your code a layer of compatibility around the db schema/WHMCS model), and want to directly extend the WHMCS models, of course this is possible: just be mindful that this could alter the behavior (and relevance) of the ORM model architecture, depending on you implementation. There are a few methods from Illuminate\Database\Eloquent\Model and kin that provide accessing, but I would suspect that you really shouldn't need to delve into that unless you are making models.

[aiso-net]

Hi there,

All of the model classes in WHMCS leverage the Eloquent ORM library, the database component from Laravel. Documentation for working with Eloquent Models can be found @ https://laravel.com/docs/5.2/eloquent

I will certainly however pass back to the team that further documentation and code examples demonstrating usage of the models would be helpful.

Matt

I had this same issue and your docs still dont provide good examples of working with WHMCS classes...example: https://docs.whmcs.com/Editing_Client_Area_Menus#Context