README

Unofficial Laravel package for the HostFact API v3.1.

Requirements

PHP 8.4+
Laravel 13 and above (auto-discovery supported)

Installation

composer require hyperized/hostfact

Publish the configuration:

php artisan vendor:publish --provider="Hyperized\Hostfact\Providers\HostfactServiceProvider" --tag="config"

Configuration

Add these to your .env file:

HOSTFACT_URL=https://yoursite.tld/Pro/apiv2/api.php
HOSTFACT_KEY=your-api-token
HOSTFACT_TIMEOUT=20

Or edit config/Hostfact.php directly:

return [
    'api_v2_url'     => env('HOSTFACT_URL', 'https://yoursite.tld/Pro/apiv2/api.php'),
    'api_v2_key'     => env('HOSTFACT_KEY', 'token'),
    'api_v2_timeout' => env('HOSTFACT_TIMEOUT', 20),
];

Usage

Every controller provides a static new() factory that reads configuration from Laravel automatically:

use Hyperized\Hostfact\Api\Controllers\Product;
use Hyperized\Hostfact\Api\Entity\Product as ProductEntity;
use Hyperized\Hostfact\Api\Response\ListResponse;

$response = Product::new()->list(['searchfor' => 'hosting']);

if ($response instanceof ListResponse) {
    echo $response->pagination->totalResults . ' results';

    foreach ($response->entities as $product) {
        assert($product instanceof ProductEntity);
        echo $product->ProductName;
        echo $product->PriceExcl;
    }
}

For dependency injection or testing, use fromHttpClient():

use Hyperized\Hostfact\Api\Controllers\Invoice;

$invoice = Invoice::fromHttpClient($httpClient);
$result = $invoice->show(['Identifier' => 'F0001']);

See the examples/ directory for more complete usage patterns.

Typed Responses

All API methods return an ApiResponse subclass:

Response Type	When	Properties
`ShowResponse`	Single entity returned	`entity` (typed entity), `data` (DataBag)
`ListResponse`	Multiple entities returned	`entities` (list of typed entities), `items` (list of DataBag), `pagination`
`ActionResponse`	Action with no entity data (e.g. markAsPaid)	—
`ErrorResponse`	API returned an error	`errors` (list of strings)

All responses share: controller, action, status, date, isSuccess(), isError(), toArray().

Typed Entities

Responses include typed entity objects with IDE autocompletion and strict PHP types:

use Hyperized\Hostfact\Api\Controllers\Invoice;
use Hyperized\Hostfact\Api\Entity\Invoice as InvoiceEntity;
use Hyperized\Hostfact\Api\Response\ShowResponse;

$response = Invoice::new()->show(['InvoiceCode' => 'F0001']);
assert($response instanceof ShowResponse);

$invoice = $response->entity;
assert($invoice instanceof InvoiceEntity);

$invoice->Identifier;      // ?int
$invoice->InvoiceCode;     // ?string
$invoice->Status;          // ?InvoiceStatus (enum)
$invoice->Date;            // ?DateTimeImmutable
$invoice->AmountExcl;      // ?string (for bcmath precision)
$invoice->Sent;            // ?bool

// Nested entities
foreach ($invoice->InvoiceLines as $line) {
    $line->Description;    // ?string
    $line->PriceExcl;      // ?string
}

// Fallback to DataBag for undocumented fields
$invoice->bag->string('SomeUndocumentedField');

For list responses:

$response = Product::new()->list(['searchfor' => 'hosting']);
assert($response instanceof ListResponse);

foreach ($response->entities as $product) {
    assert($product instanceof ProductEntity);
    echo $product->ProductCode;
    echo $product->ProductName;
}

Available entity classes: Product, Debtor, Invoice, Domain, Hosting, Ssl, Vps, Ticket, Order, PriceQuote, Creditor, Group. Controllers without documented fields (Service, CreditInvoice, Handle) return a DataBag as the entity.

DataBag

The raw API data is also accessible through typed methods on DataBag:

$bag->string('ProductCode')        // string
$bag->int('Identifier')            // int
$bag->float('PriceExcl')           // float
$bag->bool('AutoRenew')            // bool (handles "yes"/"no", 1/0)
$bag->nullableString('Comment')    // ?string
$bag->nullableInt('PackageID')     // ?int
$bag->nullableBool('Sent')         // ?bool
$bag->nullableDateTime('Created')  // ?DateTimeImmutable
$bag->array('Groups')              // array
$bag->bag('Subscription')          // nested DataBag
$bag->bags('InvoiceLines')         // list<DataBag>
$bag->has('SomeField')             // bool
$bag['ProductCode']                // mixed (ArrayAccess)

Available Controllers

Controller	Actions
`CreditInvoice`	show, list, add, edit, delete, partialPayment, markAsPaid, lineAdd, lineDelete, attachmentAdd, attachmentDelete, attachmentDownload
`Creditor`	show, list, add, edit, delete, attachmentAdd, attachmentDelete, attachmentDownload
`Debtor`	show, list, add, edit, checkLogin, updateLoginCredentials, generatePdf, sendEmail, attachmentAdd, attachmentDelete, attachmentDownload
`Domain`	show, list, add, edit, terminate, delete, getToken, lock, unlock, changeNameserver, syncWhois, editWhois, check, transfer, register, autoRenew, listDnsTemplates, getDnsZone, editDnsZone
`Group`	show, list, add, edit, delete
`Handle`	show, list, add, edit, delete, listDomain
`Hosting`	show, list, add, edit, terminate, delete, suspend, unsuspend, create, removeFromServer, getDomainList, emailAccountData, upDowngrade
`Invoice`	show, list, add, edit, delete, credit, partialPayment, markAsPaid, markAsUnpaid, sendByEmail, sendReminderByEmail, sendSummationByEmail, download, lineAdd, lineDelete, attachmentAdd, attachmentDelete, attachmentDownload, block, unblock, schedule, cancelSchedule, paymentProcessPause, paymentProcessReactivate
`Order`	show, list, add, edit, process, lineAdd, lineDelete
`PriceQuote`	show, list, add, edit, delete, sendByEmail, download, accept, decline, lineAdd, lineDelete, attachmentAdd, attachmentDelete, attachmentDownload
`Product`	show, list, add, edit, delete
`Service`	show, list, add, edit, terminate
`Ssl`	show, list, add, edit, terminate, request, markAsInstalled, download, reissue, renew, getStatus, resendApproverEmail, revoke, markAsUninstalled
`Ticket`	show, list, add, edit, delete, addMessage, changeStatus, changeOwner, attachmentDownload
`Vps`	show, list, add, edit, terminate, create, start, pause, restart, suspend, unsuspend, downloadAccountData, emailAccountData

Design

This package provides a thin wrapper around the HostFact API. It does not validate input parameters. Consult the HostFact API documentation for accepted parameters.

Architecture:

Controllers extend the abstract Api class and compose capability traits (e.g., CanShow, CanList, CanAdd)
Each controller implements a corresponding interface
All API methods accept array<string, mixed> and return typed ApiResponse subclasses
HTTP transport is handled by Guzzle 7.x

Testing

# Full test suite (PHPMD, PHPStan, PHPCS, phpmnd, PHPUnit, Infection)
composer test

# PHPUnit only
composer phpunit -- --configuration phpunit.xml.dist

# Static analysis
composer phpstan -- analyse

License

MIT - see LICENSE for details.

hyperized / hostfact

Maintainers

Package info

Statistics

Security