### Project Setup and Testing

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Instructions for cloning the repository, installing dependencies with Composer, and running unit tests using PHPUnit.

```bash
git clone https://github.com/php-mime-mail-parser/php-mime-mail-parser
cd php-mime-mail-parser
composer install
./vendor/bin/phpunit
```

--------------------------------

### ADLDAP2 Basic Setup and Raw Connection Examples

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/setup.md

Demonstrates initializing ADLDAP2, adding a provider configuration, connecting, and performing raw LDAP operations such as search, add, modify batch, and delete.

```php
$ad = new Adldap\Adldap();

$config = ['...'];

$ad->addProvider($config);

$provider = $ad->connect();

$rawConnection = $provider->getConnection();

// Performing a raw search.
$result = $rawConnection->search($basedn = 'dc=corp,dc=acme,dc=org', $filter = "cn=johndoe", $selectedAttributes = ['cn', 'department']);

$dn = "cn=John Smith,ou=Wizards,dc=example,dc=com";

// Adding a new LDAP record.
$result = $rawConnection->add($dn, $entry);

// Batch modifying an LDAP record.
$modifs = [
    [
        "attrib"  => "telephoneNumber",
        "modtype" => LDAP_MODIFY_BATCH_ADD,
        "values"  => ["+1 555 555 1717"],
    ],
];

$result = $rawConnection->modifyBatch($dn, $modifs);

// Deleting an LDAP record.
$result = $rawConnection->delete($dn);

// .. etc
```

--------------------------------

### Install TwoFactorAuth with Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/robthree/twofactorauth/docs/getting-started.md

Install the library using Composer. Use the first command if you have composer.phar and the second if composer is installed globally.

```bash
php composer.phar require robthree/twofactorauth
```

```bash
composer require robthree/twofactorauth
```

--------------------------------

### Install Carbon with Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/nesbot/carbon/readme.md

Installs the Carbon library using Composer. Ensure you have Composer installed and configured.

```bash
$ composer require nesbot/carbon
```

```json
{
    "require": {
        "nesbot/carbon": "^2.16"
    }
}
```

--------------------------------

### Install Keycloak OAuth 2.0 Provider

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/stevenmaguire/oauth2-keycloak/README.md

Install the package using Composer.

```bash
composer require stevenmaguire/oauth2-keycloak
```

--------------------------------

### Install getallheaders for PHP >= 5.6

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/ralouphie/getallheaders/README.md

Use this command to install the library for PHP versions 5.6 and newer.

```bash
composer require ralouphie/getallheaders
```

--------------------------------

### Install PHP IMAP Library with Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/ddeboer/imap/README.md

Use Composer to install the library. Ensure you have Composer installed globally.

```bash
$ composer require ddeboer/imap
```

--------------------------------

### Install bacon/bacon-qr-code Library

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/robthree/twofactorauth/docs/qr-codes/bacon.md

Use Composer to install version 2 or later of the bacon/bacon-qr-code library. Ensure the PHP imagick extension is installed if you plan to use formats other than SVG.

```bash
composer require bacon/bacon-qr-code ^2.0
```

--------------------------------

### Install getallheaders for PHP < 5.6

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/ralouphie/getallheaders/README.md

Use this command to install version 2 of the library for PHP versions older than 5.6.

```bash
composer require ralouphie/getallheaders "^2"
```

--------------------------------

### Install endroid/qr-code

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/robthree/twofactorauth/docs/qr-codes/endroid.md

Install the endroid/qr-code library version 3 and its dependencies using Composer. Ensure the PHP gd extension is installed.

```bash
composer require endroid/qr-code ^3.0
```

--------------------------------

### Install mailparse Extension on Windows

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Install the mailparse extension on Windows by downloading the DLL and configuring php.ini.

```ini
extension=php_mailparse.dll
```

--------------------------------

### Install mailparse Extension from Source

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Compile and install the mailparse extension from source. This involves cloning the repository, configuring, compiling, and manually placing the module.

```bash
git clone https://github.com/php/pecl-mail-mailparse.git
cd pecl-mail-mailparse
phpize
./configure
sed -i 's/#if\s!HAVE_MBSTRING/#ifndef MBFL_MBFILTER_H/' ./mailparse.c
make
sudo mv modules/mailparse.so /usr/lib/php/AAAAMMDD/
echo "extension=mailparse.so" | sudo tee /etc/php/7.1/mods-available/mailparse.ini
sudo phpenmod mailparse
```

--------------------------------

### Install mailparse Extension on Debian/Ubuntu

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Install the mailparse PHP extension on Debian-based systems using apt.

```bash
sudo apt install php-cli php-mailparse
```

--------------------------------

### Install GuzzleHttp PSR-7

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/guzzlehttp/psr7/README.md

Use Composer to install the guzzlehttp/psr7 package.

```shell
composer require guzzlehttp/psr7
```

--------------------------------

### HTML Input Example

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/soundasleep/html2text/README.md

This is an example of HTML content that will be processed by the html2text library.

```html
<html>
<title>Ignored Title</title>
<body>
  <h1>Hello, World!</h1>

  <p>This is some e-mail content.
  Even though it has whitespace and newlines, the e-mail converter
  will handle it correctly.

  <p>Even mismatched tags.</p>

  <div>A div</div>
  <div>Another div</div>
  <div>A div<div>within a div</div></div>

  <a href="http://foo.com">A link</a>

</body>
</html>
```

--------------------------------

### Install Guzzle using Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/guzzlehttp/guzzle/README.md

The recommended method for installing Guzzle is through Composer. This command adds Guzzle to your project's dependencies.

```bash
composer require guzzlehttp/guzzle
```

--------------------------------

### Install sodium_compat for Older PHP Versions

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/firebase/php-jwt/README.md

Optionally, install the paragonie/sodium_compat package if your PHP version is less than 7.2 or lacks libsodium support.

```bash
composer require paragonie/sodium_compat
```

--------------------------------

### Install mailparse Extension via PECL

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Install the mailparse PHP extension on other platforms using PECL. Ensure necessary development packages are installed.

```bash
sudo apt install php-cli php-pear php-dev php-mbstring
pecl install mailparse
```

--------------------------------

### Install PHPMailer with Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/phpmailer/phpmailer/README.md

Use Composer to add PHPMailer to your project dependencies. This is the recommended installation method.

```json
{
    "phpmailer/phpmailer": "^6.5"
}
```

--------------------------------

### Plain Text Output Example

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/soundasleep/html2text/README.md

This is the expected plain text output after processing the example HTML with the html2text library.

```text
Hello, World!

This is some e-mail content. Even though it has whitespace and newlines, the e-mail converter will handle it correctly.

Even mismatched tags.
A div
Another div
A div
within a div
[A link](http://foo.com)
```

--------------------------------

### Install Adldap2 with Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/installation.md

Run this command in your project's root directory to install the Adldap2 package via Composer.

```bash
composer require adldap2/adldap2
```

--------------------------------

### Install PHP MIME Mail Parser via Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Use Composer to install the latest version of the PHP MIME Mail Parser library.

```bash
composer require php-mime-mail-parser/php-mime-mail-parser
```

--------------------------------

### Get User Information

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve general information about the user.

```php
// Get the users info.
$user->getInfo();

```

--------------------------------

### Install PHP-JWT with Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/firebase/php-jwt/README.md

Use Composer to add the PHP-JWT library to your project dependencies.

```bash
composer require firebase/php-jwt
```

--------------------------------

### Get Model Converted GUID

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/model.md

Fetches the Globally Unique Identifier (GUID) of a model and returns it as a string using `getConvertedGuid()`.

```php
// Returns the model's GUID in a string.
$model->getConvertedGuid();
```

--------------------------------

### Get Model Object GUID in Binary

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/model.md

Fetches the Globally Unique Identifier (GUID) of a model in its raw binary format using `getObjectGuid()`.

```php
// Returns the model's GUID in binary.
$model->getObjectGuid();
```

--------------------------------

### Retrieve a Specific Mailbox

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/ddeboer/imap/README.md

Get a specific mailbox by its name, for example, 'INBOX'.

```php
$mailbox = $connection->getMailbox('INBOX');
```

--------------------------------

### Connect and Authenticate

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/ddeboer/imap/README.md

Demonstrates how to establish a connection to an IMAP server and authenticate using provided credentials. It also shows how to configure the server with custom ports, flags, and parameters.

```APIDOC
## Connect and Authenticate

### Description
Establishes a connection to an IMAP server and authenticates the user.

### Usage
```php
use Ddeboer\Imap\Server;

$server = new Server('imap.gmail.com');

// $connection is instance of \Ddeboer\Imap\Connection
$connection = $server->authenticate('my_username', 'my_password');
```

### Server Configuration
Allows specifying port, flags, and parameters for the server connection.

```php
$server = new Server(
    $hostname, // required
    $port,     // defaults to '993'
    $flags,    // defaults to '/imap/ssl/validate-cert'
    $parameters
);
```
```

--------------------------------

### Install Symfony Translation Component

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/symfony/translation/README.md

Use Composer to require the Symfony Translation component for your project.

```bash
$ composer require symfony/translation
```

--------------------------------

### Composer Installation Configuration

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/soundasleep/html2text/README.md

Add this JSON configuration to your composer.json file to include the html2text package in your project.

```json
{
  "require": {
    "soundasleep/html2text": "~0.5"
  }
}
```

--------------------------------

### Basic Request and Response Handling in PHP

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/guzzlehttp/guzzle/README.md

Demonstrates how to create a Guzzle client, send a GET request, and access response details like status code, headers, and body. Also shows how to handle asynchronous requests and wait for their completion.

```php
$client = new \GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.github.com/repos/guzzle/guzzle');

echo $response->getStatusCode(); // 200
echo $response->getHeaderLine('content-type'); // 'application/json; charset=utf8'
echo $response->getBody(); // '{"id": 1420053, "name": "guzzle", ...}'

// Send an asynchronous request.
$request = new \GuzzleHttp\Psr7\Request('GET', 'http://httpbin.org');
$promise = $client->sendAsync($request)->then(function ($response) {
    echo 'I completed! ' . $response->getBody();
});

$promise->wait();
```

--------------------------------

### Promise Creation and Basic Usage

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/guzzlehttp/promises/README.md

Demonstrates how to create a new Promise object with optional wait and cancel functions, and how to resolve and wait for its completion.

```APIDOC
## Promise

### Description

When creating a promise object, you can provide an optional `$waitFn` and `$cancelFn`. `$waitFn` is a function that is invoked with no arguments and is expected to resolve the promise. `$cancelFn` is a function with no arguments that is expected to cancel the computation of a promise. It is invoked when the `cancel()` method of a promise is called.

### Method

`new Promise(callable $onFulfilled = null, callable $onRejected = null)`

### Parameters

#### Constructor Parameters

- **`$onFulfilled`** (callable) - Optional. A function invoked to resolve the promise.
- **`$onRejected`** (callable) - Optional. A function invoked to cancel the promise computation.

### Request Example

```php
use GuzzleHttp\Promise\Promise;

$promise = new Promise(
    function () use (&$promise) {
        $promise->resolve('waited');
    },
    function () {
        // do something that will cancel the promise computation (e.g., close
        // a socket, cancel a database query, etc...)
    }
);

assert('waited' === $promise->wait());
```
```

--------------------------------

### Find and Get Computer Properties

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/computer.md

Demonstrates how to find a computer by its name and retrieve various properties like operating system, version, service pack, DNS hostname, and logon/logoff timestamps.

```php
$computer = $provider->search()->computers()->find('ACME-EXCHANGE');

// Returns 'Windows Server 2003'
$computer->getOperatingSystem();

// Returns '5.2 (3790)';
$computer->getOperatingSystemVersion();

// Returns 'Service Pack 1';
$computer->getOperatingSystemServicePack();

// Returns 'ACME-DESKTOP001.corp.acme.org'
$computer->getDnsHostName();

$computer->getLastLogOff();

$computer->getLastLogon();

$computer->getLastLogonTimestamp();
```

--------------------------------

### Creating a New User

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Demonstrates the process of constructing and saving a new user account, including setting the distinguished name, account name, common name, password, and account control settings.

```APIDOC
## Creating a New User

> **Note**: If you need to create users with passwords, SSL or TLS **must** be enabled on your configured connection.
> 
> The password you enter for the user **must** also obey your LDAP servers password requirements, otherwise you will receive a "Server is unwilling to perform" LDAP exception upon saving.

```php
// Construct a new User model instance.
$user = $provider->make()->user();

// Create the users distinguished name.
// We're adding an OU onto the users base DN to have it be saved in the specified OU.
$dn = $user->getDnBuilder()->addOu('Users'); // Built DN will be: "CN=John Doe,OU=Users,DC=acme,DC=org";

// Set the users DN, account name.
$user->setDn($dn);
$user->setAccountName('jdoe');
$user->setCommonName('John Doe');

// Set the users password.
// NOTE: This password must obey your AD servers password requirements
// (including password history, length, special characters etc.)
// otherwise saving will fail and you will receive an
// "LDAP Server is unwilling to perform" message.
$user->setPassword('correct-horse-battery-staple');

// Get a new account control object for the user.
$ac = $user->getUserAccountControlObject();

// Mark the account as enabled (normal).
$ac->accountIsNormal();

// Set the account control on the user and save it.
$user->setUserAccountControl($ac);

// Save the user.
$user->save();

// All done! An enabled user will be created and is ready for use.
```
```

--------------------------------

### Where Starts With

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/searching.md

Filter results where an attribute starts with a specific value using 'starts_with' or the `whereStartsWith()` method.

```php
$results = $provider->search()->where('cn', 'starts_with', 'John')->get();
```

```php
$results = $provider->search()->whereStartsWith('cn', 'John')->get();
```

--------------------------------

### ADLDAP2 Configuration Array With All Options

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/setup.md

A comprehensive PHP array example demonstrating all available configuration options for ADLDAP2, including mandatory and optional settings, schema, account prefixes/suffixes, port, and custom LDAP options.

```php
// Create the configuration array.
$config = [
    // Mandatory Configuration Options
    'hosts'            => ['corp-dc1.corp.acme.org', 'corp-dc2.corp.acme.org'],
    'base_dn'          => 'dc=corp,dc=acme,dc=org',
    'username'         => 'admin',
    'password'         => 'password',

    // Optional Configuration Options
    'schema'           => Adldap\Schemas\ActiveDirectory::class,
    'account_prefix'   => 'ACME-',
    'account_suffix'   => '@acme.org',
    'port'             => 389,
    'follow_referrals' => false,
    'use_ssl'          => false,
    'use_tls'          => false,
    'version'          => 3,
    'timeout'          => 5,

    // Custom LDAP Options
    'custom_options'   => [
        // See: http://php.net/ldap_set_option
        LDAP_OPT_X_TLS_REQUIRE_CERT => LDAP_OPT_X_TLS_HARD
    ]
];
```

--------------------------------

### Create and Save Organization

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/organization.md

Demonstrates how to create a new organization entry and set its Distinguished Name (DN) before saving it to the directory.

```php
<?php

// Adldap\Models\Organization
$org = $provider->make()->organization([
    'o' => 'Some Company',
]);

// Set the DN manually:

$org->setDn('o=Some Company,dc=test,dc=local,dc=com');

$org->save();
?>
```

--------------------------------

### Run PHPUnit Tests

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/firebase/php-jwt/README.md

Execute the project's test suite using PHPUnit. Ensure PHPUnit is installed via PEAR.

```bash
$ pear install PHPUnit
$ phpunit --configuration phpunit.xml.dist
```

--------------------------------

### Basic Adldap2 Usage and Configuration

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/readme.md

Demonstrates how to construct an Adldap instance, configure LDAP connection details, add a provider, and perform basic operations like searching and creating entries. Includes error handling for connection issues.

```php
// Construct new Adldap instance.
$ad = new \Adldap\Adldap();

// Create a configuration array.
$config = [
  // An array of your LDAP hosts. You can use either
  // the host name or the IP address of your host.
  'hosts'    => ['ACME-DC01.corp.acme.org', '192.168.1.1'],

  // The base distinguished name of your domain to perform searches upon.
  'base_dn'  => 'dc=corp,dc=acme,dc=org',

  // The account to use for querying / modifying LDAP records. This
  // does not need to be an admin account. This can also
  // be a full distinguished name of the user account.
  'username' => 'admin@corp.acme.org',
  'password' => 'password',
];

// Add a connection provider to Adldap.
$ad->addProvider($config);

try {
    // If a successful connection is made to your server, the provider will be returned.
    $provider = $ad->connect();

    // Performing a query.
    $results = $provider->search()->where('cn', '=', 'John Doe')->get();

    // Finding a record.
    $user = $provider->search()->find('jdoe');

    // Creating a new LDAP entry. You can pass in attributes into the make methods.
    $user =  $provider->make()->user([
        'cn'          => 'John Doe',
        'title'       => 'Accountant',
        'description' => 'User Account',
    ]);

    // Setting a model's attribute.
    $user->cn = 'John Doe';

    // Saving the changes to your LDAP server.
    if ($user->save()) {
        // User was saved!
    }
} catch (\	Adldap\Auth\BindException $e) {

    // There was an issue binding / connecting to the server.

}
```

--------------------------------

### Create and Save Organizational Unit

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/ou.md

Demonstrates how to create a new Organizational Unit, set its DN using the DN builder or manually, and save it to Active Directory.

```php
<?php

// Adldap\Models\OrganizationalUnit
$ou = $provider->make()->ou([
    'name' => 'Workstation Computers',
]);

// Generate the OU's DN through the DN Builder:

$dn = $ou->getDnBuilder();

$dn->addOu('Workstation Computers');

$ou->setDn($dn);

// Or set the DN manually:

$ou->setDn('ou=Workstation Computers,dc=test,dc=local,dc=com');

$ou->save();
?>
```

--------------------------------

### Run Complete Test Suite

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/matthiasmullie/minify/CONTRIBUTING.md

Execute the entire test suite for the project. This command should be run before submitting any changes.

```sh
vendor/bin/phpunit
```

--------------------------------

### Create a New Search Query

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/searching.md

Initiate a new search query using the `search()` method on your connection provider instance. This can be done standalone or chained with other methods.

```php
$search = $provider->search();
```

```php
$results = $provider->search()->where('cn', '=', 'John Doe')->get();
```

--------------------------------

### Container Creation

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/container.md

Demonstrates how to create a new container object using the AD Ldap provider.

```APIDOC
## Container Creation

This section shows how to instantiate and create a new container object.

### Usage

```php
// Adldap\Models\Container
$container = $provider->make()->container([
    'cn' => 'VPN Users',
]);
```

### Parameters

- **attributes** (array) - An associative array of attributes to set on the container.
```

--------------------------------

### Postfix Configuration for Email Forwarding

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/php-mime-mail-parser/php-mime-mail-parser/README.md

Example Postfix master.cf configuration to pipe emails to a PHP script for processing. Ensure the PHP script is executable and uses the correct arguments.

```bash
myhook unix - n n - - pipe
  		flags=F user=www-data argv=php -c /etc/php5/apache2/php.ini -f /var/www/test.php ${sender} ${size} ${recipient}
```

```bash
smtp      inet  n       -       -       -       -       smtpd
        		-o content_filter=myhook:dummy
```

--------------------------------

### Get First Attribute Value Directly

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/model.md

Provides a convenient way to get the first value of an attribute, often used for single-value attributes like primary email.

```php
// Returns the users first email address.
// Returns `null` if non-existent.
$user->getFirstAttribute('mail');
```

--------------------------------

### Get User Initials

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the initials of the user.

```php
// Get the users initials.
$user->getInitials();

```

--------------------------------

### Run Project Tests

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/stevenmaguire/oauth2-keycloak/CONTRIBUTING.md

Execute the project's test suite using PHPUnit. Ensure all tests pass before submitting a pull request.

```bash
$ ./vendor/bin/phpunit
```

--------------------------------

### Get Group

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/guzzlehttp/guzzle/UPGRADING.md

Retrieves details of a specific group by its ID.

```APIDOC
## GET groups/{id}.json

### Description
Get a group by ID.

### Method
GET

### Endpoint
/groups/{id}.json

### Path Parameters
- **id** (integer) - Required - The unique identifier of the group to retrieve.
```

--------------------------------

### Basic Usage with Composer Autoload

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/nesbot/carbon/readme.md

Includes the Composer autoloader and uses Carbon::now() after installation via Composer.

```php
<?php
require 'vendor/autoload.php';

use Carbon\Carbon;

printf("Now: %s", Carbon::now());

```

--------------------------------

### Get User Company

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the company the user is associated with.

```php
// Get the users company.
$user->getCompany();

```

--------------------------------

### Create and Set New User Password

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/troubleshooting.md

To set a new user's password, first enable their account, then set the password. Ensure the user account is enabled before attempting to set the password.

```php
// Construct a new user instance.
$user = $provider->make()->user();

// Set the user profile details.
$user->setAccountName('jdoe');
$user->setFirstName('John');
$user->setLastName('Doe');
$user->setCompany('ACME');
$user->setEmail('jdoe@acme.com');

// Save the new user.
if ($user->save()) {
    // Enable the new user (using user account control).
    $user->setUserAccountControl(512);

    // Set new user password
    $user->setPassword('Password123');

    // Save the user.
    if($user->save()) {
        // The password was saved successfully.
    }
}
```

--------------------------------

### Get User Locale

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the locale settings for the user.

```php
// Get the users locale.
$user->getLocale();

```

--------------------------------

### Basic Carbon Usage

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/nesbot/carbon/readme.md

Demonstrates common Carbon functionalities including getting the current time, manipulating dates, and formatting output. Requires `use Carbon\Carbon;`.

```php
<?php

use Carbon\Carbon;

printf("Right now is %s", Carbon::now()->toDateTimeString());
printf("Right now in Vancouver is %s", Carbon::now('America/Vancouver'));  //implicit __toString()
$tomorrow = Carbon::now()->addDay();
$lastWeek = Carbon::now()->subWeek();
$nextSummerOlympics = Carbon::createFromDate(2016)->addYears(4);

$officialDate = Carbon::now()->toRfc2822String();

$howOldAmI = Carbon::createFromDate(1975, 5, 21)->age;

$noonTodayLondonTime = Carbon::createFromTime(12, 0, 0, 'Europe/London');

$internetWillBlowUpOn = Carbon::create(2038, 01, 19, 3, 14, 7, 'GMT');

// Don't really want this to happen so mock now
Carbon::setTestNow(Carbon::createFromDate(2000, 1, 1));

// comparisons are always done in UTC
if (Carbon::now()->gte($internetWillBlowUpOn)) {
    die();
}

// Phew! Return to normal behaviour
Carbon::setTestNow();

if (Carbon::now()->isWeekend()) {
    echo 'Party!';
}
// Over 200 languages (and over 500 regional variants) supported:
echo Carbon::now()->subMinutes(2)->diffForHumans(); // '2 minutes ago'
echo Carbon::now()->subMinutes(2)->locale('zh_CN')->diffForHumans(); // '2分钟前'
echo Carbon::parse('2019-07-23 14:51')->isoFormat('LLLL'); // 'Tuesday, July 23, 2019 2:51 PM'
echo Carbon::parse('2019-07-23 14:51')->locale('fr_FR')->isoFormat('LLLL'); // 'mardi 23 juillet 2019 14:51'

// ... but also does 'from now', 'after' and 'before'
// rolling up to seconds, minutes, hours, days, months, years

$daysSinceEpoch = Carbon::createFromTimestamp(0)->diffInDays();

```

--------------------------------

### Get User Department

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the department the user belongs to.

```php
// Get the users department.
$user->getDepartment();

```

--------------------------------

### Get User Title

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the job title of the user.

```php
// Get the users title.
$user->getTitle();

```

--------------------------------

### Safely Open PHP Stream Resource

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/guzzlehttp/psr7/README.md

Use `tryFopen` to open a stream resource, replacing PHP's default warning with an exception on failure.

```php
resource $stream = GuzzleHttp\Psr7\Utils::tryFopen('/path/to/file', 'r');
```

--------------------------------

### Get User Employee Type

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the type of employment for the user.

```php
// Get the users employee type
$user->getEmployeeType();

```

--------------------------------

### Basic Usage without Composer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/nesbot/carbon/readme.md

Includes Carbon manually after downloading the release. This method is not recommended.

```php
<?php
require 'path-to-Carbon-directory/autoload.php';

use Carbon\Carbon;

printf("Now: %s", Carbon::now());

```

--------------------------------

### Get User Employee Number

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the employee number of the user.

```php
// Get the users employee number.
$user->getEmployeeNumber();

```

--------------------------------

### Configure Encryption Key by Path

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/stevenmaguire/oauth2-keycloak/README.md

Specify the encryption key by providing the file path to the key when initializing the provider or using a setter method.

```php
$keyPath = '../key.pem';

$provider = new Stevenmaguire\OAuth2\Client\Provider\Keycloak([
    // ...
    'encryptionKeyPath'   => $keyPath,
]);
```

```php
$provider->setEncryptionKeyPath($keyPath);
```

--------------------------------

### Basic Translation Usage

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/symfony/translation/README.md

Instantiate the Translator, add a loader and resources, then translate a message. Ensure the locale is set correctly.

```php
use Symfony\Component\Translation\Translator;
use Symfony\Component\Translation\Loader\ArrayLoader;

$translator = new Translator('fr_FR');
$translator->addLoader('array', new ArrayLoader());
$translator->addResource('array', [
    'Hello World!' => 'Bonjour !',
], 'fr_FR');

echo $translator->trans('Hello World!'); // outputs « Bonjour ! »
```

--------------------------------

### Get User Employee ID

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the employee ID of the user.

```php
// Get the users employee ID.
$user->getEmployeeId();

```

--------------------------------

### Get User Mail Nickname

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the email nickname for the user.

```php
// Get the users email nickname.
$user->getMailNickname();

```

--------------------------------

### Verify SQL Credentials and Access

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/_status.502.html

Source mailcow.conf and attempt to connect to the MySQL database using the extracted credentials to ensure they are correct.

```bash
source mailcow.conf ; docker compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME}
```

--------------------------------

### Send Email with PHPMailer

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/phpmailer/phpmailer/README.md

Basic example demonstrating how to send an email using PHPMailer. Ensure you have Composer's autoloader included and configure SMTP settings, recipients, attachments, and content.

```php
<?php
//Import PHPMailer classes into the global namespace
//These must be at the top of your script, not inside a function
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;
use PHPMailer\PHPMailer\Exception;

//Load Composer's autoloader
require 'vendor/autoload.php';

//Create an instance; passing `true` enables exceptions
$mail = new PHPMailer(true);

try {
    //Server settings
    $mail->SMTPDebug = SMTP::DEBUG_SERVER;                      //Enable verbose debug output
    $mail->isSMTP();                                            //Send using SMTP
    $mail->Host       = 'smtp.example.com';                     //Set the SMTP server to send through
    $mail->SMTPAuth   = true;                                   //Enable SMTP authentication
    $mail->Username   = 'user@example.com';                     //SMTP username
    $mail->Password   = 'secret';                               //SMTP password
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;            //Enable implicit TLS encryption
    $mail->Port       = 465;                                    //TCP port to connect to; use 587 if you have set `SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS`

    //Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('joe@example.net', 'Joe User');     //Add a recipient
    $mail->addAddress('ellen@example.com');               //Name is optional
    $mail->addReplyTo('info@example.com', 'Information');
    $mail->addCC('cc@example.com');
    $mail->addBCC('bcc@example.com');

    //Attachments
    $mail->addAttachment('/var/tmp/file.tar.gz');         //Add attachments
    $mail->addAttachment('/tmp/image.jpg', 'new.jpg');    //Optional name

    //Content
    $mail->isHTML(true);                                  //Set email format to HTML
    $mail->Subject = 'Here is the subject';
    $mail->Body    = 'This is the HTML message body <b>in bold!</b>';
    $mail->AltBody = 'This is the body in plain text for non-HTML mail clients';

    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
}

```

--------------------------------

### Get User Street Address

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the street address of the user.

```php
// Get the users street address.
$user->getStreetAddress();

```

--------------------------------

### Chain Model Creation

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/model.md

Chain the make() method with specific model types for concise instantiation.

```php
$user = $provider->make()->user();
```

--------------------------------

### Get User Last Name

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the last name of the user.

```php
// Get the users last name.
$user->getLastName();

```

--------------------------------

### Get User First Name

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the first name of the user.

```php
// Get the users first name.
$user->getFirstName();

```

--------------------------------

### Get User Display Name

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the display name of the user.

```php
// Get the users display name.
$user->getDisplayName();

```

--------------------------------

### Connect and Authenticate to IMAP Server

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/ddeboer/imap/README.md

Instantiate the Server class and authenticate with your username and password. The connection object is an instance of \Ddeboer\Imap\Connection.

```php
use Ddeboer\Imap\Server;

$server = new Server('imap.gmail.com');

// $connection is instance of \Ddeboer\Imap\Connection
$connection = $server->authenticate('my_username', 'my_password');
```

--------------------------------

### Get User Department Number

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the department number assigned to the user.

```php
// Get the users department number.
$user->getDepartmentNumber();

```

--------------------------------

### Get User Manager

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the distinguished name of the user's manager.

```php
// Get the users manager.
$user->getManager();

```

--------------------------------

### Get User JPEG Photo

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the user's JPEG photo.

```php
// Get the users jpeg photo.
$user->getJpegPhoto();

```

--------------------------------

### Get User Thumbnail Photo

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the user's thumbnail photo.

```php
// Get the users thumbnail photo.
$user->getThumbnail();

```

--------------------------------

### Get User Profile Path

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the roaming profile path for the user.

```php
// Get the users roaming profile path.
$user->getProfilePath();

```

--------------------------------

### Create a New Container

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/container.md

Instantiate a new container object using the provider's make method. This is useful for creating new organizational units or containers in Active Directory.

```php
use Adldap\Models\Container;

// Adldap\Models\Container
$container = $provider->make()->container([
    'cn' => 'VPN Users',
]);
```

--------------------------------

### Get User Lockout Time

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the timestamp when the user account was locked out.

```php
// Get the users lockout time.
$user->getLockoutTime();

```

--------------------------------

### Build DN for a New User Model

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/distinguished-names.md

Construct a DN for a new user by setting common attributes and then using the DN builder to assemble the full DN string. The resulting DN can be set on the user model.

```php
$user = $provider->make()->user();

$user->setCommonName('John Doe');
$user->setFirstName('John');
$user->setLastName('Doe');

$dn = $user->getDnBuilder();

$dn->addCn($user->getCommonName());
$dn->addOu('Accounting');
$dn->addDc('corp');
$dn->addDc('acme');
$dn->addDc('org');

// Returns 'cn=John Doe,ou=Accounting,dc=corp,dc=acme,dc=org'
echo $dn->get();

// The DistinguishedName object also contains the __toString() magic method
// so you can also just echo the object itself
echo $dn;
```

--------------------------------

### Load YAML File using Functional Syntax

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/mustangostang/spyc/README.md

Alternatively, use the spyc_load_file() function for a functional approach to loading YAML files. Ensure spyc.php is included.

```php
<?php
require_once "spyc.php";
$Data = spyc_load_file('spyc.yaml');
```

--------------------------------

### Get User Other Mailboxes

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve a list of other email addresses associated with the user.

```php
// Get the users other email addresses.
$user->getOtherMailbox();

```

--------------------------------

### Get User Phone Number

Source: https://github.com/mailcow/mailcow-dockerized/blob/master/data/web/inc/lib/vendor/adldap2/adldap2/docs/models/user.md

Retrieve the primary phone number of the user.

```php
// Get the users phone number.
$user->getTelephoneNumber();

```