Added capability to merge organisations

- Added an interface for organisation
- Added beforeDelete and beforeMerge callbacks
- Added hard/soft delete to organisations

src/Database/Models/Interfaces/OrganisationInterface.php

@@ -0,0 +1,85 @@
+<?php
+
+/*
+ * AVSDev UF Organisations (https://avsdev.uk)
+ *
+ * @link      https://git.avsdev.uk/avsdev/sprinkle-organisations
+ * @license   https://git.avsdev.uk/avsdev/sprinkle-organisations/blob/master/LICENSE.md (LGPL-3.0 License)
+ */
+
+namespace UserFrosting\Sprinkle\Organisations\Database\Models\Interfaces;
+
+use Illuminate\Database\Eloquent\Builder;
+
+/**
+ * Organisation Interface.
+ *
+ * Represents a Organisation object as stored in the database.
+ */
+interface OrganisationInterface
+{
+    /**
+     * Get a count of members within this organisation (includes admins).
+     *
+     * @return integer The number of members within the organisation.
+     */
+    public function getMemberCountAttribute();
+
+    /**
+     * Get a count of administrators within this organisation.
+     *
+     * @return integer The number of admins within the organisation.
+     */
+    public function getAdminCountAttribute();
+
+    /**
+     * Get a count of members within this organisation (excludes admins).
+     *
+     * @return integer The number of members within the organisation.
+     */
+    public function getTotalMemberCountAttribute();
+
+    /**
+     * Delete this organisation from the database, along with any linked objects.
+     *
+     * @param bool $hardDelete Set to true to completely remove the organisation and all associated objects.
+     *
+     * @return bool true if the deletion was successful, false otherwise.
+     */
+    public function delete($hardDelete = false);
+
+    /**
+     * Return this organisations's members.
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\HasMany
+     */
+    public function members();
+
+    /**
+     * Return this organisations's admins.
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\HasMany
+     */
+    public function administrators();
+
+    /**
+     * Performs tasks to be done before an organisation is merged
+     *
+     * By default, adds a new sign-in activity and updates any legacy hash.
+     *
+     * @param OrganisationInterface $target The organisation that will be merged towards.
+     * @param mixed[] $params Optional array of parameters used for this event handler.
+     *
+     * @todo Transition to Laravel Event dispatcher to handle this
+     */
+    public function beforeMerge($target, $params = []);
+
+    /**
+     * Joins the organisation's member count, so we can do things like sort, search, paginate, etc.
+     *
+     * @param Builder $query
+     *
+     * @return Builder
+     */
+    public function scopeJoinMemberCounts($query);
+}

src/Database/Models/Organisation.php

@@ -11,6 +11,7 @@ namespace UserFrosting\Sprinkle\Organisations\Database\Models;
 
 use Illuminate\Database\Capsule\Manager as DB;
 use UserFrosting\Sprinkle\Core\Database\Models\Model;
+use UserFrosting\Sprinkle\Organisations\Database\Models\Interfaces\OrganisationInterface;
 
 /**
  * Organisation Class.
@@ -26,7 +27,7 @@ use UserFrosting\Sprinkle\Core\Database\Models\Model;
  * @property timestamp $updated_at
  * @property timestamp $deleted_at
  */
-class Organisation extends Model
+class Organisation extends Model implements OrganisationInterface
 {
     /**
      * @var string The name of the table for the current model.
@@ -131,6 +132,86 @@ class Organisation extends Model
             ->withTimestamps();
     }
 
+    /**
+     * Delete this organisation from the database, along with any linked objects.
+     *
+     * @param bool $hardDelete Set to true to completely remove the organisation and all associated objects.
+     *
+     * @return bool true if the deletion was successful, false otherwise.
+     */
+    public function delete($hardDelete = false)
+    {
+        /** @var \UserFrosting\Sprinkle\Core\Util\ClassMapper $classMapper */
+        $classMapper = static::$ci->classMapper;
+
+        if ($hardDelete) {
+            static::$ci->get('organisation.beforeDelete')($this);
+
+            // Remove all member associations
+            $this->members()->detach();
+
+            // Delete the organisation
+            $result = $this->forceDelete();
+        } else {
+            // Soft delete the organisation, leaving all associated records alone
+            $result = parent::delete();
+        }
+
+        return $result;
+    }
+
+    /**
+     * Performs tasks to be done before an organisation is merged
+     *
+     * By default, adds a new sign-in activity and updates any legacy hash.
+     *
+     * @param mixed[] $params Optional array of parameters used for this event handler.
+     *
+     * @todo Transition to Laravel Event dispatcher to handle this
+     */
+    public function beforeMerge($target, $params = [])
+    {
+        /** @var \UserFrosting\Sprinkle\Core\Util\ClassMapper $classMapper */
+        $classMapper = static::$ci->classMapper;
+
+        /** @var \UserFrosting\Sprinkle\Account\Database\Models\Interfaces\UserInterface $currentUser */
+        $currentUser = static::$ci->authenticator->user();
+
+        /** @var \UserFrosting\Sprinkle\???? $activityLogger */
+        $activityLogger = static::$ci->userActivityLogger;
+
+        $logEntry = function($activityLogger, $currentUser, $user, $target) {
+            $activityLogger->info("User {$currentUser->user_name} moved user {$user->user_name} from organisation {$this->name} into {$target->name}.", [
+                'type'    => 'organisation_merge',
+                'user_id' => $currentUser->id,
+            ]);
+            $activityLogger->info("User {$user->user_name} was removed from the organisation {$this->name} by {$currentUser->user_name} during an organisation merge.", [
+                'type'    => 'group_leave',
+                'user_id' => $user->id,
+            ]);
+            $activityLogger->info("User {$user->user_name} was added to the organisation {$target->name} by {$currentUser->user_name} during an organisation merge.", [
+                'type'    => 'group_join',
+                'user_id' => $user->id,
+            ]);
+        };
+
+        // Move all the users from this organisation to the target
+        $this->members()->each(function ($user) use ($target, $activityLogger, $currentUser, $logEntry) {
+            $this->members()->detach($user); // NOTE: Should this record be retained? Or is the activity log enough of an audit?
+            $target->members()->attach($user, ['flag_admin' => false]);
+            $logEntry($activityLogger, $currentUser, $user, $target);
+        });
+        $this->administrators()->each(function ($user) use ($target, $activityLogger, $currentUser, $logEntry) {
+            $this->administrators()->detach($user); // NOTE: Should this record be retained? Or is the activity log enough of an audit?
+            $target->administrators()->attach($user, ['flag_admin' => true]);
+            $logEntry($activityLogger, $currentUser, $user, $target);
+        });
+        $this->save();
+        $target->save();
+
+        return $this;
+    }
+
     /**
      * Joins the organisation's member count, so we can do things like sort, search, paginate, etc.
      *