Tenants

This page covers the Stancl\Tenancy\Tenant object. Both creating tenants and interacting with the tenant storage are covered on separate pages. This page focuses on advanced usage, which can help you with writing nicer code.

$data

An associative array that mirrors the tenant's data in the actual storage. It acts as a "cache" for tenant storage methods. When you call $tenant->get('foo'), the $data property is checked for 'foo' before trying to read from the storage. Similarly, when you call $tenant->put(), you write both to the actual storage and to the $data array.

If you try to access the tenant's properties using $tenant->foo or $tenant['foo'], those calls are redirected to the $data array.

The put() call always writes to the actual storage. If you do just:

$tenant->foo = 'bar';

The data will not be persisted until you ->save() the $tenant.

$domains

An array of domains that belong to the tenant.

You may add and remove domains using the following methods:

$tenant->addDomains(['foo.yourapp.com'])->save();
$tenant->addDomains('foo.yourapp.com')->save();
$tenant->removeDomains(['foo.yourapp.com'])->save();
$tenant->removeDomains('foo.yourapp.com')->save();

Don't forget to ->save() after modifying the domains!

run()

The $tenant->run() command lets you execute a closure inside a tenant's "environment".

$tenant->run(function ($tenant) {
    User::create(['name' => 'Admin', 'email' => '[email protected]', ...]);
});

It also lets you get data from the tenant's environment:

$tenantsUserCount = $tenant->run(function ($tenant) {
    return User::count();
});

If you need access to the tenant within the closure, it's passed as the first argument.

This feature is a safe alternative to:

tenancy()->initialize($tenant);

// make some changes

tenancy()->end();

and it also checks if tenancy was initialized. If it was, it returns to the original tenant after running the closure.

$persisted

This property says whether the model has saved to the storage yet. In other words, if it's false, it's a new instance that has not been ->save()d yet.

->save()

If no ID is set in the tenant's $data, it will be generated using the UniqueIDGenerator specified in config('tenancy.unique_id_generator').

Then, if the object has been persisted, it's updated in storage. Otherwise, it's written to storage.

->with()

You may fluently change the tenant's $data using ->with():

$tenant->with('foo', 'bar'); // equivalent to $tenant->foo = $bar

Don't forget to ->save() when you use ->with():

$tenant->with('foo', 'bar')->with('abc', 'xyz')->save();

You may also use ->with<PropertyNameInPascalCase> and it will be stored in snake case:

>>> \Tenancy::find('b07aa3b0-dc68-11e9-9352-9159b2055c42')
=> Stancl\Tenancy\Tenant {#3060
     +data: [
       "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42",
     ],
     +domains: [
       "foo.localhost",
     ],
   }
>>> \Tenancy::find('b07aa3b0-dc68-11e9-9352-9159b2055c42')
    ->withPaypalApiKey('foobar')
    ->save();

=> Stancl\Tenancy\Tenant {#3087
     +data: [
       "id" => "b07aa3b0-dc68-11e9-9352-9159b2055c42",
       "paypal_api_key" => "foobar",
     ],
     +domains: [
       "foo.localhost",
     ],
   }

These methods make the most sense (= sound the best) during tenant creation:

// $domains = ['foo.yourapp.com', 'foo.com'];
$primary_domain = $domains[0];
$id = $primary_domain . $this->randomString(24);

Tenant::new()
  ->withDomains($domains)
  ->withPaypalApiKey('defaultApiKey');
  ->withId($id)
  ->save();