boneybone/auditing-sdk

There is no license information available for the latest version (v1) of this package.

The Auditing SDK for IX Systems

v1 2025-11-14 15:03 UTC

Requires

• php: ^7.2|^8.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.0

Unknown License

• Rizal

README

The Auditing Platform SDK for IX Systems for immutable audit trails.

Installation

1. Install the package via Composer:

composer require boneybone/auditing-sdk

2. Publish the config file:

php artisan vendor:publish --tag=auditing-config

3. Configuring .env variables:

First you need to obtain DSN credentials from the Auditing Platform, here's how to obtain the credentials:

Once you logged in to the platform, head to the DSN page on the sidebar, and click the "+ New DSN" button, you'll be redirected to this page

Fill out the name, description & logo, and then select the buckets you want your DSN to have access to.

If you need more bucket for your DSN, click the + Add Bucket button, it will display a dialog for you to create new bucket.

Once the DSN is created, you'll be redirected to the DSN details page, where you can get your DSN Endpoint & your DSN Token.

Add the following variables to your .env file with your DSN credentials:

AUDITING_ENDPOINT_PROTOCOL=https
AUDITING_ENDPOINT=
AUDITING_DSN_TOKEN=

# use the value "queue" if you have background job queue already setup
AUDITING_TRANSPORT_METHOD=sync
AUDITING_TRANSPORT_PRIORITY=1

And once you configure everything, head back to that DSN details page, and scroll down click the Listen for Events button

Once it says Waiting for events... run this command on your terminal to authenticate the SDK:

php artisan auditing:verify

If authentication successful, then you can start using the Auditing SDK.

SDK Usage

The most basic usage is to dispatch a ResourceUpdated event, to record changes for a given model.

use Boneybone\Auditing\Facades\Auditor;

// say you're working with Business Case data.
$bc = BusinessCase::find('125f0487-8600-4d57-929b-50da9d104d20');

... another code that update the BC details


// dispatch the changes
Auditor::data($bc)->dispatch();

The code above will record changes history for that particular BC. As long as your DSN have access to the Business Case bucket, your DSN can dispatch changes for BusinessCase model.

The SDK follows Laravel naming convention on how to track Eloquent Model, as long as your model follows the convention, it will work and assign to the correct bucket automatically.

However, this SDK also support non-modeled data such as user action that's not representable by a Model, such as User Submit Approval Request, so you can do the following:

use Boneybone\Auditing\AuditEvent;
use Boneybone\Auditing\Facades\Auditor;

// Let's say this is the claim request object with ClaimRequest model.
$claimRequest = $this->submittedClaimRequest();

// dispatch claim request created event
Auditor::data($claimRequest)->event(AuditEvent::CREATE)->dispatch();

// The approval requests for the claim request
$approvalRequest = $claimRequest->approvalRequests;

// dispatch claim request approval request submitted
Auditor::bucket('claimapprovalrequests')->data([
  'requester' => $claimRequest->user,
  'claim' => $claimRequest,
  'approval_requests' => $approvalRequests
])->node($claimRequest->id)->event(AuditEvent::APPROVAL_REQUEST_SUBMITTED)->dispatch();

// then dispatch the approval request email for the first approver has been sent
Auditor::bucket('emails')->data([
  'subject' => $emailSubject,
  'claim' => $claimRequest,
  'approver' => $approvalRequests->first()->approver
])->node($claimRequest->id)->event(AuditEvent::EMAIL_SENT)->dispatch();

Then after the approver approve/reject the request, you can also dispatch the action, here's how:

use Boneybone\Auditing\AuditEvent;
use Boneybone\Auditing\Facades\Auditor;

// Let's say this is the claim request object with ClaimRequest model.
$claimRequest = $this->submittedClaimRequest();

// then dispatch approval request action approved/rejected
Auditor::bucket('claimapprovalrequestapprovals')->data([
  'claim' => $claimRequest,
  'requester' => $claimRequest->user,
  'approver' => $approvalRequests
])
->node($claimRequest->id)
->event(
  $isApproved ? AuditEvent::APPROVAL_REQUEST_APPROVED : AuditEvent::APPROVAL_REQUEST_REJECTED
)
->dispatch();

You see on the code above that the Auditor facade have a bucket(), node() and event() methods, here's what each method does:

1. Method bucket($bucketIdentifier)

This method tell the SDK to send the audit event to that bucket in the audit platform. If you're not sure what's the bucket ID, head to the Auditing Platform and go to the Bucket page from the sidebar, and you'll see the Bucket ID in the list, you can copy and use that bucket id, see screenshot below:

2. Method node($nodeId)

This method will tell the SDK to associate the Event or the Audit Trails that got sent to the Auditing Platform to your internal ID. Like the code example above, on the Claim Approval Request Submitted event, the associated ID will be the ClaimRequest ID.

Always put the main model ID for the node() so that the Auditing Platform can track every changes accurately.

3. Method event($eventType, $eventName = null)

This method will tell the SDK to sent what type of audit will be dispatched, by default the SDK will send ResourceUpdated event to mark the resource just updated.

However, you can define other type of event types, call this method to get list of available constant you can use:

use Boneybone\Auditing\AuditEvent;

AuditEvent::all();

Or if you want to send completely custom event type, use AuditEvent::CUSTOM and pass your custom event name on the second parameter like this ->event(AuditEvent::CUSTOM, 'PeopleUpdateInsurancePolicy').

Transport Methods

There are 2 transports supported by the SDK, sync & queue. The sync transport will dispatch audit logs immediately in the same request, therefore can potentially slow down your app performance.

The queue transport will put the audit event dispatching to the background job, so your main app thread will not get disrupted. To use queue transport, set this variable in your .env file:

AUDITING_TRANSPORT_METHOD=queue

And then you can dispatch your audit events as usual.

Fetching Audit History

The SDK provides a history() method to retrieve audit trails that have been dispatched to the Auditing Platform. This allows you to fetch and display historical audit events in your application.

Basic Usage

1. Fetch history for a specific model

use Boneybone\Auditing\Facades\Auditor;

$bc = BusinessCase::find('125f0487-8600-4d57-929b-50da9d104d20');
$history = Auditor::data($bc)->history();

// Fetch page 2
$history = Auditor::data($bc)->history(2);

2. Fetch all events in a bucket

use Boneybone\Auditing\Facades\Auditor;

// Get all events in the 'businesscases' bucket
$history = Auditor::bucket('businesscases')->history();

// Get page 3 of all events in the bucket
$history = Auditor::bucket('businesscases')->history(3);

3. Fetch events for a specific node ID

use Boneybone\Auditing\Facades\Auditor;

// Manually specify bucket and node ID
$history = Auditor::bucket('businesscases')->node('125f0487-8600-4d57-929b-50da9d104d20')->history();

// With pagination
$history = Auditor::bucket('businesscases')->node('125f0487-8600-4d57-929b-50da9d104d20')->history(2);