altostrat/tools

Altostrat - Laravel Tooling

Installation

composer require altostrat/altostrat

Environment Variables

Add the following environment variables to your .env file:

AUTH0_CLIENT_ID=
AUTH0_COOKIE_SECRET=
API_PREFIX=

AUTH0_CLIENT_ID should be the client ID of the Altostrat Auth0 tenant application. AUTH0_COOKIE_SECRET should be a random string of at least 32 characters. API_PREFIX should be the prefix for your API routes, e.g. v1/my-service.

Installation Command

Run the following command run through some boilerplate installation steps:

php artisan altostrat:install

Afterward run the following command to verify that everything is working:

php artisan altostrat:check

Usage

Authenticated routes

Whenever you want to register a route that requires authentication, add it to the routes/authenticated.php file. This will require the user to be authenticated and have the correct scopes to access the route.

During the installation a model called Customer was created. You can use this model to create relationships with your own models. The Customer model is read-only and only acts as a way to leverage eloquent relationships.

Billable Models

When creating a billable service, commonly a particular model is used to represent the billable item. If you want to make a model billable, simply extend the model from Altostrat\Billable\BillableModel.

namespace App\Models;

use Altostrat\Billable\BillableModel;
use Illuminate\Database\Eloquent\Concerns\HasUuids;

class MyModel extends BillableModel
{
    use HasUuids;

    protected $fillable = [
        'customer_id',
    ];

    //
}

The model that you wish to make billable must have a UUID customer_id column and the id column must be a UUID.

Nothing more is needed, when a user attempts to create an item, a check will be performed to see if the user has a valid subscription. If the user is not allowed to create the item, execution will be halted and a response will be returned to the user.

WARNING: When making a model billable, only an authenticated user can create the model. That means it must come in through an authenticated route and the auth()->user() must be set. You cannot create a billable model through a job or a command.

HTTP requests only.

Helpers

The following helpers are available:

• new ipv4Address(string $address) - Creates a new IPv4Address object - use the ->withIsp() method to get the ISP name.
• IpLookup::info(string $address) - Returns an array with information about the IP address.
• Websocket::push(string $userId, string $event, array $data) - Pushes an event to the user's websocket connection.
• GeographicHelper::class - Helper class for geographic items, like a list of currencies, countries, etc.

Audit Logging

The package includes automatic audit logging that publishes audit events to AWS SNS. To enable audit logging, add the following environment variable:

AUDIT_LOG_DSN="your_aws_key:your_aws_secret@arn:aws:sns:us-east-1:123456789012:your-audit-log-topic"

DSN Format: aws_access_key:aws_secret_key@arn:aws:sns:region:account:topic-name

When enabled, the middleware will automatically capture and send the following data for each authenticated request:

• Request details (method, URI, payload, headers)
• Response details (status code, error responses)
• User context (user_id, org_id, workspace_id)
• Metadata (IP address, user agent, timestamp)

The audit logs are sent asynchronously via a queued job (PublishAuditLog) to avoid impacting request performance.

Note: Response payloads are only captured for error responses (status codes < 200 or >= 400) to minimize data volume.

Implementation Notes

Remember to ask the infrastructure team to add the prefix to the ALB with these paths:

• v1/my-service/*
• v1/my-service

Service Count Routes

Billable models are automatically made countable.

As an example, if you set the prefix to v1/my-service, the following route will be available:

GET /v1/my-service/billable-count/{model}

The model parameter is the name of the model, e.g. my-model. Model names should be converted to kebab-case. E.g. MyModel becomes my-model.

You may optionally pass the count=1 URL parameter to get the count of the model.

If count=1 is not passed, the route will return a list like this:

[
  {
    "id": "....", // The ID of the model
    "site_id": "...." // Only if the model has a site_id column otherwise this will be null
  }
]

If count=1 is passed, the route will return a count like this:

{
  "count": 1
}