Croft Laravel Laravel Package

Getting Started

Start by installing the package and locating its service provider and config file:

composer require usecroft/laravel
php artisan vendor:publish --provider="Usecroft\\Laravel\\UsecroftServiceProvider"

Look first at:

1. The package config file — usually the place where global defaults, enabled environments, and registration behaviour are controlled.
2. The service provider — this is where the tool registry is bound and where you will typically register your own tools.
3. The tool contract/base class — tools are the main extension point; each tool is normally a class with a name, description, schema, and handler.

A good first use case is registering a single read-only tool, such as a lookup or reporting action, and exposing it only where it is safe:

use Usecroft\Laravel\Facades\Craft;

public function boot(): void
{
    Craft::tool(GetOrderStatus::class)
        ->when(fn () => auth()->user()?->can('viewOrders'));
}

The 0.6.0 release adds conditional tool registration, so the most valuable first experiment is to register one tool unconditionally and one behind a when() condition, then verify which tools are actually available in different contexts.

Implementation Patterns

Conditional registration by environment or permission

The main new pattern in 0.6.0 is gating tools at registration time. Use it for:

• Environment gating — expose experimental or destructive tools only in local/staging.
• Authorization gating — only expose tools the current actor is allowed to use.
• Feature-flag gating — keep tools registered but conditionally available behind a flag.
• Tenant gating — expose tenant-specific tools only when a tenant context exists.

Craft::tool(RefundOrder::class)
    ->when(fn () => app()->environment('local', 'staging'));

Craft::tool(ExportCustomerData::class)
    ->when(fn () => auth()->user()?->hasRole('admin'));

Centralise tool registration

Prefer a dedicated service provider or a small registrar class over scattering Craft::tool() calls across controllers. This keeps the tool surface discoverable and makes conditional logic auditable.

// app/Providers/CroftToolsServiceProvider.php
public function boot(): void
{
    Craft::tools([
        GetOrderStatus::class,
        SearchCustomers::class,
        RefundOrder::class,
    ]);

    Craft::tool(RefundOrder::class)
        ->when(fn () => auth()->user()?->can('refundOrders'));
}

Keep tools small and domain-oriented

Treat each tool as a thin adapter around an existing application action or query. Avoid putting business logic directly in the tool class; call an action, query object, or service instead. This makes tools easier to test and keeps conditional behaviour separate from domain behaviour.

Pair conditions with policy checks

Conditional registration controls whether a tool is advertised, not necessarily whether an action is authorised. For sensitive tools, keep an explicit authorization check inside the handler as well. Registration conditions are a UX and safety layer; policies remain the enforcement layer.

Use the Laravel upgrade example as a migration template

The 0.6.0 release includes a Laravel upgrade example. Use it when moving an existing integration between Laravel major versions to see how the package expects service provider registration, configuration publishing, and tool registration to be structured. It is documentation rather than runtime behaviour, but it is the best reference for modernising an older integration.

Testing conditional tools

Test both the condition and the tool itself. Assert that a tool is present or absent under the relevant context, then test the handler independently with a fake or mocked dependency.

$this->actingAs($admin);
$this->assertTrue(Craft::hasTool(RefundOrder::class));

$this->actingAs($customer);
$this->assertFalse(Craft::hasTool(RefundOrder::class));

If the package exposes a registry fake or assertion helpers, prefer those over inspecting internal arrays.

Gotchas and Tips

• Know when conditions are evaluated. A when() closure may run at registration, at resolution, or at request time depending on how the registry is implemented. If conditions depend on auth() or request state, confirm they are not evaluated too early during application boot or in queued jobs where no authenticated user exists.

• Avoid heavy work inside conditions. Conditions run whenever the registry resolves tools. Keep them to cheap checks such as environment, feature flags, or already-loaded user attributes. Avoid database queries inside when() unless absolutely necessary.

• Clear caches after changing registration logic. If you cache configuration, routes, or the tool registry itself, stale tools can persist after deployment. Run the relevant php artisan optimize:clear or package-specific cache command after changing conditional registration.

• Conditions are not authorization. A tool hidden by when() can still be invoked if the handler is reachable through another path. Always enforce permissions inside the tool handler or the action it calls.

• Watch service provider ordering. If conditions depend on bindings from other providers, register your tool provider after those bindings are available. This is especially relevant when following the Laravel upgrade example.

• Beware of duplicate or conflicting tool names. If two tools share a name, conditional registration can make the effective tool depend on boot order. Use explicit, namespaced names and audit the registry for collisions.

• Debug by listing registered tools. If the package provides an artisan command or registry accessor, use it to dump the effective tool list in each environment. If not, add a temporary command that resolves the registry and outputs tool names and conditions.

• Test the negative case. The most common failure mode with conditional registration is a tool remaining available when it should not be. Assert both presence and absence across roles, environments, and tenant contexts.

• Prefer explicit conditions over implicit global config. Keep environment and permission rules close to the tool registration so reviewers can see why a tool is exposed. Avoid burying availability logic in distant config files unless it is genuinely shared across many tools.

• 0.6.0 is additive. Conditional tool registration is a new feature rather than a breaking change. Existing unconditional tool registrations should continue to work, but it is worth reviewing your registry for tools that should now be gated.