Events

The module dispatches some events at key points that can be used by developers to interfere with the data or flow. You need to create a custom event subscriber in your own code.  

EntraDestilledUsersAlter

This event is dispatched right after all data for selected properties are fetched from Entra, and placed in an array for further processing. It is useful for instance if you need more flexibility in the filtering of results (in which case you should not use the built in filters, as these are invoked later). You can also use it to add more data, then likely in combination with DrupalUserPreSave

The event has three methods:

getId:
returns the id (machine name) of the sync entity. 

getUsers:
returns the array of users and data from Entra. Data looks like this (with your selected properties)

[
  0 => [
    "givenName" => "Lynne"
    "surname" => "Robbins"
    "businessPhones" => [
      0 => "+1 412 555 0109"
    ]
    "mail" => "LynneR@ygrnv.onmicrosoft.com"
    "id" => "c8dc4d51-00e6-4fc1-8eeb-1ef17eb9b7cd"
  ]
  1 => [
    "givenName" => "Megan"
    "surname" => "Bowen"
    "businessPhones" => [
      0 => "+1 412 555 0109"
    ]
    "mail" => "MeganB@ygrnv.onmicrosoft.com"
    "id" => "61b34fb7-d476-461f-8944-b429f327542d"
  ]
]

setUsers:
sets the same array, possibly filtered by custom logic.

DrupalUserPreSave

This event is dispatched right before the new Drupal user is saved in the database, in the queueprocessor. The event has three methods:

getId:
returns the id (machine name) of the sync entity. 

getUser:
returns the user entity that is about to get created (or updated).

getData:
returns an array of data that primarily comes in from Entra. The data looks like this:
 

[
  [user] => [
    [userprincipalname] => MeganB@ygrnv.onmicrosoft.com
    [displayName] => Megan Bowen
    [givenname] => Megan
    [surname] => Bowen
    [businessphones] => [
        [0] => +1 412 555 0109
    ]
    [mobilephone] => 
    [department] => Marketing
    [mail] => MeganB@ygrnv.onmicrosoft.com
    [jobtitle] => Marketing Manager
    [officelocation] => 12/1110
    [id] => 61b34fb7-d476-461f-8944-b429f327542d
  ]
  [sync_entity_id] => demo
]

The [user] part is the user data extracted from Entra, while [sync_entity_id] is the machine name of the sync entity, and can be used to load this entity if you need some extra info from it. 

Example subscriber

Example of an event subscriber class that changes the username that gets stored in Drupal:

<?php

namespace Drupal\your_module\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Drupal\entrasync\Event\DrupalUserPreSave;

class UserEventSubscriber implements EventSubscriberInterface {

  public static function getSubscribedEvents() {
    return [
      DrupalUserPreSave::NAME => 'onUserPreSave',
    ];
  }

  public function onUserPreSave(DrupalUserPreSave $event) {
    // Check per id, unless you want the event to fire for all syncs. 
    if ($event->getId() === 'my_sync_id') {
      // Gets the user object about to be created
      $user = $event->getUser();
      // Gets the data used to create this user object
      $data = $event->getData();

      // Interferes and sets the username to something else than the standard
      // In the case of this data, it will take "MeganB@ygrnv.onmicrosoft.com"
      // and store it as "MeganB"
      $user->setUsername(strstr($data['user']['userprincipalname'], '@', true));
    }
  }
}