Add docblocks

src/Tenant.php

@@ -7,6 +7,7 @@ namespace Stancl\Tenancy;
 use ArrayAccess;
 use Illuminate\Foundation\Application;
 use Illuminate\Support\Str;
+use Illuminate\Support\Traits\ForwardsCalls;
 use Stancl\Tenancy\Contracts\StorageDriver;
 use Stancl\Tenancy\Contracts\UniqueIdentifierGenerator;
 use Stancl\Tenancy\Exceptions\TenantStorageException;
@@ -18,7 +19,8 @@ use Stancl\Tenancy\Exceptions\TenantStorageException;
  */
 class Tenant implements ArrayAccess
 {
-    use Traits\HasArrayAccess;
+    use Traits\HasArrayAccess,
+        ForwardsCalls;
 
     /**
      * Tenant data. A "cache" of tenant storage.
@@ -53,6 +55,14 @@ class Tenant implements ArrayAccess
      */
     protected $persisted = false;
 
+    /**
+     * Use new() if you don't want to swap dependencies.
+     *
+     * @param Application $app
+     * @param StorageDriver $storage
+     * @param TenantManager $tenantManager
+     * @param UniqueIdentifierGenerator $idGenerator
+     */
     public function __construct(Application $app, StorageDriver $storage, TenantManager $tenantManager, UniqueIdentifierGenerator $idGenerator)
     {
         $this->app = $app;
@@ -61,6 +71,12 @@ class Tenant implements ArrayAccess
         $this->idGenerator = $idGenerator;
     }
 
+    /**
+     * Public constructor.
+     *
+     * @param Application $app
+     * @return self
+     */
     public static function new(Application $app = null): self
     {
         $app = $app ?? app();
@@ -73,11 +89,25 @@ class Tenant implements ArrayAccess
         );
     }
 
+    /**
+     * DO NOT CALL THIS METHOD FROM USERLAND. Used by storage
+     * drivers to create persisted instances of Tenant.
+     *
+     * @param array $data
+     * @return self
+     */
     public static function fromStorage(array $data): self
     {
         return static::new()->withData($data)->persisted(true);
     }
 
+    /**
+     * Create a tenant in a single command.
+     *
+     * @param string|string[] $domains
+     * @param array $data
+     * @return self
+     */
     public static function create($domains, array $data = []): self
     {
         return static::new()->withDomains((array) $domains)->withData($data)->save();
@@ -94,6 +124,11 @@ class Tenant implements ArrayAccess
         return $this;
     }
 
+    /**
+     * Does this model exist in the tenant storage.
+     *
+     * @return boolean
+     */
     public function isPersisted(): bool
     {
         return $this->persisted;
@@ -127,6 +162,11 @@ class Tenant implements ArrayAccess
         return $this;
     }
 
+    /**
+     * Unassign all domains from the tenant.
+     *
+     * @return self
+     */
     public function clearDomains(): self
     {
         $this->domains = [];
@@ -134,6 +174,12 @@ class Tenant implements ArrayAccess
         return $this;
     }
 
+    /**
+     * Set (overwrite) the tenant's domains.
+     *
+     * @param string|string[] $domains
+     * @return self
+     */
     public function withDomains($domains): self
     {
         $domains = (array) $domains;
@@ -143,6 +189,12 @@ class Tenant implements ArrayAccess
         return $this;
     }
 
+    /**
+     * Set (overwrite) tenant data.
+     *
+     * @param array $data
+     * @return self
+     */
     public function withData(array $data): self
     {
         $this->data = $data;
@@ -150,11 +202,21 @@ class Tenant implements ArrayAccess
         return $this;
     }
 
+    /**
+     * Generate a random ID.
+     *
+     * @return void
+     */
     public function generateId()
     {
         $this->id = $this->idGenerator->generate($this->domains, $this->data);
     }
 
+    /**
+     * Write the tenant's state to storage.
+     *
+     * @return self
+     */
     public function save(): self
     {
         if (! isset($this->data['id'])) {
@@ -188,7 +250,7 @@ class Tenant implements ArrayAccess
     }
 
     /**
-     * Unassign all domains from the tenant.
+     * Unassign all domains from the tenant and write to storage.
      *
      * @return self
      */
@@ -201,12 +263,22 @@ class Tenant implements ArrayAccess
         return $this;
     }
 
-    public function getDatabaseName()
+    /**
+     * Get the tenant's database's name.
+     *
+     * @return string
+     */
+    public function getDatabaseName(): string
     {
         return $this->data['_tenancy_db_name'] ?? ($this->app['config']['tenancy.database.prefix'] . $this->id . $this->app['config']['tenancy.database.suffix']);
     }
 
-    public function getConnectionName()
+    /**
+     * Get the tenant's database connection's name.
+     *
+     * @return string
+     */
+    public function getConnectionName(): string
     {
         return $this->data['_tenancy_db_connection'] ?? 'tenant';
     }
@@ -243,6 +315,13 @@ class Tenant implements ArrayAccess
         return $this->data[$key];
     }
 
+    /**
+     * Set a value and write to storage.
+     *
+     * @param string|array<string, mixed> $key
+     * @param mixed $value
+     * @return self
+     */
     public function put($key, $value = null): self
     {
         if ($key === 'id') {
@@ -268,6 +347,13 @@ class Tenant implements ArrayAccess
         return $this->put($key, $value);
     }
 
+    /**
+     * Set a value.
+     *
+     * @param string $key
+     * @param mixed $value
+     * @return self
+     */
     public function with(string $key, $value): self
     {
         $this->data[$key] = $value;
@@ -285,6 +371,7 @@ class Tenant implements ArrayAccess
         if ($key === 'id' && isset($this->data['id'])) {
             throw new TenantStorageException("Tenant ids can't be changed.");
         }
+
         $this->data[$key] = $value;
     }
 
@@ -294,6 +381,6 @@ class Tenant implements ArrayAccess
            return $this->with(Str::snake(substr($method, 4)), $parameters[0]);
         }
 
-        // todo throw some exception?
+        static::throwBadMethodCallException($method);
     }
 }