[CmdletBinding()]
param(
	[Parameter(Mandatory=$true)]
	[string]$Name,
	[Parameter(Mandatory=$true)]
	[string]$List = 'Shared Documents',
	[Parameter(Mandatory=$true)]
	[string]$Owner,
	[Parameter()]
	[array]$Acl
)

<#
.SYNOPSIS
	Sets permissions on a folder in a SharePoint document library.
.DESCRIPTION
	This script breaks permission inheritance on a specified folder in a SharePoint document library and assigns permissions to a specified owner group and additional groups defined in the ACL parameter.
.PARAMETER Name
	The name of the folder to set permissions on.
.PARAMETER List
	The name of the document library containing the folder. Default is 'Shared Documents'.
.PARAMETER Owner
	The name of the SharePoint group to assign as the owner of the folder with 'Full Control' permissions.
.PARAMETER Acl
	An array of objects defining additional groups and their permissions to assign to the folder. Each object should have a 'DisplayName' property for the group name and a 'Role' property for the permission level (e.g., 'Read', 'Edit').
.EXAMPLE
	$Acl = @(
		@{ DisplayName = "SG-ADMIN-AdvocateFloats-Dynamic"; Role = "Edit" },
		@{ DisplayName = "SG-ADMIN-AdvocateManagers-Dynamic"; Role = "Edit" }
	)
	.\Set-PnPFolderAcl.ps1 -Name "ProjectX" -List "Shared Documents" -Owner "Project Owners" -Acl $Acl
#>

<#
.SYNOPSIS
	Tests if a PnP Group exists.
.DESCRIPTION
	This function tests if a PnP Group exists in the current SharePoint site.
.PARAMETER Identity
	The identity of the group to test.
.EXAMPLE
	Test-PnPGroup -Identity "MyGroup"
#>
function Test-PnPGroup {
	param(
		[string]$Identity
	)

	try {
		Get-PnPGroup -Identity $Identity -ErrorAction Stop | Out-Null
		return $true
	} catch {
		return $false
	}
}

<#
.SYNOPSIS
	Tests if an Entra ID Group exists and PnP can resolve it.
.DESCRIPTION
	This function tests if a Entra ID Group exists and can be resolved by PnP.
.PARAMETER Identity
	The identity of the group to test.
.EXAMPLE
	Test-EntraIdGroup -Identity "MyGroup"
#>
function Test-EntraIdGroup {
	param(
		[string]$Identity
	)

	try {
		Get-PnPEntraIdGroup -Identity $Identity -ErrorAction Stop | Out-Null
		return $true
	} catch {
		return $false
	}
}

# Validate that we are connected to a SharePoint site and that the specified list and owner group exist
if (-not (Get-PnPContext)) {
	Write-Error "Not connected to a SharePoint site. Please connect using Connect-PnPOnline before running this script."
	exit 1
}
if (-not (Get-PnPList -Identity $List -ErrorAction SilentlyContinue)) {
	Write-Error "The specified list '$List' does not exist on the current site."
	exit 1
}
if (-not (Test-PnPGroup -Identity $Owner)) {
	Write-Error "The specified owner group '$Owner' does not exist on the current site."
	exit 1
}

# Warning if no ACL entries are provided, as this will result in the folder having no permissions assigned
if ($Acl.Count -eq 0) {
	Write-Warning "No ACL entries provided. The folder will have no permissions assigned."
}


# Break inheritance on the location folder and set ownership
Write-Host "Breaking permission inheritance for folder '$List/$Name'."
Write-Host "Assigning 'Full Control' permissions to SharePoint group '$Owner' for folder '$List/$Name'."
Set-PnPFolderPermission -List $List -Identity "$List/$Name" -Group $Owner -AddRole 'Full Control' -ClearExisting

foreach ($Group in $Acl) {
	if (Test-PnPGroup $Group.DisplayName) {
		Write-Host "Assigning '$($Group.Role)' permissions to SharePoint group '$($Group.DisplayName)' for folder '$List/$Name'."
		Set-PnPFolderPermission -List $List -Identity "$List/$Name" -Group $Group.DisplayName -AddRole $Group.Role
	} elseif (Test-EntraIdGroup $Group.DisplayName) {
		Write-Host "Assigning '$($Group.Role)' permissions to Entra ID group '$($Group.DisplayName)' for folder '$List/$Name'."
		Set-PnPFolderPermission -List $List -Identity "$List/$Name" -User $Group.DisplayName -AddRole $Group.Role
	} else {
		Write-Warning "Group '$($Group.DisplayName)' does not exist. Skipping permission assignment."
		continue
	}
}