Brandgeo Laravel Nova Laravel Package

Getting Started

1. Install the package and confirm the client constraint resolves as expected:

   composer require a2zwebltd/brandgeo-laravel-client:"^1.0|^2.0"
   composer show a2zwebltd/brandgeo-laravel-client
   

   v1.1.0 accepts both client majors, so check which major Composer actually installed before relying on client-specific APIs.

2. Publish any package config and set credentials:

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

   Then configure the API key/base URL in .env and clear cached config:

   php artisan config:clear
   

3. Look first at:

   • config/brandgeo.php for credentials, status mappings, and badge defaults.
   • The published Blade/Filament badge component for how statuses are rendered.
   • The client’s subscription status enum/value object to see which statuses are known.

4. First use case: render the plan badge in a user profile or admin user table. For example, in Blade:

   <x-brandgeo-plan-badge :subscription="$user->subscription" />
   

   Or, if the package exposes a Filament column:

   PlanBadge::make('plan')
       ->label('Plan');
   

   The quickest validation is to render a known active status and an intentionally unknown status. v1.1.0 should show a neutral grey badge for the unknown status rather than throwing UnhandledMatchError.

Implementation Patterns

• Use the badge as a presentation component, not as business logic. Keep plan entitlements and authorization checks in your own domain layer. The badge should only display the subscription state returned by the client.

• Centralize status-to-label/color mapping. If the package allows publishing views or config, define your app’s status map once and reuse it across Blade, Filament tables, and API resources. This makes future client status additions easier to handle.

• Handle unknown statuses explicitly. v1.1.0 changes unknown statuses from an exception to a grey fallback badge. Treat that grey badge as “unknown/unsupported” and optionally log or report it:

  if ($subscription->status->isUnknown()) {
      report(new \RuntimeException("Unknown BrandGeo status: {$subscription->status}"));
  }
  

  If the client does not expose an isUnknown() helper, compare against the known status list or check the rendered badge state.

• Upgrade the client independently. Because the package supports ^1.0|^2.0, you can adopt client v2 without upgrading the badge package. Review the client’s v2 changelog for renamed statuses, new fields, or changed response shapes before switching.

• Eager-load or cache subscription data. Badges in tables can trigger repeated client calls. Resolve the subscription once per model and pass it into the badge, or cache the result for the request/page.

• Test both known and unknown statuses. Add coverage that asserts known statuses render the expected label/color and unknown statuses render the neutral grey fallback without throwing:

  $response = $this->get('/dashboard');
  $response->assertSee('Unknown');
  $response->assertStatus(200);
  

• Use the package’s extension points before forking. If badge colors or labels do not match your UI, publish the views/config and override the mapping. Only reach into the client directly if the badge component cannot express your use case.

Gotchas and Tips

• The old exception-based detection is gone. If your code caught UnhandledMatchError to detect new subscription statuses, that signal now disappears. Add logging or monitoring around unknown statuses so new upstream statuses do not silently render as grey forever.

• Grey is ambiguous. A grey badge can mean “unknown status from the API”, “missing subscription”, or “not configured”. Make sure your UI distinguishes these cases, especially in admin views.

• Composer may resolve client v2 unexpectedly. The constraint ^1.0|^2.0 permits either major. Run composer show and, if needed, pin the major explicitly in your root composer.json to avoid accidental upgrades during unrelated dependency updates.

• Config caching bites during setup. After changing BrandGeo credentials or badge configuration, run php artisan config:clear or php artisan optimize:clear.

• Do not rely on badge rendering for API health checks. A grey badge means the UI did not throw, not that the client request succeeded. Check the client response/error state separately if you need operational visibility.

• Update tests that expected a throw. Any test asserting UnhandledMatchError for unknown statuses must be rewritten to assert the grey fallback and, ideally, the logged warning.

• Custom views can lag behind package updates. If you published and modified the badge view, compare it with the v1.1.0 version to ensure the new unknown-status branch is present.

• Extension point priority: config/status mapping → published views → wrapping the component → direct client usage. Prefer the highest-level option that solves the problem so future package upgrades remain boring.