Multitenancy Nova Tool Laravel Package

Getting Started

• Install via Composer:

  composer require romegadigital/multitenancy-nova-tool
  

  Version 4.0.0 is the current line and targets Nova 4, Laravel 10, and PHP 8.1+. If you are on Nova 3 / Laravel 9 / PHP 8.0, pin ^3.0 instead — the 4.x constraints are not backward compatible.
• Register the tool in app/Providers/NovaServiceProvider.php:

  public function tools()
  {
      return [
          new \RomegaDigital\MultitenancyNovaTool\MultitenancyNovaTool(),
      ];
  }
  

• Publish config (if available) to map your tenant/domain models:

  php artisan vendor:publish --provider="RomegaDigital\MultitenancyNovaTool\MultitenancyNovaToolServiceProvider"
  

• Ensure the underlying multitenancy package is installed and configured first. This tool is a UI layer; it expects a tenant model, domain model, and central/tenant database connections to already exist. Check composer.json of the tool for the exact multitenancy dependency (likely romegadigital/multitenancy or a compatible contract).
• Note the permission dependency: 4.0.0 replaced the abandoned vyuldashev/nova-permission with kiritokatklian/nova-permission (a maintained fork). If you already ship Nova permission tooling, confirm which one is installed before registering menus — see Gotchas.
• First use case: open Nova, navigate to the new “Tenants” tool/resource, create a tenant, attach a domain, and run the provided “migrate” or “provision” action. Verify the tenant database is created and migrations run.

Implementation Patterns

• Tenant lifecycle via Nova actions – Use the built-in actions to create, delete, suspend, or impersonate tenants. These typically wrap the multitenancy package’s service methods. Wire them to your own events by listening to tenant created/deleted events emitted by the underlying package.
• Custom Nova resource fields – The tool often publishes a tenant resource or allows overriding it via config. Add fields (e.g., plan, status) directly to the resource or extend it in your app. Use Nova’s fields() method to add computed fields like tenant database size.
• Domain management – Manage tenant domains from the Nova UI. For day-to-day ops, use the tool to add/remove domains and trigger SSL provisioning (if integrated with your own actions). Combine with Nova’s inline actions for quick edits.
• Central admin workflow – Keep the tool in the central (landlord) app only. Use Nova’s canSee or tool authorization to restrict access to super‑admins. The tool is not intended to run inside tenant contexts.
• Integration with existing tenant provisioning – If you already have a provisioning pipeline (e.g., jobs, events), call those from the tool’s actions. For example, override the create action to dispatch your own ProvisionTenantJob instead of the default database creation.
• Permissions wiring on 4.x – With kiritokatklian/nova-permission in the stack, gate the Tenants tool via roles/permissions rather than hard‑coded emails: seed a super-admin role, assign permissions such as view tenants / manage tenants, and check them in the tool’s canSee callback or a TenantPolicy. This is also the cleanest way to scope “who can create vs. who can only view”.
• Testing and seeding – Use the tool’s actions to run tenant migrations or seeders from the UI. For automated tests, call the underlying multitenancy package’s methods directly; the Nova tool is a UI wrapper and not test‑friendly.
• Multiple Nova panels – If you have separate Nova panels for central vs. tenant admins, register the tool only on the central panel via Nova::tools() in the appropriate NovaServiceProvider.

Gotchas and Tips

• Version matrix is narrow – 4.0.0 adds Nova 4, Laravel 10, and PHP 8.1+, but there is still no Nova 5, Laravel 11, or PHP 8.3 support. Upgrading the rest of your stack past those versions will break the tool; budget for a fork-and-patch if you need to move forward. Also confirm whether Laravel 9/PHP 8.0 were dropped in 4.0.0 by reading the composer.json constraints — the release notes advertise additions, not removals.
• Permission package swap is the real breaking change – Upgrading from 3.x swaps vyuldashev/nova-permission for kiritokatklian/nova-permission. Watch for:
  • Composer conflicts if anything else in your app (another Nova tool, a custom package) still requires vyuldashev/nova-permission. The fork typically replaces it; if not, you'll need to remove the old one explicitly.
  • Duplicate provider registration if both packages are installed — remove the old Vyuldashev\NovaPermission\NovaPermissionServiceProvider from config/app.php.
  • Config/migration naming differences between the fork and the original; re-publish and diff rather than assuming identical keys.
  • Existing roles/permissions tables and pivot data normally carry over unchanged (same schema lineage), but run migrations on a staging copy first.
• Underlying multitenancy package coupling – The tool is tightly coupled to a specific tenant model and domain model. If you use stancl/tenancy or another package, you will likely need to write an adapter or override the config to point to your models. Review the service provider bindings.
• Database connection config – The tool assumes a central connection and a tenant connection template. Ensure config/database.php has the correct tenant connection and that the tool’s config points to it. A common failure is migrations running on the central DB instead of the tenant DB.
• Tool not appearing in Nova – Clear Nova’s cache (php artisan nova:clear) and config cache (php artisan config:clear). Verify the tool is registered in the correct NovaServiceProvider and that the authenticated user passes the tool’s authorization (often viewNova plus a gate or permission check). After the permission-package swap, also clear the permission cache (php artisan permission:cache-reset, or your fork’s equivalent command) — stale permission caches are a frequent cause of “the tool vanished after upgrade”.
• Policies – The tool may not ship with policies. Create your own TenantPolicy and register it in AuthServiceProvider to control who can create/delete tenants. Use Nova’s authorizedToViewAny on the resource if you override it.
• Extension points – Publish the config to override the tenant resource class, domain model, and connection names. Publish views/assets if you need to customize the UI. The tool’s actions are often registered in a service provider; you can swap them by binding your own implementations.
• Debugging – Enable Nova’s debug mode (APP_DEBUG=true) and check storage/logs/laravel.log. If an action fails silently, wrap the underlying provisioning call in a try/catch and log the exception. Use php artisan tenancy:list (if using stancl) or the tool’s own artisan commands to inspect tenant state.
• Maintenance cadence – 4.0.0 shows the package is still receiving compatibility bumps, but releases are infrequent (previous line dates to 2023). Treat the Nova UI as a thin admin layer, keep critical provisioning logic in your own services, and consider pinning to an exact version (4.0.0) or a fork in your own VCS so an unexpected constraint change can't take down your admin panel.