sql-server-samples Documentation

git clone -n https://github.com/Microsoft/sql-server-samples
cd sql-server-samples
git config core.sparsecheckout true
echo samples/features/*| out-file -append -encoding ascii .git/info/sparse-checkout
echo samples/demos/*| out-file -append -encoding ascii .git/info/sparse-checkout
git checkout

Install-Module -Name SqlServer -AllowClobber

Get-SqlInstance -ServerInstance 'localhost' | Invoke-SqlAssessment

PS:> Get-SqlInstance -ServerInstance localhost | Invoke-SqlAssessment

   TargetPath: Server[@Name='LOCAL']

Sev. Message                                                            Check ID              Origin
---- -------                                                            --------              ------
Info Enable trace flag 834 to use large-page allocations to improve     TF834                 Microsoft Ruleset 0.1.202
     analytical and data warehousing workloads.
Low  Detected deprecated or discontinued feature uses: String literals  DeprecatedFeatures    Microsoft Ruleset 0.1.202
     as column aliases, syscolumns, sysusers, SET FMTONLY ON, XP_API,
     Table hint without WITH, More than two-part column name. We
     recommend to replace them with features actual for SQL Server
     version 14.0.1000.
Medi Amount of single use plans in cache is high (100%). Consider       PlansUseRatio         Microsoft Ruleset 0.1.202
     enabling the Optimize for ad hoc workloads setting on heavy OLTP
     ad-hoc workloads to conserve resources.
...

Get-SqlDatabase -ServerInstance 'localhost' | Invoke-SqlAssessment

"DBMetaInfo": [
    {
        "type": "SQL",
        "target": { "type": "Database" },
        "implementation": {
          "query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS",
        }
    }
]

"DBMetaInfo": [
    {
        "type": "SQL",
        "target": { "type": "Database" },
        "implementation": {
          "query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS",
        },
        "requires": {
          "role": [ "sysadmin" ]
        }
    }
]

SELECT
    [name] AS endpoint_name,
    is_encryption_enabled,
    encryption_algorithm,
    encryption_algorithm_desc
FROM
    sys.database_mirroring_endpoints

"AGEndpoints": [
    {
        "type": "SQL",
        "target": { "type": "Server" },
        "implementation": { "query": " … " },
        "requires": {
          "feature": [ "HADR" ]
        }
    }
]

"AGEndpoints": [
    {
        "type": "SQL",
        "target": { "type": "Server" },
        "implementation": { "query": " … " },
        "runFor": {
          "feature": [ "HADR" ]
        }
    }
]

"requires": {
    "server permission": [
        "ALTER TABLE",
        "ADMINISTER BULK OPERATIONS"
    ]
}

SELECT host_platform, host_release
FROM sys.dm_os_host_info

"implementation": {
    "query": "SELECT host_platform, host_release FROM sys.dm_os_host_info",
    "transform": {
        "type": "parse",
        "map": {
            "host_release": "/^(?<major>\\d+)\\.(?<minor>\\d+)"
        }
    }
}

{
    "probes": ["SysDmOsSysInfo"],
    "locals": {
        "workers": {"sub": [ "@max_workers_count", 1 ] }
    },
    "message": "Workers = @{workers}.",
    "condition": {
        "lt": [ 0, "@workers" ],
        "lt": [ "@workers", 4 ]
    }
}

"message": "Drop hypothetical @{IndexName} index for @{Schema}.@{Object}"

"message": "Current fragmentation level is @{fragmentation:P2}"

Current fragmentation level is 37.20%

"message": "Create index on @{Table} with key columns @{KeyCols}@{IncludedCols: and included columns: #}"

Create index on MyTable with key columns Id, Name

Create index on MyTable with key columns Id, name and included columns: SpaceAvailable, CPULoad

"probes": [
    {
        "type": "DiskInfo",
        "alias": "FirstDisk",
        "params": {
            "DiskName": "C:"
        }
    },
    {
        "type": "DiskInfo",
        "alias": "SecondDisk",
        "params": {
            "DiskName": "D:"
        }
    }
],
"condition": {
    "greater": [
        "@FirstDisk::FreeSpace",
        "@SecondDisk::FreeSpace"
    ]
}

"probes": [
    {
        "id": "DatabaseMasterFiles",
        "alias": "db_files",
        "params": {
            "dbId": null,
            "type": null
        },
        "transform": [
            {
                "type": "aggregate",
                "group": [
                    "volume_mount_point",
                    "volume_id"
                ]
            },
            {
                "type": "aggregate",
                "group": "volume_id",
                "map": {
                    "volume_mount_point": "join"
                }
            }
        ]
    },
    {
        "id": "AzStorage",
        "params": {
            "path": "@db_files::volume_id"
        }
    }
]

{
    "id": "MaxMemory",
    "itemType": "definition",
    "target":
    {
        "type": "Server",
        "version": "[11.0,)"
    },
    "limit": 2147483647
}

{
    "id": "MaxMemory",
    "itemType": "override",
    "limit": 2000000000
}

{
    "id": "MaxMemory",
    "itemType": "override",
    "targetFilter":
    {
        "engineEdition": "Standard"
    },
    "limit": 131072
},

{
    "id": "MaxMemory",
    "itemType": "override",
    "targetFilter":
    {
        "engineEdition": "Express"
    },
    "limit": 1410
}

{
    "id": [ "MaxMemory", "Performance" ],
    "itemType": "override",
    "targetFilter": {
        "platform": "Linux"
    },
    "enabled": false
}

{
     "name": "Ruleset name",
     "version": "Ruleset version",
     "schemaVersion": "Schema version",
     "rules":[
          {
               … rule A …
          },
          {
               … rule B …
          },

          …
     ],
     "probes":{
          "probe1": [
               {
                    … implementation 1 …
               },
               {
                    … implementation 2 …
               },

               …
          ],
          "probe2": [
               …
          ],

          …
     }
}

"engineEdtion": "SqlServer, ManagedInstance"

"name": { "not": [ "master", "tempdb", "model"]}

"machineType": ["AzureVm", "Physical"]

"platform": ["Windows", "Linux"]

"serverName": {"not": "/*.Test$/"}

"type": "Database"

"version": ["[13.0.5026.0, 14.0)", "[12.0.6024.0, 13.0)", "[15.0)"]

{ "not": "/*.Test$/c" }

"version": [
    "[10.0.4326,10.0.4371]",
    "[10.0.5794,10.50)",
    "[10.50.2806,11.0)",
    "[11.0.2316,)"
]

TargetPath : Server[@Name='ContosoAzureSQL']

Sev. Message                                                            Check ID              Origin
---- -------                                                            --------              ------
Medi Amount of single use plans in cache is high (100%). Consider       PlansUseRatio         Microsoft Ruleset 0.1.202
     enabling the Optimize for ad hoc workloads setting on heavy OLTP
     ad-hoc workloads to conserve resources
Low  Use memory optimized virtual machine sizes for the best            AzSqlVmSize           Microsoft Ruleset 0.1.202
     performance of SQL Server workloads

"version": [
    "[10.0.4326,10.0.4371]",
    "[10.0.5794,10.50)",
    "[10.50.2806,11.0)",
    "[11.0.2316,)"
]

expression1: {
    "@version": "10.50.0",
    "@memroySize": 4096
}

expression2: {
    "and": [
        {"@version": "10.50.0"},
        {"@memroySize": 4096}
    ]
}

expression1: {"@memorySize": 4096}

expression2: {
    "equal": [
    "@memorySize",
    4096
    ]
}

"condition": [
    {"@version": "10.50.0"},
    {"@memroySize": 4096}
]

"condition": {
    "or": [
        {"@version": "10.50.0"},
        {"@memroySize": 4096}
    ]
}

"condition": {
    "@version": "10.50.0",
    "@memroySize": 4096
}

"condition": {
    "and": [
        {"@version": "10.50.0"},
        {"@memroySize": 4096}
    ]
}

{
    "probes": ["SysDmOsSysInfo"],
    "locals": {
        "workers": {"sub": [ "@max_workers_count", 1 ] }
    },
    "message": "Workers = @{workers}.",
    "condition": {
        "lt": [ 0, "@workers" ],
        "lt": [ "@workers", 4 ]
    }
}

/* Detailed source-code truncated for AI context efficiency. */

/* Detailed source-code truncated for AI context efficiency. */

{
    "schemaVersion": "1.0",
    "version": "0.2",
    "name": "Custom Overrides",
    "rules":
    [
        {
            "id": "LatestCU",
            "itemType": "override",
            "enabled": false
        },
        {
            "id": ["TraceFlag"],
            "itemType": "override",
            "enabled": false
        },
        {
            "id": ["DefaultRuleset"],
            "itemType": "override",
            "targetFilter":
            {
                "type": "Database",
                "name": [ "DBName1", "DBName2" ]
            },
            "enabled": false
        }
    ]
}

Invoke-SqlAssessment -Check FullBackup | Select TagerObject, Message

TargetObject    Message
-------------   --------
[DevTest]       Create full backup. Last full backup is over 7 days old
[Prototype]     Create full backup. Last full backup is over 7 days old

{
    //Sets the schema version
    "schemaVersion": "1.0",

    //Sets the version
    "version": "1.0",

    //Sets the rule name
    "name": "Backup Policy",

    //Sets the override for the specified rule
    "rules":
    [
        {
            //Sets the type, which is 'override'
            "itemType": "override",

            //Sets the name of the rule that should be overridden
            "id": "FullBackup",

            //Sets the new threshold
            "threshold": 3
        }
    ]
}

Invoke-SqlAssessment -Check FullBackup -Configuration .\BackupPolicy.json | Select TargetObject, Message

TargetObject    Message
-------------   --------
[DevProd]       Create full backup. Last full backup is over 3 days old
[TestDB]        Create full backup. Last full backup is over 3 days old
[DevTest]       Create full backup. Last full backup is over 3 days old
[Prototype]     Create full backup. Last full backup is over 3 days old

{
    …
    "message": "Account '@{attr::service::SQLAgent.account}' is not supported for 'SQL Server Agent' service.",
    "localServiceAccount": "NT AUTHORITY\\LOCALSERVICE",
    "condition": [
        { "not": "@attr::service::SQLAgent" },
        { "ine": [
            "@attr::service::SQLAgent.account",
            "@localServiceAccount"
        ]}
    ],
    "probes": [ "IsClusteredServer" ]
}

{
    …
    "message": "Account '@{attr::service::SQLAgent.account}' is not supported for 'SQL Server Agent' service.",
    "localServiceAccount": "NT AUTHORITY\\LOCALSERVICE",
    "unsupportedAccounts": [
        "NT AUTHORITY\\SYSTEM",
        "LOCALSYSTEM",
        "NT AUTHORITY\\NETWORKSERVICE"
    ],
    "condition": [
        { "not": "@attr::service::SQLAgent" },
        {
            "ine": [
                "@attr::service::SQLAgent.account",
                "@localServiceAccount"
            ],
            "or": [
                { "not": "@is_clustered_server" },
                { "not": {
                    "iin": [
                        "@attr::service::SQLAgent.account",
                        "@unsupportedAccounts"
                    ]
                }}
            ]
        }
    ],
    "probes": [ "IsClusteredServer" ]
}

"runFor": {
    "feature": [ "HADR" ]
}

"requires": {
    "server permission": [
        "ALTER TRACE"
    ]
},

"requires": {
    "object permission on [msdb].[dbo].[sysalerts]": [
        "SELECT"
    ]
},

"requires": {
    "object permission on [msdb].[dbo].[sysjobs]": [
        "SELECT"
    ],
    "object permission on [msdb].[dbo].[sysjobsteps]": [
        "SELECT"
    ]
},

"requires": {
    "role": [
        "bulkadmin",
        "diskadmin"
    ]
}

"runFor": {
    "service": [ "ReportServer" ]
}

"transform": {
    "type": "aggregate",
    "map": {
        "blocked_spid": "count",
        "block_time_min": "min"
    }
}

"transform": {
    "type": "aggregate",
    "map": {
        "RecoveryUnitId": {
            "type": "count",
            "distinct": false
        },
        "blocked_spid": "count",
        "block_time_min": "min"
    }
}

"transform": {
    "type": "aggregate",
    "group": "publisher_db",
    "map": {
        "publication": "join"
    }
}

"transform": {
    "type": "defaultValue",
    "map": {
        "automatic_soft_NUMA_disabled": 0
    }
}

"transform": {
    "type": "nameValuePairs",
    "keyColumn": "Metric",
    "valueColumn": "MeasuredValue",
    "map": {
        "CPU Utilization": "cpu_utilization",
        "Disk Free Space": "disk_space"
    }
}

"transform": {
    "define": {
        "InUse": 0,
        "Name": "master"
}

"transform": {
    "presenceFlag": "dataFound",
    "define": {
        "InUse": 0,
        "Name": "master"
}

{
    "type": "parse",
    "map" : {
        "a": "/(?<amount>\\d+)(\\s*(?<kind>\\w+?)s?\\b)?/x",
        "b": "/(?<color>red|green|blue|yellow)/ix"
    }
}

{
    "type": "parse",
    "map" : {
        "a": "/(?<amount>\\d+)(\\s*(?<kind>\\w+?)s?\b)?/x",
        "b": "/(?<color>red|green|blue|yellow)/ix"
    }
}

/* Detailed source-code truncated for AI context efficiency. */

"probes": [
    {
        "id": "PerformanceProbe",
        "alias": "b",
        "transform": {
        "type": "performance",
            "counters": {
                "batch_request_sec": "rate",
                "lock_requests_sec": {
                    "type": "rate",
                    "instance": "_Total"
                }
            }
        }
    }
]

"probes": [
    {
        "id": "PerformanceProbe",
        "alias": "b",
        "transform": {
        "type": "performance",
            "counters": {
                "batch_request_sec": "rate"
            }
        }
    },
    {
        "id": "PerformanceProbe",
        "alias": "l",
        "transform": {
        "type": "performance",
            "counters": {
                "lock_requests_sec": {
                    "type": "rate",
                    "instance": "_Total"
                }
            }
        }
    }
]

@PerformanceProbe::batch_request_sec
@b::batch_request_sec
@batch_request_sec

"transform": {
    "type": "rename",
    "map": {
        "id": "Archive #",
        "size": "Log File Size (Byte)",
        "date": "Date"
    }
}

"transform": {
    "type": "defaultValue",
    "map": {
        "a":{
            "one"  : 1,
            "two"  : 2,
            "three": 3
        },
        "b":{
            "one"  : "o",
            "two"  : "w",
            "three": "r"
        }
    }
}

...
    "implementation": {
        "query": "Resources | where id =~ @resId | project name"
    }
...

{
    "type": "CmdShell",
    "target": …,
    "implementation": {
        "command": "dir"
    }
}

{
  "type": "Performance",
  "implementation": {
    "Counters": {
      "Access Methods": {
        "Pages Allocated/sec": "pages_allocated"
      }
    }
  }
}

{
  "type": "Performance",
  "implementation": {
    "NumberOfSamples": 1,
    "Counters": {
      "Memory Node": {
        "Free Node Memory (KB)": "free_node_memory"
      }
    }
  }
}

{
  "type": "Performance",
  "implementation": {
    "NumberOfSamples": 1,
    "Counters": {
      "Memory Node": {
        "Free Node Memory (KB)": {
          "alias": "free_node_memory",
          "instances": ["000"]
        },
        "Target Node Memory (KB)": "target_node_memory"
      },
      "Access Methods": {
        "Pages Allocated/sec": "pages_allocated"
      }
    }
  }
}

/* Detailed source-code truncated for AI context efficiency. */

"probes": [
    {
        "id": "PerformanceProbe",
        "alias": "b",
        "transform": {
        "type": "performance",
            "counters": {
                "batch_request_sec": "rate",
                "lock_requests_sec": {
                    "type": "rate",
                    "instance": "_Total"
                }
            }
        }
    }
]

"probes": [
    {
        "id": "PerformanceProbe",
        "alias": "b",
        "transform": {
        "type": "performance",
            "counters": {
                "batch_request_sec": "rate"
            }
        }
    },
    {
        "id": "PerformanceProbe",
        "alias": "l",
        "transform": {
        "type": "performance",
            "counters": {
                "lock_requests_sec": {
                    "type": "rate",
                    "instance": "_Total"
                }
            }
        }
    }
]

@PerformanceProbe::batch_request_sec
@b::batch_request_sec
@batch_request_sec

{
    "type": "PowerShell",
    "target": …,
    "implementation": {
        "command": 'Get-ChildItem'
    }
}

Software\Microsoft\MSSQLSERVER\SQLServerAgent

Software\Microsoft\Microsoft SQL Server\MSSQL12.SQL2014\SQLServerAgent

"probes": {
  "MuRegistryProbe": [
    {
      "type": "Registry",
      "target": { "type": "Server" },
      "implementation": {
        "query": {
          "HKEY_LOCAL_MACHINE":{
            "HARDWARE\\DESCRIPTION\\System": [
              "Identifier",
              "SystemBiosVersion"
            ]
          }
        }
      }
    }
  ]
}

{
  "type": "Registry",
  "target": { "type": "Server" },
  "implementation": {
    "query": {
      "HKEY_LOCAL_MACHINE":{
        "HARDWARE\\DESCRIPTION\\System\\CentralProcessor\\*": [
          "VendorIdentifier"
        ]
      }
    }
  }
}

{
  "HKEY_LOCAL_MACHINE": {
    "HARDWARE\\DESCRIPTION\\*": [
        "Identifier"
    ]
  }
}

"rules": [
    {
      "id": "MyKeys",
      "itemType": "definition",
      "target": {
        "type": "Server",
        "platform": "Windows"
      },
      "displayName": "My custom keys",
      "message": "The current key is @{test}",
      "testParam": "test",
      "resultParam": "result",
      "hiveParam": "Policies",
      "condition": {
        "@test": "@resultParam"
      },
      "probes": [
        {
          "id": "myprobe",
          "params": {
            "hiveParam": "@hiveParam",
            "testParam": "@testParam"
          }
        }
      ]
    }
  ],
  "probes": {
    "myprobe": [
      {
        "type": "Registry",
        "target": {
          "type": "Server",
          "platform": "Windows",
          "instance": true
        },
        "implementation": {
          "query": {
            "HKEY_LOCAL_MACHINE": {
              "SOFTWARE\\@{hiveParam}": [ "@{testParam}" ],
              "SOFTWARE\\@{hiveParam}\\Microsoft\\some": [ "@{testParam}" ]
            }
          }
        }
      }
    ]
  }

{
    "type": "SQL",
    "target": {
        "type": "Server",
        "engineEdition": "OnPremises",
        "platform": "Linux",
        "version": "[11.0,)"
    },
    "implementation": {
        "query": "SELECT [host_platform] AS [host_platform] ,[host_release] AS [host_release] ,64 AS [host_architecture] FROM sys.dm_os_host_info(NOLOCK)",
        "transform": {
            "type": "parse",
            "map": {
                "host_release": "/^(?<major>\\d+)\\.(?<minor>\\d+)(?:\\.(?<build>\\d+))?(?:\\.(?<revision>\\d+))?$/x"
            }
        }
    }
}

{
    "type": "WMI",
    "target": …,
    "implementation": {
        "query": "SELECT Name, BlockSize FROM Win32_Volume WHERE Capacity <> NULL"
    }
}

{
    "type": "WMI",
    "target": {
        "type": "Server",
        "platform": "Windows",
        "engineEdition": "OnPremises",
        "version": "[11.0,)"
    },
    "implementation": {
        "query": "SELECT Name, StartingOffset FROM Win32_DiskPartition WHERE StartingOffset < $threshold"
    }
}

{
    "type": "WMI",
    "target": {
        "type": "Server",
        "platform": "Windows",
        "engineEdition": "OnPremises",
        "version": "[11.0,)"
    },
    "implementation": {
        "query": "SELECT DeviceID, Name FROM Win32_Volume WHERE DriveType=3 AND Name LIKE '_:\\\\'",
        "methods": {
            "da": "DefragAnalysis"
        }
    }
}

getting_started/index

reference/index

cookbook/index

composer require monolog/monolog

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\FirePHPHandler;

// Create the logger
$logger = new Logger('my_logger');
// Now add some handlers
$logger->pushHandler(new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG));
$logger->pushHandler(new FirePHPHandler());

// You can now use your logger
$logger->addInfo('My logger is now ready');

<?php

$logger->addInfo('Adding a new user', array('username' => 'Seldaek'));

<?php

$logger->pushProcessor(function ($record) {
    $record['extra']['dummy'] = 'Hello world!';

    return $record;
});

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\FirePHPHandler;

// Create some handlers
$stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
$firephp = new FirePHPHandler();

// Create the main logger of the app
$logger = new Logger('my_logger');
$logger->pushHandler($stream);
$logger->pushHandler($firephp);

// Create a logger for the security-related stuff with a different channel
$securityLogger = new Logger('security');
$securityLogger->pushHandler($stream);
$securityLogger->pushHandler($firephp);

$record['formatted']

// the default date format is "Y-m-d H:i:s"
$dateFormat = "Y n j, g:i a";
// the default output format is "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"
$output = "%datetime% > %level_name% > %message% %context% %extra%\n";
// finally, create a formatter
$formatter = new LineFormatter($output, $dateFormat);

// Create a handler
$stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
$stream->setFormatter($formatter);
// bind it to a logger object
$securityLogger = new Logger('security');
$securityLogger->pushHandler($stream);

<?php

use Monolog\Logger;
use Monolog\Handler\AbstractProcessingHandler;

class PDOHandler extends AbstractProcessingHandler
{
    private $initialized = false;
    private $pdo;
    private $statement;

    public function __construct(PDO $pdo, $level = Logger::DEBUG, $bubble = true)
    {
        $this->pdo = $pdo;
        parent::__construct($level, $bubble);
    }

    protected function write(array $record)
    {
        if (!$this->initialized) {
            $this->initialize();
        }

        $this->statement->execute(array(
            'channel' => $record['channel'],
            'level' => $record['level'],
            'message' => $record['formatted'],
            'time' => $record['datetime']->format('U'),
        ));
    }

    private function initialize()
    {
        $this->pdo->exec(
            'CREATE TABLE IF NOT EXISTS monolog '
            .'(channel VARCHAR(255), level INTEGER, message LONGTEXT, time INTEGER UNSIGNED)'
        );
        $this->statement = $this->pdo->prepare(
            'INSERT INTO monolog (channel, level, message, time) VALUES (:channel, :level, :message, :time)'
        );

        $this->initialized = true;
    }
}

<?php

$logger->pushHandler(new PDOHandler(new PDO('sqlite:logs.sqlite')));

// You can now use your logger
$logger->addInfo('My logger is now ready');

<?php

use Monolog\Logger;
use Monolog\Handler\SocketHandler;

// Create the logger
$logger = new Logger('my_logger');

// Create the handler
$handler = new SocketHandler('unix:///var/log/httpd_app_log.socket');
$handler->setPersistent(true);

// Now add the handler
$logger->pushHandler($handler, Logger::DEBUG);

// You can now use your logger
$logger->addInfo('My logger is now ready');

cweb1 [2012-02-26 00:12:03] my_logger.INFO: My logger is now ready [] []

$message = Swift_Message::newInstance();

// Fetch the HeaderSet from a Message object
$headers = $message->getHeaders();

$attachment = Swift_Attachment::fromPath('document.pdf');

// Fetch the HeaderSet from an attachment object
$headers = $attachment->getHeaders();

foreach ($headers->getAll() as $header) {
  printf("%s\n", $header->getFieldName());
}

/*
Content-Transfer-Encoding
Content-Type
MIME-Version
Date
Message-ID
From
Subject
To
*/

echo $headers->toString();

/*
Message-ID: <[email protected]>
Date: Tue, 17 Feb 2009 22:26:31 +1100
Subject: Awesome subject!
From: [email protected]
To: [email protected]
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
*/

foreach ($headers->getAll() as $header) {
  switch ($header->getFieldType()) {
    case Swift_Mime_Header::TYPE_TEXT: $type = 'text';
      break;
    case Swift_Mime_Header::TYPE_PARAMETERIZED: $type = 'parameterized';
      break;
    case Swift_Mime_Header::TYPE_MAILBOX: $type = 'mailbox';
      break;
    case Swift_Mime_Header::TYPE_DATE: $type = 'date';
      break;
    case Swift_Mime_Header::TYPE_ID: $type = 'ID';
      break;
    case Swift_Mime_Header::TYPE_PATH: $type = 'path';
      break;
  }
  printf("%s: is a %s header\n", $header->getFieldName(), $type);
}

/*
Content-Transfer-Encoding: is a text header
Content-Type: is a parameterized header
MIME-Version: is a text header
Date: is a date header
Message-ID: is a ID header
From: is a mailbox header
Subject: is a text header
To: is a mailbox header
*/

Text headers are the simplest type of Header. They contain textual information
with no special information included within it -- for example the Subject
header in a message.

There's nothing particularly interesting about a text header, though it is
probably the one you'd opt to use if you need to add a custom header to a
message. It represents text just like you'd think it does. If the text
contains characters that are not permitted in a message header (such as new
lines, or non-ascii characters) then the header takes care of encoding the
text so that it can be used.

No header -- including text headers -- in Swift Mailer is vulnerable to
header-injection attacks. Swift Mailer breaks any attempt at header injection by
encoding the dangerous data into a non-dangerous form.

It's easy to add a new text header to a HeaderSet. You do this by calling the
HeaderSet's ``addTextHeader()`` method.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addTextHeader('Your-Header-Name', 'the header value');

Changing the value of an existing text header is done by calling it's
``setValue()`` method.

.. code-block:: php

    $subject = $message->getHeaders()->get('Subject');

    $subject->setValue('new subject');

When output via ``toString()``, a text header produces something like the
following:

.. code-block:: php

    $subject = $message->getHeaders()->get('Subject');

    $subject->setValue('amazing subject line');

    echo $subject->toString();

    /*

    Subject: amazing subject line

    */

If the header contains any characters that are outside of the US-ASCII range
however, they will be encoded. This is nothing to be concerned about since
mail clients will decode them back.

.. code-block:: php

    $subject = $message->getHeaders()->get('Subject');

    $subject->setValue('contains – dash');

    echo $subject->toString();

    /*

    Subject: contains =?utf-8?Q?=E2=80=93?= dash

    */

Parameterized Headers

$message = Swift_Message::newInstance();

$headers = $message->getHeaders();

$headers->addParameterizedHeader(
  'Header-Name', 'header value',
  array('foo' => 'bar')
  );

$type = $message->getHeaders()->get('Content-Type');

// setParameters() takes an associative array
$type->setParameters(array(
  'name' => 'file.txt',
  'charset' => 'iso-8859-1'
  ));

// setParameter() takes two args for $key and $value
$type->setParameter('charset', 'iso-8859-1');

$type = $message->getHeaders()->get('Content-Type');

$type->setValue('text/html');
$type->setParameter('charset', 'utf-8');

echo $type->toString();

/*

Content-Type: text/html; charset=utf-8

*/

$attachment = Swift_Attachment::newInstance();

$disp = $attachment->getHeaders()->get('Content-Disposition');

$disp->setValue('attachment');
$disp->setParameter('filename', 'report–may.pdf');

echo $disp->toString();

/*

Content-Disposition: attachment; filename*=utf-8''report%E2%80%93may.pdf

*/

Date headers contains an RFC 2822 formatted date (i.e. what PHP's ``date('r')``
returns). They are used anywhere a date or time is needed to be presented as a
message header.

The data on which a date header is modeled is simply a UNIX timestamp such as
that returned by ``time()`` or ``strtotime()``.  The timestamp is used to create
a correctly structured RFC 2822 formatted date such as
``Tue, 17 Feb 2009 22:26:31 +1100``.

The obvious place this header type is used is in the ``Date:`` header of the
message itself.

It's easy to add a new date header to a HeaderSet.  You do this by calling
the HeaderSet's ``addDateHeader()`` method.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addDateHeader('Your-Header-Name', strtotime('3 days ago'));

Changing the value of an existing date header is done by calling it's
``setTimestamp()`` method.

.. code-block:: php

    $date = $message->getHeaders()->get('Date');

    $date->setTimestamp(time());

When output via ``toString()``, a date header produces something like the
following:

.. code-block:: php

    $date = $message->getHeaders()->get('Date');

    echo $date->toString();

    /*

    Date: Wed, 18 Feb 2009 13:35:02 +1100

    */

Mailbox (e-mail address) Headers

$message = Swift_Message::newInstance();

$headers = $message->getHeaders();

$headers->addMailboxHeader('Your-Header-Name', array(
  '[email protected]' => 'Person Name One',
  '[email protected]',
  '[email protected]',
  '[email protected]' => 'Another named person'
  ));

$to = $message->getHeaders()->get('To');

$to->setNameAddresses(array(
  '[email protected]' => 'Joe Bloggs',
  '[email protected]' => 'John Doe',
  '[email protected]'
  ));

$to = $message->getHeaders()->get('To');

$to->setAddresses(array(
  '[email protected]',
  '[email protected]',
  '[email protected]'
  ));

Both methods will accept the above input format in practice.

$to = $message->getHeaders()->get('To');

$to->setAddresses('[email protected]');

$to = $message->getHeaders()->get('To');

$to->setNameAddresses(array(
  '[email protected]' => 'Name of Person',
  '[email protected]',
  '[email protected]' => 'Another Person'
));

echo $to->toString();

/*

To: Name of Person <[email protected]>, [email protected], Another Person
 <[email protected]>

*/

ID headers contain identifiers for the entity (or the message). The most
notable ID header is the Message-ID header on the message itself.

An ID that exists inside an ID header looks more-or-less less like an email
address.  For example, ``<[email protected]>``.
The part to the left of the @ sign is usually unique, based on the current time
and some random factor. The part on the right is usually a domain name.

Any ID passed to the header's ``setId()`` method absolutely MUST conform to
this structure, otherwise you'll get an Exception thrown at you by Swift Mailer
(a ``Swift_RfcComplianceException``).  This is to ensure that the generated
email complies with relevant RFC documents and therefore is less likely to be
blocked as spam.

It's easy to add a new ID header to a HeaderSet.  You do this by calling
the HeaderSet's ``addIdHeader()`` method.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $headers = $message->getHeaders();

    $headers->addIdHeader('Your-Header-Name', '[email protected]');

Changing the value of an existing date header is done by calling its
``setId()`` method.

.. code-block:: php

    $msgId = $message->getHeaders()->get('Message-ID');

    $msgId->setId(time() . '.' . uniqid('thing') . '@example.org');

When output via ``toString()``, an ID header produces something like the
following:

.. code-block:: php

    $msgId = $message->getHeaders()->get('Message-ID');

    echo $msgId->toString();

    /*

    Message-ID: <[email protected]>

    */

Path Headers

$message = Swift_Message::newInstance();

$headers = $message->getHeaders();

$headers->addPathHeader('Your-Header-Name', '[email protected]');

$return = $message->getHeaders()->get('Return-Path');

$return->setAddress('[email protected]');

$return = $message->getHeaders()->get('Return-Path');

$return->setAddress('[email protected]');

echo $return->toString();

/*

Return-Path: 

*/

New headers can be added to the HeaderSet by using one of the provided
``add..Header()`` methods.

To add a header to a MIME entity (such as the message):

Get the HeaderSet from the entity by via its ``getHeaders()`` method.

* Add the header to the HeaderSet by calling one of the ``add..Header()``
  methods.

The added header will appear in the message when it is sent.

.. code-block:: php

    // Adding a custom header to a message
    $message = Swift_Message::newInstance();
    $headers = $message->getHeaders();
    $headers->addTextHeader('X-Mine', 'something here');

    // Adding a custom header to an attachment
    $attachment = Swift_Attachment::fromPath('/path/to/doc.pdf');
    $attachment->getHeaders()->addDateHeader('X-Created-Time', time());

Retrieving Headers

It's valid for some headers to appear more than once in a message (e.g.
the Received header). For this reason ``getAll()`` exists to fetch all
headers with a specified name. In addition, ``get()`` accepts an optional
numerical index, starting from zero to specify which header you want more
specifically.

If you want to modify the contents of the header and you don't know for
sure what type of header it is then you may need to check the type by
calling its ``getFieldType()`` method.

.. code-block:: php

    $headers = $message->getHeaders();

    // Get the To: header
    $toHeader = $headers->get('To');

    // Get all headers named "X-Foo"
    $fooHeaders = $headers->getAll('X-Foo');

    // Get the second header named "X-Foo"
    $foo = $headers->get('X-Foo', 1);

    // Get all headers that are present
    $all = $headers->getAll();

You can check if a named header is present in a HeaderSet by calling its
``has()`` method.

To check if a header exists:

* Get the HeaderSet from the entity by via its ``getHeaders()`` method.

* Call the HeaderSet's ``has()`` method specifying the header you're looking
  for.

If the header exists, ``true`` will be returned or ``false`` if not.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``has()`` accepts an optional
    numerical index, starting from zero to specify which header you want to
    check more specifically.

    .. code-block:: php

        $headers = $message->getHeaders();

        // Check if the To: header exists
        if ($headers->has('To')) {
          echo 'To: exists';
        }

        // Check if an X-Foo header exists twice (i.e. check for the 2nd one)
        if ($headers->has('X-Foo', 1)) {
          echo 'Second X-Foo header exists';
        }

Removing Headers
~~~~~~~~~~~~~~~~

Removing a Header from the HeaderSet is done by calling the HeaderSet's
``remove()`` or ``removeAll()`` methods.

To remove an existing header:

* Get the HeaderSet from the entity by via its ``getHeaders()`` method.

* Call the HeaderSet's ``remove()`` or ``removeAll()`` methods specifying the
  header you want to remove.

When calling ``remove()`` a single header will be removed. When calling
``removeAll()`` all headers with the given name will be removed. If no headers
exist with the given name, no errors will occur.

.. note::

    It's valid for some headers to appear more than once in a message (e.g.
    the Received header). For this reason ``remove()`` accepts an optional
    numerical index, starting from zero to specify which header you want to
    check more specifically. For the same reason, ``removeAll()`` exists to
    remove all headers that have the given name.

    .. code-block:: php

        $headers = $message->getHeaders();

        // Remove the Subject: header
        $headers->remove('Subject');

        // Remove all X-Foo headers
        $headers->removeAll('X-Foo');

        // Remove only the second X-Foo header
        $headers->remove('X-Foo', 1);

Modifying a Header's Content

$headers = $message->getHeaders();

// Change the Subject: header
$subj = $headers->get('Subject');
$subj->setValue('new subject here');

// Change the To: header
$to = $headers->get('To');
$to->setNameAddresses(array(
  '[email protected]' => 'Person',
  '[email protected]'
));

// Using the setFieldBodyModel() just delegates to the correct method
// So here to calls setNameAddresses()
$to->setFieldBodyModel(array(
  '[email protected]' => 'Person',
  '[email protected]'
));

require_once '/path/to/swift-mailer/lib/swift_required.php';

/* rest of code goes here */

require_once '/path/to/swift-mailer/lib/swift_required.php';

function swiftmailer_configurator() {
    // configure Swift Mailer

    Swift_DependencyContainer::getInstance()->...
    Swift_Preferences::getInstance()->...
}

Swift::init('swiftmailer_configurator');

/* rest of code goes here */

While Swift Mailer's autoloader is designed to play nicely with other
autoloaders, sometimes you may have a need to avoid using Swift Mailer's
autoloader and use your own instead. Include the ``swift_init.php``
instead of the ``swift_required.php`` if you need to do this. The very
minimum include is the ``swift_init.php`` file since Swift Mailer will not
work without the dependency injection this file sets up:

.. code-block:: php

    require_once '/path/to/swift-mailer/lib/swift_init.php';

    /* rest of code goes here */

introduction
overview
installing
help-resources
including-the-files
messages
headers
sending
plugins
japanese

$ php composer.phar require swiftmailer/swiftmailer @stable

You do not need to have git installed to use Swift Mailer from GitHub. If
you don't have git installed, go to `GitHub`_ and click the "Download"
button.

The repository can be cloned from git://github.com/swiftmailer/swiftmailer.git
using the ``git clone`` command.

You will need to have ``git`` installed before you can use the
``git clone`` command.

To clone the repository:

* Open your favorite terminal environment (command line).

* Move to the directory you want to clone to.

* Run the command ``git clone git://github.com/swiftmailer/swiftmailer.git
  swiftmailer``.

The source code will be downloaded into a directory called "swiftmailer".

The example shows the process on a UNIX-like system such as Linux, BSD or Mac
OS X.

.. code-block:: bash

    $ cd source_code/
    $ git clone git://github.com/swiftmailer/swiftmailer.git swiftmailer
    Initialized empty Git repository in /Users/chris/source_code/swiftmailer/.git/
    remote: Counting objects: 6815, done.
    remote: Compressing objects: 100% (2761/2761), done.
    remote: Total 6815 (delta 3641), reused 6326 (delta 3286)
    Receiving objects: 100% (6815/6815), 4.35 MiB | 162 KiB/s, done.
    Resolving deltas: 100% (3641/3641), done.
    Checking out files: 100% (1847/1847), done.
    $ cd swiftmailer/
    $ ls
    CHANGES LICENSE ...
    $

Troubleshooting
---------------

Swift Mailer does not work when used with function overloading as implemented
by ``mbstring`` (``mbstring.func_overload`` set to ``2``). A workaround is to
temporarily change the internal encoding to ``ASCII`` when sending an email:

.. code-block:: php

    if (function_exists('mb_internal_encoding') && ((int) ini_get('mbstring.func_overload')) & 2)
    {
      $mbEncoding = mb_internal_encoding();
      mb_internal_encoding('ASCII');
    }

    // Create your message and send it with Swift Mailer

    if (isset($mbEncoding))
    {
      mb_internal_encoding($mbEncoding);
    }

.. _`GitHub`: http://github.com/swiftmailer/swiftmailer

---

### Samples Development Frameworks Laravel Vendor Swiftmailer Swiftmailer Doc Introduction (`samples/development-frameworks/laravel/vendor/swiftmailer/swiftmailer/doc/introduction.rst`)

Introduction
============

Swift Mailer is a component-based library for sending e-mails from PHP
applications.

Organization of this Book
-------------------------

This book has been written so that those who need information quickly are able
to find what they need, and those who wish to learn more advanced topics can
read deeper into each chapter.

The book begins with an overview of Swift Mailer, discussing what's included
in the package and preparing you for the remainder of the book.

It is possible to read this user guide just like any other book (from
beginning to end). Each chapter begins with a discussion of the contents it
contains, followed by a short code sample designed to give you a head start.
As you get further into a chapter you will learn more about Swift Mailer's
capabilities, but often you will be able to head directly to the topic you
wish to learn about.

Throughout this book you will be presented with code samples, which most
people should find ample to implement Swift Mailer appropriately in their own
projects. We will also use diagrams where appropriate, and where we believe
readers may find it helpful we will discuss some related theory, including
reference to certain documents you are able to find online.

Code Samples
------------

Code samples presented in this book will be displayed on a different colored
background in a monospaced font. Samples are not to be taken as copy & paste
code snippets.

Code examples are used through the book to clarify what is written in text.
They will sometimes be usable as-is, but they should always be taken as
outline/pseudo code only.

A code sample will look like this::

    class AClass
    {
      ...
    }

    // A Comment
    $obj = new AClass($arg1, $arg2, ... );

    /* A note about another way of doing something
    $obj = AClass::newInstance($arg1, $arg2, ... );

    */

The presence of 3 dots ``...`` in a code sample indicates that we have left
out a chunk of the code for brevity, they are not actually part of the code.

We will often place multi-line comments ``/* ... */`` in the code so that we
can show alternative ways of achieving the same result.

You should read the code examples given and try to understand them. They are
kept concise so that you are not overwhelmed with information.

History of Swift Mailer
-----------------------

Swift Mailer began back in 2005 as a one-class project for sending mail over
SMTP. It has since grown into the flexible component-based library that is in
development today.

Chris Corbyn first posted Swift Mailer on a web forum asking for comments from
other developers. It was never intended as a fully supported open source
project, but members of the forum began to adopt it and make use of it.

Very quickly feature requests were coming for the ability to add attachments
and use SMTP authentication, along with a number of other "obvious" missing
features. Considering the only alternative was PHPMailer it seemed like a good
time to bring some fresh tools to the table. Chris began working towards a
more component based, PHP5-like approach unlike the existing single-class,
legacy PHP4 approach taken by PHPMailer.

Members of the forum offered a lot of advice and critique on the code as he
worked through this project and released versions 2 and 3 of the library in
2005 and 2006, which by then had been broken down into smaller classes
offering more flexibility and supporting plugins. To this day the Swift Mailer
team still receive a lot of feature requests from users both on the forum and
in by email.

Until 2008 Chris was the sole developer of Swift Mailer, but entering 2009 he
gained the support of two experienced developers well-known to him: Paul
Annesley and Christopher Thompson. This has been an extremely welcome change.

As of September 2009, Chris handed over the maintenance of Swift Mailer to
Fabien Potencier.

Now 2009 and in its fourth major version Swift Mailer is more object-oriented
and flexible than ever, both from a usability standpoint and from a
development standpoint.

By no means is Swift Mailer ready to call "finished". There are still many
features that can be added to the library along with the constant refactoring
that happens behind the scenes.

It's a Library!
---------------

Swift Mailer is not an application - it's a library.

To most experienced developers this is probably an obvious point to make, but
it's certainly worth mentioning. Many people often contact us having gotten
the completely wrong end of the stick in terms of what Swift Mailer is
actually for.

It's not an application. It does not have a graphical user interface. It
cannot be opened in your web browser directly.

It's a library (or a framework if you like). It provides a whole lot of
classes that do some very complicated things, so that you don't have to. You
"use" Swift Mailer within an application so that your application can have the
ability to send emails.

The component-based structure of the library means that you are free to
implement it in a number of different ways and that you can pick and choose
what you want to use.

An application on the other hand (such as a blog or a forum) is already "put
together" in a particular way, (usually) provides a graphical user interface
and most likely doesn't offer a great deal of integration with your own
application.

Embrace the structure of the library and use the components it offers to your
advantage. Learning what the components do, rather than blindly copying and
pasting existing code will put you in a great position to build a powerful
application!

---

### Samples Development Frameworks Laravel Vendor Swiftmailer Swiftmailer Doc Japanese (`samples/development-frameworks/laravel/vendor/swiftmailer/swiftmailer/doc/japanese.rst`)

Using Swift Mailer for Japanese Emails
======================================

To send emails in Japanese, you need to tweak the default configuration.

After requiring the Swift Mailer autoloader (by including the
``swift_required.php`` file), call the ``Swift::init()`` method with the
following code::

    require_once '/path/to/swift-mailer/lib/swift_required.php';

    Swift::init(function () {
        Swift_DependencyContainer::getInstance()
            ->register('mime.qpheaderencoder')
            ->asAliasOf('mime.base64headerencoder');

        Swift_Preferences::getInstance()->setCharset('iso-2022-jp');
    });

    /* rest of code goes here */

That's all!

---

### Samples Development Frameworks Laravel Vendor Swiftmailer Swiftmailer Doc Messages (`samples/development-frameworks/laravel/vendor/swiftmailer/swiftmailer/doc/messages.rst`)

Creating Messages
=================

Creating messages in Swift Mailer is done by making use of the various MIME
entities provided with the library.  Complex messages can be quickly created
with very little effort.

Quick Reference for Creating a Message
---------------------------------------

You can think of creating a Message as being similar to the steps you perform
when you click the Compose button in your mail client.  You give it a subject,
specify some recipients, add any attachments and write your message.

To create a Message:

* Call the ``newInstance()`` method of ``Swift_Message``.

* Set your sender address (``From:``) with ``setFrom()`` or ``setSender()``.

* Set a subject line with ``setSubject()``.

* Set recipients with ``setTo()``, ``setCc()`` and/or ``setBcc()``.

* Set a body with ``setBody()``.

* Add attachments with ``attach()``.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the message
    $message = Swift_Message::newInstance()

      // Give the message a subject
      ->setSubject('Your subject')

      // Set the From address with an associative array
      ->setFrom(array('[email protected]' => 'John Doe'))

      // Set the To addresses with an associative array
      ->setTo(array('[email protected]', '[email protected]' => 'A name'))

      // Give it a body
      ->setBody('Here is the message itself')

      // And optionally an alternative body
      ->addPart('<q>Here is the message itself</q>', 'text/html')

      // Optionally add any attachments
      ->attach(Swift_Attachment::fromPath('my-document.pdf'))
      ;

Message Basics
--------------

A message is a container for anything you want to send to somebody else. There
are several basic aspects of a message that you should know.

An e-mail message is made up of several relatively simple entities that are
combined in different ways to achieve different results. All of these entities
have the same fundamental outline but serve a different purpose. The Message
itself can be defined as a MIME entity, an Attachment is a MIME entity, all
MIME parts are MIME entities -- and so on!

The basic units of each MIME entity -- be it the Message itself, or an
Attachment -- are its Headers and its body:

.. code-block:: text

    Header-Name: A header value
    Other-Header: Another value

    The body content itself

The Headers of a MIME entity, and its body must conform to some strict
standards defined by various RFC documents. Swift Mailer ensures that these
specifications are followed by using various types of object, including
Encoders and different Header types to generate the entity.

The Structure of a Message

Although there are a lot of available methods on a message object, you only
need to make use of a small subset of them. Usually you'll use
``setSubject()``, ``setTo()`` and
``setFrom()`` before setting the body of your message with
``setBody()``.

Calling methods is simple. You just call them like functions, but using the
object operator "``->``" to do so. If you've created
a message object and called it ``$message`` then you'd set a
subject on it like so:

.. code-block:: php

    require_once 'lib/swift_required.php';

    $message = Swift_Message::newInstance();
    $message->setSubject('My subject');

All MIME entities (including a message) have a ``toString()``
method that you can call if you want to take a look at what is going to be
sent. For example, if you ``echo
$message->toString();`` you would see something like this:

.. code-block:: bash

    Message-ID: <[email protected]>
    Date: Thu, 25 Dec 2008 13:54:38 +1100
    Subject: Example subject
    From: Chris Corbyn <[email protected]>
    To: Receiver Name <[email protected]>
    MIME-Version: 1.0
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: quoted-printable

    Here is the message

We'll take a closer look at the methods you use to create your message in the
following sections.

Adding Content to Your Message
------------------------------

Rich content can be added to messages in Swift Mailer with relative ease by
calling methods such as ``setSubject()``, ``setBody()``, ``addPart()`` and
``attach()``.

Setting the Subject Line
~~~~~~~~~~~~~~~~~~~~~~~~

The subject line, displayed in the recipients' mail client can be set with the
``setSubject()`` method, or as a parameter to ``Swift_Message::newInstance()``.

To set the subject of your Message:

* Call the ``setSubject()`` method of the Message, or specify it at the time
  you create the message.

  .. code-block:: php

    // Pass it as a parameter when you create the message
    $message = Swift_Message::newInstance('My amazing subject');

    // Or set it after like this
    $message->setSubject('My amazing subject');

Setting the Body Content
~~~~~~~~~~~~~~~~~~~~~~~~

The body of the message -- seen when the user opens the message --
is specified by calling the ``setBody()`` method. If an alternative body is to
be included ``addPart()`` can be used.

The body of a message is the main part that is read by the user. Often people
want to send a message in HTML format (``text/html``), other
times people want to send in plain text (``text/plain``), or
sometimes people want to send both versions and allow the recipient to choose
how they view the message.

As a rule of thumb, if you're going to send a HTML email, always include a
plain-text equivalent of the same content so that users who prefer to read
plain text can do so.

To set the body of your Message:

* Call the ``setBody()`` method of the Message, or specify it at the time you
  create the message.

* Add any alternative bodies with ``addPart()``.

If the recipient's mail client offers preferences for displaying text vs. HTML
then the mail client will present that part to the user where available.  In
other cases the mail client will display the "best" part it can - usually HTML
if you've included HTML.

.. code-block:: php

    // Pass it as a parameter when you create the message
    $message = Swift_Message::newInstance('Subject here', 'My amazing body');

    // Or set it after like this
    $message->setBody('My *amazing* body', 'text/html');

    // Add alternative parts with addPart()
    $message->addPart('My amazing body in plain text', 'text/plain');

Attaching Files
---------------

Attachments are downloadable parts of a message and can be added by calling
the ``attach()`` method on the message. You can add attachments that exist on
disk, or you can create attachments on-the-fly.

Attachments are actually an interesting area of Swift Mailer and something
that could put a lot of power at your fingertips if you grasp the concept
behind the way a message is held together.

Although we refer to files sent over e-mails as "attachments" -- because
they're attached to the message -- lots of other parts of the message are
actually "attached" even if we don't refer to these parts as attachments.

File attachments are created by the ``Swift_Attachment`` class
and then attached to the message via the ``attach()`` method on
it. For all of the "every day" MIME types such as all image formats, word
documents, PDFs and spreadsheets you don't need to explicitly set the
content-type of the attachment, though it would do no harm to do so. For less
common formats you should set the content-type -- which we'll cover in a
moment.

Attaching Existing Files
~~~~~~~~~~~~~~~~~~~~~~~~

Files that already exist, either on disk or at a URL can be attached to a
message with just one line of code, using ``Swift_Attachment::fromPath()``.

You can attach files that exist locally, or if your PHP installation has
``allow_url_fopen`` turned on you can attach files from other
websites.

To attach an existing file:

* Create an attachment with ``Swift_Attachment::fromPath()``.

* Add the attachment to the message with ``attach()``.

The attachment will be presented to the recipient as a downloadable file with
the same filename as the one you attached.

.. code-block:: php

    // Create the attachment
    // * Note that you can technically leave the content-type parameter out
    $attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');

    // Attach it to the message
    $message->attach($attachment);


    // The two statements above could be written in one line instead
    $message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));


    // You can attach files from a URL if allow_url_fopen is on in php.ini
    $message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));

Setting the Filename
~~~~~~~~~~~~~~~~~~~~

Usually you don't need to explicitly set the filename of an attachment because
the name of the attached file will be used by default, but if you want to set
the filename you use the ``setFilename()`` method of the Attachment.

To change the filename of an attachment:

* Call its ``setFilename()`` method.

The attachment will be attached in the normal way, but meta-data sent inside
the email will rename the file to something else.

.. code-block:: php

    // Create the attachment and call its setFilename() method
    $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
      ->setFilename('cool.jpg');


    // Because there's a fluid interface, you can do this in one statement
    $message->attach(
      Swift_Attachment::fromPath('/path/to/image.jpg')->setFilename('cool.jpg')
    );

Attaching Dynamic Content
~~~~~~~~~~~~~~~~~~~~~~~~~

Files that are generated at runtime, such as PDF documents or images created
via GD can be attached directly to a message without writing them out to disk.
Use the standard ``Swift_Attachment::newInstance()`` method.

To attach dynamically created content:

* Create your content as you normally would.

* Create an attachment with ``Swift_Attachment::newInstance()``, specifying
  the source data of your content along with a name and the content-type.

* Add the attachment to the message with ``attach()``.

The attachment will be presented to the recipient as a downloadable file
with the filename and content-type you specify.

.. note::

    If you would usually write the file to disk anyway you should just attach
    it with ``Swift_Attachment::fromPath()`` since this will use less memory:

    .. code-block:: php

        // Create your file contents in the normal way, but don't write them to disk
        $data = create_my_pdf_data();

        // Create the attachment with your data
        $attachment = Swift_Attachment::newInstance($data, 'my-file.pdf', 'application/pdf');

        // Attach it to the message
        $message->attach($attachment);


        // You can alternatively use method chaining to build the attachment
        $attachment = Swift_Attachment::newInstance()
          ->setFilename('my-file.pdf')
          ->setContentType('application/pdf')
          ->setBody($data)
          ;

Changing the Disposition
~~~~~~~~~~~~~~~~~~~~~~~~

Attachments just appear as files that can be saved to the Desktop if desired.
You can make attachment appear inline where possible by using the
``setDisposition()`` method of an attachment.

To make an attachment appear inline:

* Call its ``setDisposition()`` method.

The attachment will be displayed within the email viewing window if the mail
client knows how to display it.

.. note::

    If you try to create an inline attachment for a non-displayable file type
    such as a ZIP file, the mail client should just present the attachment as
    normal:

    .. code-block:: php

        // Create the attachment and call its setDisposition() method
        $attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
          ->setDisposition('inline');


        // Because there's a fluid interface, you can do this in one statement
        $message->attach(
          Swift_Attachment::fromPath('/path/to/image.jpg')->setDisposition('inline')
        );

Embedding Inline Media Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Often people want to include an image or other content inline with a HTML
message. It's easy to do this with HTML linking to remote resources, but this
approach is usually blocked by mail clients. Swift Mailer allows you to embed
your media directly into the message.

Mail clients usually block downloads from remote resources because this
technique was often abused as a mean of tracking who opened an email. If
you're sending a HTML email and you want to include an image in the message
another approach you can take is to embed the image directly.

Swift Mailer makes embedding files into messages extremely streamlined. You
embed a file by calling the ``embed()`` method of the message,
which returns a value you can use in a ``src`` or
``href`` attribute in your HTML.

Just like with attachments, it's possible to embed dynamically generated
content without having an existing file available.

The embedded files are sent in the email as a special type of attachment that
has a unique ID used to reference them within your HTML attributes. On mail
clients that do not support embedded files they may appear as attachments.

Although this is commonly done for images, in theory it will work for any
displayable (or playable) media type. Support for other media types (such as
video) is dependent on the mail client however.

Embedding Existing Files
........................

Files that already exist, either on disk or at a URL can be embedded in a
message with just one line of code, using ``Swift_EmbeddedFile::fromPath()``.

You can embed files that exist locally, or if your PHP installation has
``allow_url_fopen`` turned on you can embed files from other websites.

To embed an existing file:

* Create a message object with ``Swift_Message::newInstance()``.

* Set the body as HTML, and embed a file at the correct point in the message with ``embed()``.

The file will be displayed with the message inline with the HTML wherever its ID
is used as a ``src`` attribute.

.. note::

    ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one
    another. ``Swift_Image`` exists for semantic purposes.

.. note::

    You can embed files in two stages if you prefer. Just capture the return
    value of ``embed()`` in a variable and use that as the ``src`` attribute.

    .. code-block:: php

        // Create the message
        $message = Swift_Message::newInstance('My subject');

        // Set the body
        $message->setBody(
        '<html>' .
        ' <head></head>' .
        ' <body>' .
        '  Here is an image <img src="' . // Embed the file
             $message->embed(Swift_Image::fromPath('image.png')) .
           '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html' // Mark the content-type as HTML
        );

        // You can embed files from a URL if allow_url_fopen is on in php.ini
        $message->setBody(
        '<html>' .
        ' <head></head>' .
        ' <body>' .
        '  Here is an image <img src="' .
             $message->embed(Swift_Image::fromPath('http://site.tld/logo.png')) .
           '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html'
        );


        // If placing the embed() code inline becomes cumbersome
        // it's easy to do this in two steps
        $cid = $message->embed(Swift_Image::fromPath('image.png'));

        $message->setBody(
        '<html>' .
        ' <head></head>' .
        ' <body>' .
        '  Here is an image <img src="' . $cid . '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html' // Mark the content-type as HTML
        );

Embedding Dynamic Content
.........................

Images that are generated at runtime, such as images created via GD can be
embedded directly to a message without writing them out to disk. Use the
standard ``Swift_Image::newInstance()`` method.

To embed dynamically created content:

* Create a message object with ``Swift_Message::newInstance()``.

* Set the body as HTML, and embed a file at the correct point in the message
  with ``embed()``. You will need to specify a filename and a content-type.

The file will be displayed with the message inline with the HTML wherever its ID
is used as a ``src`` attribute.

.. note::

    ``Swift_Image`` and ``Swift_EmbeddedFile`` are just aliases of one
    another. ``Swift_Image`` exists for semantic purposes.

.. note::

    You can embed files in two stages if you prefer. Just capture the return
    value of ``embed()`` in a variable and use that as the ``src`` attribute.

    .. code-block:: php

        // Create your file contents in the normal way, but don't write them to disk
        $img_data = create_my_image_data();

        // Create the message
        $message = Swift_Message::newInstance('My subject');

        // Set the body
        $message->setBody(
        '<html>' .
        ' <head></head>' .
        ' <body>' .
        '  Here is an image <img src="' . // Embed the file
             $message->embed(Swift_Image::newInstance($img_data, 'image.jpg', 'image/jpeg')) .
           '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html' // Mark the content-type as HTML
        );


        // If placing the embed() code inline becomes cumbersome
        // it's easy to do this in two steps
        $cid = $message->embed(Swift_Image::newInstance($img_data, 'image.jpg', 'image/jpeg'));

        $message->setBody(
        '<html>' .
        ' <head></head>' .
        ' <body>' .
        '  Here is an image <img src="' . $cid . '" alt="Image" />' .
        '  Rest of message' .
        ' </body>' .
        '</html>',
          'text/html' // Mark the content-type as HTML
        );

Adding Recipients to Your Message
---------------------------------

Recipients are specified within the message itself via ``setTo()``, ``setCc()``
and ``setBcc()``. Swift Mailer reads these recipients from the message when it
gets sent so that it knows where to send the message to.

Message recipients are one of three types:

* ``To:`` recipients -- the primary recipients (required)

* ``Cc:`` recipients -- receive a copy of the message (optional)

* ``Bcc:`` recipients -- hidden from other recipients (optional)

Each type can contain one, or several addresses. It's possible to list only
the addresses of the recipients, or you can personalize the address by
providing the real name of the recipient.

Make sure to add only valid email addresses as recipients. If you try to add an
invalid email address with ``setTo()``, ``setCc()`` or ``setBcc()``, Swift
Mailer will throw a ``Swift_RfcComplianceException``.

If you add recipients automatically based on a data source that may contain
invalid email addresses, you can prevent possible exceptions by validating the
addresses using ``Swift_Validate::email($email)`` and only adding addresses
that validate. Another way would be to wrap your ``setTo()``, ``setCc()`` and
``setBcc()`` calls in a try-catch block and handle the
``Swift_RfcComplianceException`` in the catch block.

.. sidebar:: Syntax for Addresses

    If you only wish to refer to a single email address (for example your
    ``From:`` address) then you can just use a string.

    .. code-block:: php

          $message->setFrom('[email protected]');

    If you want to include a name then you must use an associative array.

    .. code-block:: php

         $message->setFrom(array('[email protected]' => 'The Name'));

    If you want to include multiple addresses then you must use an array.

    .. code-block:: php

         $message->setTo(array('[email protected]', '[email protected]'));

    You can mix personalized (addresses with a name) and non-personalized
    addresses in the same list by mixing the use of associative and
    non-associative array syntax.

    .. code-block:: php

         $message->setTo(array(
           '[email protected]' => 'Recipient Name One',
           '[email protected]', // Note that this is not a key-value pair
           '[email protected]' => 'Recipient Name Two'
         ));

Setting ``To:`` Recipients
~~~~~~~~~~~~~~~~~~~~~~~~~~

``To:`` recipients are required in a message and are set with the
``setTo()`` or ``addTo()`` methods of the message.

To set ``To:`` recipients, create the message object using either
``new Swift_Message( ... )`` or ``Swift_Message::newInstance( ... )``,
then call the ``setTo()`` method with a complete array of addresses, or use the
``addTo()`` method to iteratively add recipients.

The ``setTo()`` method accepts input in various formats as described earlier in
this chapter. The ``addTo()`` method takes either one or two parameters. The
first being the email address and the second optional parameter being the name
of the recipient.

``To:`` recipients are visible in the message headers and will be
seen by the other recipients.

.. note::

    Multiple calls to ``setTo()`` will not add new recipients -- each
    call overrides the previous calls. If you want to iteratively add
    recipients, use the ``addTo()`` method.

    .. code-block:: php

        // Using setTo() to set all recipients in one go
        $message->setTo(array(
          '[email protected]',
          '[email protected]' => 'Person 2 Name',
          '[email protected]',
          '[email protected]',
          '[email protected]' => 'Person 5 Name'
        ));

        // Using addTo() to add recipients iteratively
        $message->addTo('[email protected]');
        $message->addTo('[email protected]', 'Person 2 Name');

Setting ``Cc:`` Recipients
~~~~~~~~~~~~~~~~~~~~~~~~~~

``Cc:`` recipients are set with the ``setCc()`` or ``addCc()`` methods of the
message.

To set ``Cc:`` recipients, create the message object using either
``new Swift_Message( ... )`` or ``Swift_Message::newInstance( ... )``, then call
the ``setCc()`` method with a complete array of addresses, or use the
``addCc()`` method to iteratively add recipients.

The ``setCc()`` method accepts input in various formats as described earlier in
this chapter. The ``addCc()`` method takes either one or two parameters. The
first being the email address and the second optional parameter being the name
of the recipient.

``Cc:`` recipients are visible in the message headers and will be
seen by the other recipients.

.. note::

    Multiple calls to ``setCc()`` will not add new recipients -- each
    call overrides the previous calls. If you want to iteratively add Cc:
    recipients, use the ``addCc()`` method.

    .. code-block:: php

        // Using setCc() to set all recipients in one go
        $message->setCc(array(
          '[email protected]',
          '[email protected]' => 'Person 2 Name',
          '[email protected]',
          '[email protected]',
          '[email protected]' => 'Person 5 Name'
        ));

        // Using addCc() to add recipients iteratively
        $message->addCc('[email protected]');
        $message->addCc('[email protected]', 'Person 2 Name');

Setting ``Bcc:`` Recipients
~~~~~~~~~~~~~~~~~~~~~~~~~~~

``Bcc:`` recipients receive a copy of the message without anybody else knowing
it, and are set with the ``setBcc()`` or ``addBcc()`` methods of the message.

To set ``Bcc:`` recipients, create the message object using either ``new
Swift_Message( ... )`` or ``Swift_Message::newInstance( ... )``, then call the
``setBcc()`` method with a complete array of addresses, or use
the ``addBcc()`` method to iteratively add recipients.

The ``setBcc()`` method accepts input in various formats as described earlier in
this chapter. The ``addBcc()`` method takes either one or two parameters. The
first being the email address and the second optional parameter being the name
of the recipient.

Only the individual ``Bcc:`` recipient will see their address in the message
headers. Other recipients (including other ``Bcc:`` recipients) will not see the
address.

.. note::

    Multiple calls to ``setBcc()`` will not add new recipients -- each
    call overrides the previous calls. If you want to iteratively add Bcc:
    recipients, use the ``addBcc()`` method.

    .. code-block:: php

        // Using setBcc() to set all recipients in one go
        $message->setBcc(array(
          '[email protected]',
          '[email protected]' => 'Person 2 Name',
          '[email protected]',
          '[email protected]',
          '[email protected]' => 'Person 5 Name'
        ));

        // Using addBcc() to add recipients iteratively
        $message->addBcc('[email protected]');
        $message->addBcc('[email protected]', 'Person 2 Name');

Specifying Sender Details
-------------------------

An email must include information about who sent it. Usually this is managed
by the ``From:`` address, however there are other options.

The sender information is contained in three possible places:

* ``From:`` -- the address(es) of who wrote the message (required)

* ``Sender:`` -- the address of the single person who sent the message
  (optional)

* ``Return-Path:`` -- the address where bounces should go to (optional)

You must always include a ``From:`` address by using ``setFrom()`` on the
message. Swift Mailer will use this as the default ``Return-Path:`` unless
otherwise specified.

The ``Sender:`` address exists because the person who actually sent the email
may not be the person who wrote the email. It has a higher precedence than the
``From:`` address and will be used as the ``Return-Path:`` unless otherwise
specified.

Setting the ``From:`` Address

If you set multiple ``From:`` addresses then you absolutely must set a
``Sender:`` address to indicate who physically sent the message.

.. code-block:: php

    // Set a single From: address
    $message->setFrom('[email protected]');

    // Set a From: address including a name
    $message->setFrom(array('[email protected]' => 'Your Name'));

    // Set multiple From: addresses if multiple people wrote the email
    $message->setFrom(array(
      '[email protected]' => 'Sender One',
      '[email protected]' => 'Sender Two'
    ));

A ``Sender:`` address specifies who sent the message and is set with the
``setSender()`` method of the message.

To set the ``Sender:`` address:

* Call the ``setSender()`` method on the Message.

The ``Sender:`` address is visible in the message headers and will be seen by
the recipients.

This address will be used as the ``Return-Path:`` unless otherwise specified.

.. note::

    If you set multiple ``From:`` addresses then you absolutely must set a
    ``Sender:`` address to indicate who physically sent the message.

You must not set more than one sender address on a message because it's not
possible for more than one person to send a single message.

.. code-block:: php

    $message->setSender('[email protected]');

Setting the ``Return-Path:`` (Bounce) Address

$message->setReturnPath('[email protected]');

S/MIME can sign and/or encrypt a message using the OpenSSL extension.

When signing a message, the signer creates a signature of the entire content of the message (including attachments).

The certificate and private key must be PEM encoded, and can be either created using for example OpenSSL or
obtained at an official Certificate Authority (CA).

**The recipient must have the CA certificate in the list of trusted issuers in order to verify the signature.**

**Make sure the certificate supports emailProtection.**

When using OpenSSL this can done by the including the *-addtrust emailProtection* parameter when creating the certificate.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $smimeSigner = Swift_Signers_SMimeSigner::newInstance();
    $smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem');
    $message->attachSigner($smimeSigner);

When the private key is secured using a passphrase use the following instead.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $smimeSigner = Swift_Signers_SMimeSigner::newInstance();
    $smimeSigner->setSignCertificate('/path/to/certificate.pem', array('/path/to/private-key.pem', 'passphrase'));
    $message->attachSigner($smimeSigner);

By default the signature is added as attachment,
making the message still readable for mailing agents not supporting signed messages.

Storing the message as binary is also possible but not recommended.

.. code-block:: php

    $smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem', PKCS7_BINARY);

When encrypting the message (also known as enveloping), the entire message (including attachments)
is encrypted using a certificate, and the recipient can then decrypt the message using corresponding private key.

Encrypting ensures nobody can read the contents of the message without the private key.

Normally the recipient provides a certificate for encrypting and keeping the decryption key private.

Using both signing and encrypting is also possible.

.. code-block:: php

    $message = Swift_Message::newInstance();

    $smimeSigner = Swift_Signers_SMimeSigner::newInstance();
    $smimeSigner->setSignCertificate('/path/to/sign-certificate.pem', '/path/to/private-key.pem');
    $smimeSigner->setEncryptCertificate('/path/to/encrypt-certificate.pem');
    $message->attachSigner($smimeSigner);

The used encryption cipher can be set as the second parameter of setEncryptCertificate()

See http://php.net/manual/openssl.ciphers for a list of supported ciphers.

By default the message is first signed and then encrypted, this can be changed by adding.

.. code-block:: php

    $smimeSigner->setSignThenEncrypt(false);

**Changing this is not recommended as most mail agents don't support this none-standard way.**

Only when having trouble with sign then encrypt method, this should be changed.

Requesting a Read Receipt
-------------------------

It is possible to request a read-receipt to be sent to an address when the
email is opened. To request a read receipt set the address with
``setReadReceiptTo()``.

To request a read receipt:

* Set the address you want the receipt to be sent to with the
  ``setReadReceiptTo()`` method on the Message.

When the email is opened, if the mail client supports it a notification will be sent to this address.

.. note::

    Read receipts won't work for the majority of recipients since many mail
    clients auto-disable them. Those clients that will send a read receipt
    will make the user aware that one has been requested.

    .. code-block:: php

        $message->setReadReceiptTo('[email protected]');

Setting the Character Set
-------------------------

The character set of the message (and it's MIME parts) is set with the
``setCharset()`` method. You can also change the global default of UTF-8 by
working with the ``Swift_Preferences`` class.

Swift Mailer will default to the UTF-8 character set unless otherwise
overridden. UTF-8 will work in most instances since it includes all of the
standard US keyboard characters in addition to most international characters.

It is absolutely vital however that you know what character set your message
(or it's MIME parts) are written in otherwise your message may be received
completely garbled.

There are two places in Swift Mailer where you can change the character set:

* In the ``Swift_Preferences`` class

* On each individual message and/or MIME part

To set the character set of your Message:

* Change the global UTF-8 setting by calling
  ``Swift_Preferences::setCharset()``; or

* Call the ``setCharset()`` method on the message or the MIME part.

   .. code-block:: php

    // Approach 1: Change the global setting (suggested)
    Swift_Preferences::getInstance()->setCharset('iso-8859-2');

    // Approach 2: Call the setCharset() method of the message
    $message = Swift_Message::newInstance()
      ->setCharset('iso-8859-2');

    // Approach 3: Specify the charset when setting the body
    $message->setBody('My body', 'text/html', 'iso-8859-2');

    // Approach 4: Specify the charset for each part added
    $message->addPart('My part', 'text/plain', 'iso-8859-2');

Setting the Line Length
-----------------------

The length of lines in a message can be changed by using the ``setMaxLineLength()`` method on the message. It should be kept to less than
1000 characters.

Swift Mailer defaults to using 78 characters per line in a message. This is
done for historical reasons and so that the message can be easily viewed in
plain-text terminals.

To change the maximum length of lines in your Message:

* Call the ``setMaxLineLength()`` method on the Message.

Lines that are longer than the line length specified will be wrapped between
words.

.. note::

    You should never set a maximum length longer than 1000 characters
    according to RFC 2822. Doing so could have unspecified side-effects such
    as truncating parts of your message when it is transported between SMTP
    servers.

    .. code-block:: php

        $message->setMaxLineLength(1000);

Setting the Message Priority
----------------------------

You can change the priority of the message with ``setPriority()``. Setting the
priority will not change the way your email is sent -- it is purely an
indicative setting for the recipient.

The priority of a message is an indication to the recipient what significance
it has. Swift Mailer allows you to set the priority by calling the ``setPriority`` method. This method takes an integer value between 1 and 5:

* Highest
* High
* Normal
* Low
* Lowest

To set the message priority:

* Set the priority as an integer between 1 and 5 with the ``setPriority()``
  method on the Message.

.. code-block:: php

    // Indicate "High" priority
    $message->setPriority(2);

---

### Samples Development Frameworks Laravel Vendor Swiftmailer Swiftmailer Doc Overview (`samples/development-frameworks/laravel/vendor/swiftmailer/swiftmailer/doc/overview.rst`)

Library Overview
================

Most features (and more) of your every day mail client software are provided
by Swift Mailer, using object-oriented PHP code as the interface.

In this chapter we will take a short tour of the various components, which put
together form the Swift Mailer library as a whole. You will learn key
terminology used throughout the rest of this book and you will gain a little
understanding of the classes you will work with as you integrate Swift Mailer
into your application.

This chapter is intended to prepare you for the information contained in the
subsequent chapters of this book. You may choose to skip this chapter if you
are fairly technically minded, though it is likely to save you some time in
the long run if you at least read between the lines here.

System Requirements
-------------------

The basic requirements to operate Swift Mailer are extremely minimal and
easily achieved. Historically, Swift Mailer has supported both PHP 4 and PHP 5
by following a parallel development workflow. Now in it's fourth major
version, and Swift Mailer operates on servers running PHP 5.2 or higher.

The library aims to work with as many PHP 5 projects as possible:

* PHP 5.2 or higher, with the SPL extension (standard)

* Limited network access to connect to remote SMTP servers

* 8 MB or more memory limit (Swift Mailer uses around 2 MB)

Component Breakdown
-------------------

Swift Mailer is made up of many classes. Each of these classes can be grouped
into a general "component" group which describes the task it is designed to
perform.

We'll take a brief look at the components which form Swift Mailer in this
section of the book.

The Mailer

Transports are the classes in Swift Mailer that are responsible for
communicating with a service in order to deliver a Message. There are several
types of Transport in Swift Mailer, all of which implement the Swift_Transport
interface and offer underlying start(), stop() and send() methods.

Typically you will not need to know how a Transport works under-the-surface,
you will only need to know how to create an instance of one, and which one to
use for your environment.

+---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| Class                           | Features                                                                                    | Pros/cons                                                                                                                                     |
+=================================+=============================================================================================+===============================================================================================================================================+
| ``Swift_SmtpTransport``         | Sends messages over SMTP; Supports Authentication; Supports Encryption                      | Very portable; Pleasingly predictable results; Provides good feedback                                                                         |
+---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``Swift_SendmailTransport``     | Communicates with a locally installed ``sendmail`` executable (Linux/UNIX)                  | Quick time-to-run;  Provides less-accurate feedback than SMTP; Requires ``sendmail`` installation                                             |
+---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``Swift_MailTransport``         | Uses PHP's built-in ``mail()`` function                                                     | Very portable; Potentially unpredictable results; Provides extremely weak feedback                                                            |
+---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``Swift_LoadBalancedTransport`` | Cycles through a collection of the other Transports to manage load-reduction                | Provides graceful fallback if one Transport fails (e.g. an SMTP server is down); Keeps the load on remote services down by spreading the work |
+---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
| ``Swift_FailoverTransport``     | Works in conjunction with a collection of the other Transports to provide high-availability | Provides graceful fallback if one Transport fails (e.g. an SMTP server is down)                                                               |
+---------------------------------+---------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+

MIME Entities

Other-Header: Another value

The body content itself

Encoders are used to transform the content of Messages generated in Swift
Mailer into a format that is safe to send across the internet and that
conforms to RFC specifications.

Generally speaking you will not need to interact with the Encoders in Swift
Mailer -- the correct settings will be handled by the library itself.
However they are probably worth a brief mention in the event that you do want
to play with them.

Both the Headers and the body of all MIME entities (including the Message
itself) use Encoders to ensure the data they contain can be sent over the
internet without becoming corrupted or misinterpreted.

There are two types of Encoder: Base64 and Quoted-Printable.

Plugins
~~~~~~~

Plugins exist to extend, or modify the behaviour of Swift Mailer. They respond
to Events that are fired within the Transports during sending.

There are a number of Plugins provided as part of the base Swift Mailer
package and they all follow a common interface to respond to Events fired
within the library. Interfaces are provided to "listen" to each type of Event
fired and to act as desired when a listened-to Event occurs.

Although several plugins are provided with Swift Mailer out-of-the-box, the
Events system has been specifically designed to make it easy for experienced
object-oriented developers to write their own plugins in order to achieve
goals that may not be possible with the base library.

---

### Samples Development Frameworks Laravel Vendor Swiftmailer Swiftmailer Doc Plugins (`samples/development-frameworks/laravel/vendor/swiftmailer/swiftmailer/doc/plugins.rst`)

Plugins
=======

Plugins are provided with Swift Mailer and can be used to extend the behavior
of the library in situations where using simple class inheritance would be more complex.

AntiFlood Plugin
----------------

Many SMTP servers have limits on the number of messages that may be sent
during any single SMTP connection. The AntiFlood plugin provides a way to stay
within this limit while still managing a large number of emails.

A typical limit for a single connection is 100 emails. If the server you
connect to imposes such a limit, it expects you to disconnect after that
number of emails has been sent. You could manage this manually within a loop,
but the AntiFlood plugin provides the necessary wrapper code so that you don't
need to worry about this logic.

Regardless of limits imposed by the server, it's usually a good idea to be
conservative with the resources of the SMTP server. Sending will become
sluggish if the server is being over-used so using the AntiFlood plugin will
not be a bad idea even if no limits exist.

The AntiFlood plugin's logic is basically to disconnect and the immediately
re-connect with the SMTP server every X number of emails sent, where X is a
number you specify to the plugin.

You can also specify a time period in seconds that Swift Mailer should pause
for between the disconnect/re-connect process. It's a good idea to pause for a
short time (say 30 seconds every 100 emails) simply to give the SMTP server a
chance to process its queue and recover some resources.

Using the AntiFlood Plugin

require_once 'lib/swift_required.php';

// Create the Mailer using any Transport
$mailer = Swift_Mailer::newInstance(
  Swift_SmtpTransport::newInstance('smtp.example.org', 25)
);

// Use AntiFlood to re-connect after 100 emails
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100));

// And specify a time in seconds to pause for (30 secs)
$mailer->registerPlugin(new Swift_Plugins_AntiFloodPlugin(100, 30));

// Continue sending as normal
for ($lotsOfRecipients as $recipient) {
  ...

  $mailer->send( ... );
}

The Throttler Plugin -- like all plugins -- is added with the Mailer class'
``registerPlugin()`` method. It has two required constructor parameters that
tell it how to do its rate-limiting.

To use the Throttler plugin:

* Create an instance of the Mailer using any Transport you choose.

* Create an instance of the ``Swift_Plugins_ThrottlerPlugin`` class, passing
  the number of emails, or bytes you wish to limit by, along with the mode
  you're using.

* Register the plugin using the Mailer's ``registerPlugin()`` method.

* Continue using Swift Mailer to send messages as normal.

When Swift Mailer sends messages it will keep track of the rate at which sending
messages is occurring. If it realises that sending is happening too fast, it
will cause your program to ``sleep()`` for enough time to average out the rate.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the Mailer using any Transport
    $mailer = Swift_Mailer::newInstance(
      Swift_SmtpTransport::newInstance('smtp.example.org', 25)
    );

    // Rate limit to 100 emails per-minute
    $mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
      100, Swift_Plugins_ThrottlerPlugin::MESSAGES_PER_MINUTE
    ));

    // Rate limit to 10MB per-minute
    $mailer->registerPlugin(new Swift_Plugins_ThrottlerPlugin(
      1024 * 1024 * 10, Swift_Plugins_ThrottlerPlugin::BYTES_PER_MINUTE
    ));

    // Continue sending as normal
    for ($lotsOfRecipients as $recipient) {
      ...

      $mailer->send( ... );
    }

Logger Plugin
-------------

The Logger plugins helps with debugging during the process of sending. It can
help to identify why an SMTP server is rejecting addresses, or any other
hard-to-find problems that may arise.

The Logger plugin comes in two parts. There's the plugin itself, along with
one of a number of possible Loggers that you may choose to use. For example,
the logger may output messages directly in realtime, or it may capture
messages in an array.

One other notable feature is the way in which the Logger plugin changes
Exception messages. If Exceptions are being thrown but the error message does
not provide conclusive information as to the source of the problem (such as an
ambiguous SMTP error) the Logger plugin includes the entire SMTP transcript in
the error message so that debugging becomes a simpler task.

There are a few available Loggers included with Swift Mailer, but writing your
own implementation is incredibly simple and is achieved by creating a short
class that implements the ``Swift_Plugins_Logger`` interface.

* ``Swift_Plugins_Loggers_ArrayLogger``: Keeps a collection of log messages
  inside an array. The array content can be cleared or dumped out to the
  screen.

* ``Swift_Plugins_Loggers_EchoLogger``: Prints output to the screen in
  realtime. Handy for very rudimentary debug output.

Using the Logger Plugin
~~~~~~~~~~~~~~~~~~~~~~~

The Logger Plugin -- like all plugins -- is added with the Mailer class'
``registerPlugin()`` method. It accepts an instance of ``Swift_Plugins_Logger``
in its constructor.

To use the Logger plugin:

* Create an instance of the Mailer using any Transport you choose.

* Create an instance of the a Logger implementation of
  ``Swift_Plugins_Logger``.

* Create an instance of the ``Swift_Plugins_LoggerPlugin`` class, passing the
  created Logger instance to its constructor.

* Register the plugin using the Mailer's ``registerPlugin()`` method.

* Continue using Swift Mailer to send messages as normal.

* Dump the contents of the log with the logger's ``dump()`` method.

When Swift Mailer sends messages it will keep a log of all the interactions
with the underlying Transport being used. Depending upon the Logger that has
been used the behaviour will differ, but all implementations offer a way to
get the contents of the log.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the Mailer using any Transport
    $mailer = Swift_Mailer::newInstance(
     Swift_SmtpTransport::newInstance('smtp.example.org', 25)
    );

    // To use the ArrayLogger
    $logger = new Swift_Plugins_Loggers_ArrayLogger();
    $mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));

    // Or to use the Echo Logger
    $logger = new Swift_Plugins_Loggers_EchoLogger();
    $mailer->registerPlugin(new Swift_Plugins_LoggerPlugin($logger));

    // Continue sending as normal
    for ($lotsOfRecipients as $recipient) {
     ...

     $mailer->send( ... );
    }

    // Dump the log contents
    // NOTE: The EchoLogger dumps in realtime so dump() does nothing for it
    echo $logger->dump();

Decorator Plugin
----------------

Often there's a need to send the same message to multiple recipients, but with
tiny variations such as the recipient's name being used inside the message
body. The Decorator plugin aims to provide a solution for allowing these small
differences.

The decorator plugin works by intercepting the sending process of Swift
Mailer, reading the email address in the To: field and then looking up a set
of replacements for a template.

While the use of this plugin is simple, it is probably the most commonly
misunderstood plugin due to the way in which it works. The typical mistake
users make is to try registering the plugin multiple times (once for each
recipient) -- inside a loop for example. This is incorrect.

The Decorator plugin should be registered just once, but containing the list
of all recipients prior to sending. It will use this list of recipients to
find the required replacements during sending.

Using the Decorator Plugin

The replacements array becomes a 2-dimensional array whose keys are the
email addresses and whose values are an associative array of replacements
for that email address. The curly braces used in this example can be any
type of syntax you choose, provided they match the placeholders in your
email template.

.. code-block:: php

    $replacements = array();
    foreach ($users as $user) {
      $replacements[$user['email']] = array(
        '{username}'=>$user['username'],
        '{password}'=>$user['password']
      );
    }

$decorator = new Swift_Plugins_DecoratorPlugin($replacements);

$mailer->registerPlugin($decorator);

$message = Swift_Message::newInstance()
  ->setSubject('Important notice for {username}')
  ->setBody(
    "Hello {username}, we have reset your password to {password}\n" .
    "Please log in and change it at your earliest convenience."
  )
  ;

foreach ($users as $user) {
  $message->addTo($user['email']);
}

Subject: Important notice for smilingsunshine2009

Hello smilingsunshine2009, we have reset your password to rainyDays
Please log in and change it at your earliest convenience.

Subject: Important notice for billy-bo-bob

Hello billy-bo-bob, we have reset your password to dancingOctopus
Please log in and change it at your earliest convenience.

Filling an array with replacements may not be the best solution for providing
replacement information to the decorator. If you have a more elegant algorithm
that performs replacement lookups on-the-fly you may provide your own
implementation.

Providing your own replacements lookup implementation for the Decorator is
simply a matter of passing an instance of ``Swift_Plugins_Decorator_Replacements`` to the decorator plugin's constructor,
rather than passing in an array.

The Replacements interface is very simple to implement since it has just one
method: ``getReplacementsFor($address)``.

Imagine you want to look up replacements from a database on-the-fly, you might
provide an implementation that does this. You need to create a small class.

.. code-block:: php

    class DbReplacements implements Swift_Plugins_Decorator_Replacements {
      public function getReplacementsFor($address) {
        $sql = sprintf(
          "SELECT * FROM user WHERE email = '%s'",
          mysql_real_escape_string($address)
        );

        $result = mysql_query($sql);

        if ($row = mysql_fetch_assoc($result)) {
          return array(
            '{username}'=>$row['username'],
            '{password}'=>$row['password']
          );
        }
      }
    }

Now all you need to do is pass an instance of your class into the Decorator
plugin's constructor instead of passing an array.

.. code-block:: php

    $decorator = new Swift_Plugins_DecoratorPlugin(new DbReplacements());

    $mailer->registerPlugin($decorator);

For each message sent, the plugin will call your class' ``getReplacementsFor()``
method to find the array of replacements it needs.

.. note::

    If your lookup algorithm is case sensitive, you should transform the
    ``$address`` argument as appropriate -- for example by passing it
    through ``strtolower()``.

---

### Samples Development Frameworks Laravel Vendor Swiftmailer Swiftmailer Doc Sending (`samples/development-frameworks/laravel/vendor/swiftmailer/swiftmailer/doc/sending.rst`)

Sending Messages
================

Quick Reference for Sending a Message
-------------------------------------

Sending a message is very straightforward. You create a Transport, use it to
create the Mailer, then you use the Mailer to send the message.

To send a Message:

* Create a Transport from one of the provided Transports --
  ``Swift_SmtpTransport``, ``Swift_SendmailTransport``, ``Swift_MailTransport``
  or one of the aggregate Transports.

* Create an instance of the ``Swift_Mailer`` class, using the Transport as
  it's constructor parameter.

* Create a Message.

* Send the message via the ``send()`` method on the Mailer object.

.. caution::

    The ``Swift_SmtpTransport`` and ``Swift_SendmailTransport`` transports use
    ``proc_*`` PHP functions, which might not be available on your PHP
    installation. You can easily check if that's the case by running the
    following PHP script: ``<?php echo function_exists('proc_open') ? "Yep,
    that will work" : "Sorry, that won't work";``

When using ``send()`` the message will be sent just like it would be sent if you
used your mail client. An integer is returned which includes the number of
successful recipients. If none of the recipients could be sent to then zero will
be returned, which equates to a boolean ``false``. If you set two ``To:``
recipients and three ``Bcc:`` recipients in the message and all of the
recipients are delivered to successfully then the value 5 will be returned.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the Transport
    $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25)
      ->setUsername('your username')
      ->setPassword('your password')
      ;

    /*
    You could alternatively use a different transport such as Sendmail or Mail:

    // Sendmail
    $transport = Swift_SendmailTransport::newInstance('/usr/sbin/sendmail -bs');

    // Mail
    $transport = Swift_MailTransport::newInstance();
    */

    // Create the Mailer using your created Transport
    $mailer = Swift_Mailer::newInstance($transport);

    // Create a message
    $message = Swift_Message::newInstance('Wonderful Subject')
      ->setFrom(array('[email protected]' => 'John Doe'))
      ->setTo(array('[email protected]', '[email protected]' => 'A name'))
      ->setBody('Here is the message itself')
      ;

    // Send the message
    $result = $mailer->send($message);

Transport Types
~~~~~~~~~~~~~~~

A Transport is the component which actually does the sending. You need to
provide a Transport object to the Mailer class and there are several possible
options.

Typically you will not need to know how a Transport works under-the-surface,
you will only need to know how to create an instance of one, and which one to
use for your environment.

The SMTP Transport
..................

The SMTP Transport sends messages over the (standardized) Simple Message
Transfer Protocol.  It can deal with encryption and authentication.

The SMTP Transport, ``Swift_SmtpTransport`` is without doubt the most commonly
used Transport because it will work on 99% of web servers (I just made that
number up, but you get the idea). All the server needs is the ability to
connect to a remote (or even local) SMTP server on the correct port number
(usually 25).

SMTP servers often require users to authenticate with a username and password
before any mail can be sent to other domains. This is easily achieved using
Swift Mailer with the SMTP Transport.

SMTP is a protocol -- in other words it's a "way" of communicating a job
to be done (i.e. sending a message). The SMTP protocol is the fundamental
basis on which messages are delivered all over the internet 7 days a week, 365
days a year. For this reason it's the most "direct" method of sending messages
you can use and it's the one that will give you the most power and feedback
(such as delivery failures) when using Swift Mailer.

Because SMTP is generally run as a remote service (i.e. you connect to it over
the network/internet) it's extremely portable from server-to-server. You can
easily store the SMTP server address and port number in a configuration file
within your application and adjust the settings accordingly if the code is
moved or if the SMTP server is changed.

Some SMTP servers -- Google for example -- use encryption for security reasons.
Swift Mailer supports using both SSL and TLS encryption settings.

Using the SMTP Transport
^^^^^^^^^^^^^^^^^^^^^^^^

The SMTP Transport is easy to use. Most configuration options can be set with
the constructor.

To use the SMTP Transport you need to know which SMTP server your code needs
to connect to. Ask your web host if you're not sure. Lots of people ask me who
to connect to -- I really can't answer that since it's a setting that's
extremely specific to your hosting environment.

To use the SMTP Transport:

* Call ``Swift_SmtpTransport::newInstance()`` with the SMTP server name and
  optionally with a port number (defaults to 25).

* Use the returned object to create the Mailer.

A connection to the SMTP server will be established upon the first call to
``send()``.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the Transport
    $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25);

    // Create the Mailer using your created Transport
    $mailer = Swift_Mailer::newInstance($transport);

    /*
    It's also possible to use multiple method calls

    $transport = Swift_SmtpTransport::newInstance()
      ->setHost('smtp.example.org')
      ->setPort(25)
      ;
    */

Encrypted SMTP
^^^^^^^^^^^^^^

You can use SSL or TLS encryption with the SMTP Transport by specifying it as
a parameter or with a method call.

To use encryption with the SMTP Transport:

* Pass the encryption setting as a third parameter to
  ``Swift_SmtpTransport::newInstance()``; or

* Call the ``setEncryption()`` method on the Transport.

A connection to the SMTP server will be established upon the first call to
``send()``. The connection will be initiated with the correct encryption
settings.

.. note::

    For SSL or TLS encryption to work your PHP installation must have
    appropriate OpenSSL transports wrappers. You can check if "tls" and/or
    "ssl" are present in your PHP installation by using the PHP function
    ``stream_get_transports()``

    .. code-block:: php

        require_once 'lib/swift_required.php';

        // Create the Transport
        $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 587, 'ssl');

        // Create the Mailer using your created Transport
        $mailer = Swift_Mailer::newInstance($transport);

        /*
        It's also possible to use multiple method calls

        $transport = Swift_SmtpTransport::newInstance()
          ->setHost('smtp.example.org')
          ->setPort(587)
          ->setEncryption('ssl')
          ;
        */

SMTP with a Username and Password
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Some servers require authentication. You can provide a username and password
with ``setUsername()`` and ``setPassword()`` methods.

To use a username and password with the SMTP Transport:

* Create the Transport with ``Swift_SmtpTransport::newInstance()``.

* Call the ``setUsername()`` and ``setPassword()`` methods on the Transport.

Your username and password will be used to authenticate upon first connect
when ``send()`` are first used on the Mailer.

If authentication fails, an Exception of type ``Swift_TransportException`` will
be thrown.

.. note::

    If you need to know early whether or not authentication has failed and an
    Exception is going to be thrown, call the ``start()`` method on the
    created Transport.

    .. code-block:: php

        require_once 'lib/swift_required.php';

        // Create the Transport the call setUsername() and setPassword()
        $transport = Swift_SmtpTransport::newInstance('smtp.example.org', 25)
          ->setUsername('username')
          ->setPassword('password')
          ;

        // Create the Mailer using your created Transport
        $mailer = Swift_Mailer::newInstance($transport);

The Sendmail Transport
......................

The Sendmail Transport sends messages by communicating with a locally
installed MTA -- such as ``sendmail``.

The Sendmail Transport, ``Swift_SendmailTransport`` does not directly connect to
any remote services. It is designed for Linux servers that have ``sendmail``
installed. The Transport starts a local ``sendmail`` process and sends messages
to it. Usually the ``sendmail`` process will respond quickly as it spools your
messages to disk before sending them.

The Transport is named the Sendmail Transport for historical reasons
(``sendmail`` was the "standard" UNIX tool for sending e-mail for years). It
will send messages using other transfer agents such as Exim or Postfix despite
its name, provided they have the relevant sendmail wrappers so that they can be
started with the correct command-line flags.

It's a common misconception that because the Sendmail Transport returns a
result very quickly it must therefore deliver messages to recipients quickly
-- this is not true. It's not slow by any means, but it's certainly not
faster than SMTP when it comes to getting messages to the intended recipients.
This is because sendmail itself sends the messages over SMTP once they have
been quickly spooled to disk.

The Sendmail Transport has the potential to be just as smart of the SMTP
Transport when it comes to notifying Swift Mailer about which recipients were
rejected, but in reality the majority of locally installed ``sendmail``
instances are not configured well enough to provide any useful feedback. As such
Swift Mailer may report successful deliveries where they did in fact fail before
they even left your server.

You can run the Sendmail Transport in two different modes specified by command
line flags:

* "``-bs``" runs in SMTP mode so theoretically it will act like the SMTP
  Transport

* "``-t``" runs in piped mode with no feedback, but theoretically faster,
  though not advised

You can think of the Sendmail Transport as a sort of asynchronous SMTP Transport
-- though if you have problems with delivery failures you should try using the
SMTP Transport instead. Swift Mailer isn't doing the work here, it's simply
passing the work to somebody else (i.e. ``sendmail``).

Using the Sendmail Transport
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To use the Sendmail Transport you simply need to call
``Swift_SendmailTransport::newInstance()`` with the command as a parameter.

To use the Sendmail Transport you need to know where ``sendmail`` or another MTA
exists on the server. Swift Mailer uses a default value of
``/usr/sbin/sendmail``, which should work on most systems.

You specify the entire command as a parameter (i.e. including the command line
flags). Swift Mailer supports operational modes of "``-bs``" (default) and
"``-t``".

.. note::

    If you run sendmail in "``-t``" mode you will get no feedback as to whether
    or not sending has succeeded. Use "``-bs``" unless you have a reason not to.

To use the Sendmail Transport:

* Call ``Swift_SendmailTransport::newInstance()`` with the command, including
  the correct command line flags. The default is to use ``/usr/sbin/sendmail
  -bs`` if this is not specified.

* Use the returned object to create the Mailer.

A sendmail process will be started upon the first call to ``send()``. If the
process cannot be started successfully an Exception of type
``Swift_TransportException`` will be thrown.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the Transport
    $transport = Swift_SendmailTransport::newInstance('/usr/sbin/exim -bs');

    // Create the Mailer using your created Transport
    $mailer = Swift_Mailer::newInstance($transport);

The Mail Transport
..................

The Mail Transport sends messages by delegating to PHP's internal
``mail()`` function.

In my experience -- and others' -- the ``mail()`` function is not particularly
predictable, or helpful.

Quite notably, the ``mail()`` function behaves entirely differently between
Linux and Windows servers. On linux it uses ``sendmail``, but on Windows it uses
SMTP.

In order for the ``mail()`` function to even work at all ``php.ini`` needs to be
configured correctly, specifying the location of sendmail or of an SMTP server.

The problem with ``mail()`` is that it "tries" to simplify things to the point
that it actually makes things more complex due to poor interface design. The
developers of Swift Mailer have gone to a lot of effort to make the Mail
Transport work with a reasonable degree of consistency.

Serious drawbacks when using this Transport are:

* Unpredictable message headers

* Lack of feedback regarding delivery failures

* Lack of support for several plugins that require real-time delivery feedback

It's a last resort, and we say that with a passion!

Using the Mail Transport
^^^^^^^^^^^^^^^^^^^^^^^^

To use the Mail Transport you simply need to call
``Swift_MailTransport::newInstance()``. It's unlikely you'll need to configure
the Transport.

To use the Mail Transport:

* Call ``Swift_MailTransport::newInstance()``.

* Use the returned object to create the Mailer.

Messages will be sent using the ``mail()`` function.

.. note::

    The ``mail()`` function can take a ``$additional_parameters`` parameter.
    Swift Mailer sets this to "``-f%s``" by default, where the "``%s``" is
    substituted with the address of the sender (via a ``sprintf()``) at send
    time. You may override this default by passing an argument to
    ``newInstance()``.

    .. code-block:: php

        require_once 'lib/swift_required.php';

        // Create the Transport
        $transport = Swift_MailTransport::newInstance();

        // Create the Mailer using your created Transport
        $mailer = Swift_Mailer::newInstance($transport);

Available Methods for Sending Messages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Mailer class offers two methods for sending Messages -- ``send()``.
Each behaves in a slightly different way.

When a message is sent in Swift Mailer, the Mailer class communicates with
whichever Transport class you have chosen to use.

Each recipient in the message should either be accepted or rejected by the
Transport. For example, if the domain name on the email address is not
reachable the SMTP Transport may reject the address because it cannot process
it. Whichever method you use -- ``send()`` -- Swift Mailer will return
an integer indicating the number of accepted recipients.

.. note::

    It's possible to find out which recipients were rejected -- we'll cover that
    later in this chapter.

Using the ``send()`` Method
...........................

The ``send()`` method of the ``Swift_Mailer`` class sends a message using
exactly the same logic as your Desktop mail client would use. Just pass it a
Message and get a result.

To send a Message with ``send()``:

* Create a Transport from one of the provided Transports --
  ``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
  ``Swift_MailTransport`` or one of the aggregate Transports.

* Create an instance of the ``Swift_Mailer`` class, using the Transport as
  it's constructor parameter.

* Create a Message.

* Send the message via the ``send()`` method on the Mailer object.

The message will be sent just like it would be sent if you used your mail
client. An integer is returned which includes the number of successful
recipients. If none of the recipients could be sent to then zero will be
returned, which equates to a boolean ``false``. If you set two
``To:`` recipients and three ``Bcc:`` recipients in the message and all of the
recipients are delivered to successfully then the value 5 will be returned.

.. code-block:: php

    require_once 'lib/swift_required.php';

    // Create the Transport
    $transport = Swift_SmtpTransport::newInstance('localhost', 25);

    // Create the Mailer using your created Transport
    $mailer = Swift_Mailer::newInstance($transport);

    // Create a message
    $message = Swift_Message::newInstance('Wonderful Subject')
      ->setFrom(array('[email protected]' => 'John Doe'))
      ->setTo(array('[email protected]', '[email protected]' => 'A name'))
      ->setBody('Here is the message itself')
      ;

    // Send the message
    $numSent = $mailer->send($message);

    printf("Sent %d messages\n", $numSent);

    /* Note that often that only the boolean equivalent of the
       return value is of concern (zero indicates FALSE)

    if ($mailer->send($message))
    {
      echo "Sent\n";
    }
    else
    {
      echo "Failed\n";
    }

    */

Sending Emails in Batch
.......................

If you want to send a separate message to each recipient so that only their
own address shows up in the ``To:`` field, follow the following recipe:

* Create a Transport from one of the provided Transports --
  ``Swift_SmtpTransport``, ``Swift_SendmailTransport``,
  ``Swift_MailTransport`` or one of the aggregate Transports.

* Create an instance of the ``Swift_Mailer`` class, using the Transport as
  it's constructor parameter.

* Create a Message.

* Iterate over the recipients and send message via the ``send()`` method on
  the Mailer object.

Each recipient of the messages receives a different copy with only their own
email address on the ``To:`` field.

Make sure to add only valid email addresses as recipients. If you try to add an
invalid email address with ``setTo()``, ``setCc()`` or ``setBcc()``, Swift
Mailer will throw a ``Swift_RfcComplianceException``.

If you add recipients automatically based on a data source that may contain
invalid email addresses, you can prevent possible exceptions by validating the
addresses using ``Swift_Validate::email($email)`` and only adding addresses
that validate. Another way would be to wrap your ``setTo()``, ``setCc()`` and
``setBcc()`` calls in a try-catch block and handle the
``Swift_RfcComplianceException`` in the catch block.

Handling invalid addresses properly is especially important when sending emails
in large batches since a single invalid address might cause an unhandled
exception and stop the execution or your script early.

.. note::

    In the following example, two emails are sent. One to each of
    ``[email protected]`` and ``[email protected]``. These recipients will
    not be aware of each other.

    .. code-block:: php

        require_once 'lib/swift_required.php';

        // Create the Transport
        $transport = Swift_SmtpTransport::newInstance('localhost', 25);

        // Create the Mailer using your created Transport
        $mailer = Swift_Mailer::newInstance($transport);

        // Create a message
        $message = Swift_Message::newInstance('Wonderful Subject')
          ->setFrom(array('[email protected]' => 'John Doe'))
          ->setBody('Here is the message itself')
          ;

        // Send the message
        $failedRecipients = array();
        $numSent = 0;
        $to = array('[email protected]', '[email protected]' => 'A name');

        foreach ($to as $address => $name)
        {
          if (is_int($address)) {
            $message->setTo($name);
          } else {
            $message->setTo(array($address => $name));
          }

          $numSent += $mailer->send($message, $failedRecipients);
        }

        printf("Sent %d messages\n", $numSent);

Finding out Rejected Addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It's possible to get a list of addresses that were rejected by the Transport
by using a by-reference parameter to ``send()``.

As Swift Mailer attempts to send the message to each address given to it, if a
recipient is rejected it will be added to the array. You can pass an existing
array, otherwise one will be created by-reference.

Collecting the list of recipients that were rejected can be useful in
circumstances where you need to "prune" a mailing list for example when some
addresses cannot be delivered to.

Getting Failures By-reference
.............................

Collecting delivery failures by-reference with the ``send()`` method is as
simple as passing a variable name to the method call.

To get failed recipients by-reference:

* Pass a by-reference variable name to the ``send()`` method of the Mailer
  class.

If the Transport rejects any of the recipients, the culprit addresses will be
added to the array provided by-reference.

.. note::

    If the variable name does not yet exist, it will be initialized as an
    empty array and then failures will be added to that array. If the variable
    already exists it will be type-cast to an array and failures will be added
    to it.

    .. code-block:: php

        $mailer = Swift_Mailer::newInstance( ... );

        $message = Swift_Message::newInstance( ... )
          ->setFrom( ... )
          ->setTo(array(
            '[email protected]' => 'Receiver Name',
            '[email protected]' => 'A name',
            '[email protected]' => 'Other Name'
          ))
          ->setBody( ... )
          ;

        // Pass a variable name to the send() method
        if (!$mailer->send($message, $failures))
        {
          echo "Failures:";
          print_r($failures);
        }

        /*
        Failures:
        Array (
          0 => [email protected],
          1 => [email protected]
        )
        */

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Cookbook Default Expectations (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/cookbook/default_expectations.rst`)

.. index::
    single: Cookbook; Default Mock Expectations

Default Mock Expectations
=========================

Often in unit testing, we end up with sets of tests which use the same object
dependency over and over again. Rather than mocking this class/object within
every single unit test (requiring a mountain of duplicate code), we can
instead define reusable default mocks within the test case's ``setup()``
method. This even works where unit tests use varying expectations on the same
or similar mock object.

How this works, is that you can define mocks with default expectations. Then,
in a later unit test, you can add or fine-tune expectations for that specific
test. Any expectation can be set as a default using the ``byDefault()``
declaration.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Cookbook Detecting Mock Objects (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/cookbook/detecting_mock_objects.rst`)

.. index::
    single: Cookbook; Detecting Mock Objects

Detecting Mock Objects
======================

Users may find it useful to check whether a given object is a real object or a
simulated Mock Object. All Mockery mocks implement the
``\Mockery\MockInterface`` interface which can be used in a type check.

.. code-block:: php

    assert($mightBeMocked instanceof \Mockery\MockInterface);

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Cookbook Index (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/cookbook/index.rst`)

Cookbook
========

.. toctree::
    :hidden:

    default_expectations
    detecting_mock_objects
    mocking_hard_dependencies

.. include:: map.rst.inc

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Cookbook Mocking Hard Dependencies (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/cookbook/mocking_hard_dependencies.rst`)

.. index::
    single: Cookbook; Mocking Hard Dependencies

Mocking Hard Dependencies (new Keyword)
=======================================

One prerequisite to mock hard dependencies is that the code we are trying to test uses autoloading.

Let's take the following code for an example:

.. code-block:: php

    <?php
    namespace App;
    class Service
    {
        function callExternalService($param)
        {
            $externalService = new Service\External();
            $externalService->sendSomething($param);
            return $externalService->getSomething();
        }
    }

The way we can test this without doing any changes to the code itself is by creating :doc:`instance mocks </reference/instance_mocking>` by using the ``overload`` prefix.

.. code-block:: php

    <?php
    namespace AppTest;
    use Mockery as m;
    class ServiceTest extends \PHPUnit_Framework_TestCase
    {
        public function testCallingExternalService()
        {
            $param = 'Testing';

            $externalMock = m::mock('overload:App\Service\External');
            $externalMock->shouldReceive('sendSomething')
                ->once()
                ->with($param);
            $externalMock->shouldReceive('getSomething')
                ->once()
                ->andReturn('Tested!');

            $service = new \App\Service();

            $result = $service->callExternalService($param);

            $this->assertSame('Tested!', $result);
        }
    }

If we run this test now, it should pass. Mockery does its job and our ``App\Service`` will use the mocked external service instead of the real one.

The problem with this is when we want to, for example, test the ``App\Service\External`` itself, or if we use that class somewhere else in our tests.

When Mockery overloads a class, because of how PHP works with files, that overloaded class file must not be included otherwise Mockery will throw a "class already exists" exception. This is where autoloading kicks in and makes our job a lot easier.

To make this possible, we'll tell PHPUnit to run the tests that have overloaded classes in separate processes and to not preserve global state. That way we'll avoid having the overloaded class included more than once. Of course this has its downsides as these tests will run slower.

Our test example from above now becomes:

.. code-block:: php

    <?php
    namespace AppTest;
    use Mockery as m;
    /**
     * @runTestsInSeparateProcesses
     * @preserveGlobalState disabled
     */
    class ServiceTest extends \PHPUnit_Framework_TestCase
    {
        public function testCallingExternalService()
        {
            $param = 'Testing';

            $externalMock = m::mock('overload:App\Service\External');
            $externalMock->shouldReceive('sendSomething')
                ->once()
                ->with($param);
            $externalMock->shouldReceive('getSomething')
                ->once()
                ->andReturn('Tested!');

            $service = new \App\Service();

            $result = $service->callExternalService($param);

            $this->assertSame('Tested!', $result);
        }
    }

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Getting Started Index (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/getting_started/index.rst`)

Getting Started
===============

.. toctree::
    :hidden:

    installation
    upgrading
    simple_example

.. include:: map.rst.inc

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Getting Started Installation (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/getting_started/installation.rst`)

.. index::
    single: Installation

Installation
============

Mockery can be installed using Composer, PEAR or by cloning it from its GitHub
repository.  These three options are outlined below.

Composer
--------

You can read more about Composer on `getcomposer.org <https://getcomposer.org>`_.
To install Mockery using Composer, first install Composer for your project
using the instructions on the `Composer download page <https://getcomposer.org/download/>`_.
You can then define your development dependency on Mockery using the suggested
parameters below. While every effort is made to keep the master branch stable,
you may prefer to use the current stable version tag instead (use the
``@stable`` tag).

.. code-block:: json

    {
        "require-dev": {
            "mockery/mockery": "dev-master"
        }
    }

To install, you then may call:

.. code-block:: bash

    php composer.phar update

This will install Mockery as a development dependency, meaning it won't be
installed when using ``php composer.phar update --no-dev`` in production.

PEAR
----

Mockery is hosted on the `survivethedeepend.com <http://pear.survivethedeepend.com>`_
PEAR channel and can be installed using the following commands:

.. code-block:: bash

    sudo pear channel-discover pear.survivethedeepend.com
    sudo pear channel-discover hamcrest.googlecode.com/svn/pear
    sudo pear install --alldeps deepend/Mockery

Git
---

The Git repository hosts the development version in its master branch. You can
install this using Composer by referencing ``dev-master`` as your preferred
version in your project's ``composer.json`` file as the earlier example shows.

You may also install this development version using PEAR:

.. code-block:: bash

    git clone git://github.com/padraic/mockery.git
    cd mockery
    sudo pear channel-discover hamcrest.googlecode.com/svn/pear
    sudo pear install --alldeps package.xml

The above processes will install both Mockery and Hamcrest. While omitting
Hamcrest will not break Mockery, Hamcrest is recommended as it adds a wider
variety of functionality for argument matching.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Getting Started Simple Example (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/getting_started/simple_example.rst`)

.. index::
    single: Getting Started; Simple Example

Simple Example
==============

Imagine we have a ``Temperature`` class which samples the temperature of a
locale before reporting an average temperature. The data could come from a web
service or any other data source, but we do not have such a class at present.
We can, however, assume some basic interactions with such a class based on its
interaction with the ``Temperature`` class:

.. code-block:: php

    class Temperature
    {

        public function __construct($service)
        {
            $this->_service = $service;
        }

        public function average()
        {
            $total = 0;
            for ($i=0;$i<3;$i++) {
                $total += $this->_service->readTemp();
            }
            return $total/3;
        }

    }

Even without an actual service class, we can see how we expect it to operate.
When writing a test for the ``Temperature`` class, we can now substitute a
mock object for the real service which allows us to test the behaviour of the
``Temperature`` class without actually needing a concrete service instance.

.. code-block:: php

    use \Mockery as m;

    class TemperatureTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            m::close();
        }

        public function testGetsAverageTemperatureFromThreeServiceReadings()
        {
            $service = m::mock('service');
            $service->shouldReceive('readTemp')->times(3)->andReturn(10, 12, 14);

            $temperature = new Temperature($service);

            $this->assertEquals(12, $temperature->average());
        }

    }

.. note::

    PHPUnit integration can remove the need for a ``tearDown()`` method. See
    ":doc:`/reference/phpunit_integration`" for more information.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Getting Started Upgrading (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/getting_started/upgrading.rst`)

.. index::
    single: Upgrading

Upgrading
=========

Upgrading to 0.9
----------------

The generator was completely rewritten, so any code with a deep integration to
mockery will need evaluating

Upgrading to 0.8
----------------

Since the release of 0.8.0 the following behaviours were altered:

1. The ``shouldIgnoreMissing()`` behaviour optionally applied to mock objects
   returned an instance of ``\Mockery\Undefined`` when methods called did not
   match a known expectation. Since 0.8.0, this behaviour was switched to
   returning ``null`` instead. You can restore the 0.7.2 behavour by using the
   following:

   .. code-block:: php

       $mock = \Mockery::mock('stdClass')->shouldIgnoreMissing()->asUndefined();

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Argument Validation (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/argument_validation.rst`)

.. index::
    single: Argument Validation

Argument Validation
===================

The arguments passed to the ``with()`` declaration when setting up an
expectation determine the criteria for matching method calls to expectations.
Thus, you can setup up many expectations for a single method, each
differentiated by the expected arguments. Such argument matching is done on a
"best fit" basis.  This ensures explicit matches take precedence over
generalised matches.

An explicit match is merely where the expected argument and the actual
argument are easily equated (i.e. using ``===`` or ``==``). More generalised
matches are possible using regular expressions, class hinting and the
available generic matchers. The purpose of generalised matchers is to allow
arguments be defined in non-explicit terms, e.g. ``Mockery::any()`` passed to
``with()`` will match **any** argument in that position.

Mockery's generic matchers do not cover all possibilities but offers optional
support for the Hamcrest library of matchers. Hamcrest is a PHP port of the
similarly named Java library (which has been ported also to Python, Erlang,
etc).  I strongly recommend using Hamcrest since Mockery simply does not need
to duplicate Hamcrest's already impressive utility which itself promotes a
natural English DSL.

The example below show Mockery matchers and their Hamcrest equivalent.
Hamcrest uses functions (no namespacing).

Here's a sample of the possibilities.

.. code-block:: php

    with(1)

Matches the integer ``1``. This passes the ``===`` test (identical). It does
facilitate a less strict ``==`` check (equals) where the string ``'1'`` would
also match the
argument.

.. code-block:: php

    with(\Mockery::any()) OR with(anything())

Matches any argument. Basically, anything and everything passed in this
argument slot is passed unconstrained.

.. code-block:: php

    with(\Mockery::type('resource')) OR with(resourceValue()) OR with(typeOf('resource'))

Matches any resource, i.e. returns true from an ``is_resource()`` call. The
Type matcher accepts any string which can be attached to ``is_`` to form a
valid type check. For example, ``\Mockery::type('float')`` or Hamcrest's
``floatValue()`` and ``typeOf('float')`` checks using ``is_float()``, and
``\Mockery::type('callable')`` or Hamcrest's ``callable()`` uses
``is_callable()``.

The Type matcher also accepts a class or interface name to be used in an
``instanceof`` evaluation of the actual argument (similarly Hamcrest uses
``anInstanceOf()``).

You may find a full list of the available type checkers at
`php.net <http://www.php.net/manual/en/ref.var.php>`_ or browse Hamcrest's function
list in
`the Hamcrest code <http://code.google.com/p/hamcrest/source/browse/trunk/hamcrest-php/hamcrest/Hamcrest.php>`_.

.. code-block:: php

    with(\Mockery::on(closure))

The On matcher accepts a closure (anonymous function) to which the actual
argument will be passed. If the closure evaluates to (i.e. returns) boolean
``true`` then the argument is assumed to have matched the expectation. This is
invaluable where your argument expectation is a bit too complex for or simply
not implemented in the current default matchers.

There is no Hamcrest version of this functionality.

.. code-block:: php

    with('/^foo/') OR with(matchesPattern('/^foo/'))

The argument declarator also assumes any given string may be a regular
expression to be used against actual arguments when matching. The regex option
is only used when a) there is no ``===`` or ``==`` match and b) when the regex
is verified to be a valid regex (i.e. does not return false from
``preg_match()``).  If the regex detection doesn't suit your tastes, Hamcrest
offers the more explicit ``matchesPattern()`` function.

.. code-block:: php

    with(\Mockery::ducktype('foo', 'bar'))

The Ducktype matcher is an alternative to matching by class type. It simply
matches any argument which is an object containing the provided list of
methods to call.

There is no Hamcrest version of this functionality.

.. code-block:: php

    with(\Mockery::mustBe(2)) OR with(identicalTo(2))

The MustBe matcher is more strict than the default argument matcher. The
default matcher allows for PHP type casting, but the MustBe matcher also
verifies that the argument must be of the same type as the expected value.
Thus by default, the argument `'2'` matches the actual argument 2 (integer)
but the MustBe matcher would fail in the same situation since the expected
argument was a string and instead we got an integer.

Note: Objects are not subject to an identical comparison using this matcher
since PHP would fail the comparison if both objects were not the exact same
instance. This is a hindrance when objects are generated prior to being
returned, since an identical match just would never be possible.

.. code-block:: php

    with(\Mockery::not(2)) OR with(not(2))

The Not matcher matches any argument which is not equal or identical to the
matcher's parameter.

.. code-block:: php

    with(\Mockery::anyOf(1, 2)) OR with(anyOf(1,2))

Matches any argument which equals any one of the given parameters.

.. code-block:: php

    with(\Mockery::notAnyOf(1, 2))

Matches any argument which is not equal or identical to any of the given
parameters.

There is no Hamcrest version of this functionality.

.. code-block:: php

    with(\Mockery::subset(array(0 => 'foo')))

Matches any argument which is any array containing the given array subset.
This enforces both key naming and values, i.e. both the key and value of each
actual element is compared.

There is no Hamcrest version of this functionality, though Hamcrest can check
a single entry using ``hasEntry()`` or ``hasKeyValuePair()``.

.. code-block:: php

    with(\Mockery::contains(value1, value2))

Matches any argument which is an array containing the listed values. The
naming of keys is ignored.

.. code-block:: php

    with(\Mockery::hasKey(key));

Matches any argument which is an array containing the given key name.

.. code-block:: php

    with(\Mockery::hasValue(value));

Matches any argument which is an array containing the given value.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Demeter Chains (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/demeter_chains.rst`)

.. index::
    single: Mocking; Demeter Chains

Mocking Demeter Chains And Fluent Interfaces
============================================

Both of these terms refer to the growing practice of invoking statements
similar to:

.. code-block:: php

    $object->foo()->bar()->zebra()->alpha()->selfDestruct();

The long chain of method calls isn't necessarily a bad thing, assuming they
each link back to a local object the calling class knows. Just as a fun
example, Mockery's long chains (after the first ``shouldReceive()`` method)
all call to the same instance of ``\Mockery\Expectation``. However, sometimes
this is not the case and the chain is constantly crossing object boundaries.

In either case, mocking such a chain can be a horrible task. To make it easier
Mockery support demeter chain mocking. Essentially, we shortcut through the
chain and return a defined value from the final call. For example, let's
assume ``selfDestruct()`` returns the string "Ten!" to $object (an instance of
``CaptainsConsole``). Here's how we could mock it.

.. code-block:: php

    $mock = \Mockery::mock('CaptainsConsole');
    $mock->shouldReceive('foo->bar->zebra->alpha->selfDestruct')->andReturn('Ten!');

The above expectation can follow any previously seen format or expectation,
except that the method name is simply the string of all expected chain calls
separated by ``->``. Mockery will automatically setup the chain of expected
calls with its final return values, regardless of whatever intermediary object
might be used in the real implementation.

Arguments to all members of the chain (except the final call) are ignored in
this process.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Expectations (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/expectations.rst`)

.. index::
    single: Expectations

Expectation Declarations
========================

Once you have created a mock object, you'll often want to start defining how
exactly it should behave (and how it should be called). This is where the
Mockery expectation declarations take over.

.. code-block:: php

    shouldReceive(method_name)

Declares that the mock expects a call to the given method name. This is the
starting expectation upon which all other expectations and constraints are
appended.

.. code-block:: php

    shouldReceive(method1, method2, ...)

Declares a number of expected method calls, all of which will adopt any
chained expectations or constraints.

.. code-block:: php

    shouldReceive(array('method1'=>1, 'method2'=>2, ...))

Declares a number of expected calls but also their return values. All will
adopt any additional chained expectations or constraints.

.. code-block:: php

    shouldReceive(closure)

Creates a mock object (only from a partial mock) which is used to create a
mock object recorder. The recorder is a simple proxy to the original object
passed in for mocking. This is passed to the closure, which may run it through
a set of operations which are recorded as expectations on the partial mock. A
simple use case is automatically recording expectations based on an existing
usage (e.g. during refactoring). See examples in a later section.

.. code-block:: php

    shouldNotReceive(method_name)

Declares that the mock should not expect a call to the given method name. This
method is a convenience method for calling ``shouldReceive()->never()``.

.. code-block:: php

    with(arg1, arg2, ...) / withArgs(array(arg1, arg2, ...))

Adds a constraint that this expectation only applies to method calls which
match the expected argument list. You can add a lot more flexibility to
argument matching using the built in matcher classes (see later). For example,
``\Mockery::any()`` matches any argument passed to that position in the
``with()`` parameter list. Mockery also allows Hamcrest library matchers - for
example, the Hamcrest function ``anything()`` is equivalent to
``\Mockery::any()``.

It's important to note that this means all expectations attached only apply to
the given method when it is called with these exact arguments. This allows for
setting up differing expectations based on the arguments provided to expected
calls.

.. code-block:: php

    withAnyArgs()

Declares that this expectation matches a method call regardless of what
arguments are passed. This is set by default unless otherwise specified.

.. code-block:: php

    withNoArgs()

Declares this expectation matches method calls with zero arguments.

.. code-block:: php

    andReturn(value)

Sets a value to be returned from the expected method call.

.. code-block:: php

    andReturn(value1, value2, ...)

Sets up a sequence of return values or closures. For example, the first call
will return value1 and the second value2. Note that all subsequent calls to a
mocked method will always return the final value (or the only value) given to
this declaration.

.. code-block:: php

    andReturnNull() / andReturn([NULL])

Both of the above options are primarily for communication to test readers.
They mark the mock object method call as returning ``null`` or nothing.

.. code-block:: php

    andReturnValues(array)

Alternative syntax for ``andReturn()`` that accepts a simple array instead of
a list of parameters. The order of return is determined by the numerical
index of the given array with the last array member being return on all calls
once previous return values are exhausted.

.. code-block:: php

    andReturnUsing(closure, ...)

Sets a closure (anonymous function) to be called with the arguments passed to
the method. The return value from the closure is then returned. Useful for
some dynamic processing of arguments into related concrete results. Closures
can queued by passing them as extra parameters as for ``andReturn()``.

.. note::

    You cannot currently mix ``andReturnUsing()`` with ``andReturn()``.

.. code-block:: php

    andThrow(Exception)

Declares that this method will throw the given ``Exception`` object when
called.

.. code-block:: php

    andThrow(exception_name, message)

Rather than an object, you can pass in the ``Exception`` class and message to
use when throwing an ``Exception`` from the mocked method.

.. code-block:: php

    andSet(name, value1) / set(name, value1)

Used with an expectation so that when a matching method is called, one can
also cause a mock object's public property to be set to a specified value.

.. code-block:: php

    passthru()

Tells the expectation to bypass a return queue and instead call the real
method of the class that was mocked and return the result. Basically, it
allows expectation matching and call count validation to be applied against
real methods while still calling the real class method with the expected
arguments.

.. code-block:: php

    zeroOrMoreTimes()

Declares that the expected method may be called zero or more times. This is
the default for all methods unless otherwise set.

.. code-block:: php

    once()

Declares that the expected method may only be called once. Like all other call
count constraints, it will throw a ``\Mockery\CountValidator\Exception`` if
breached and can be modified by the ``atLeast()`` and ``atMost()``
constraints.

.. code-block:: php

    twice()

Declares that the expected method may only be called twice.

.. code-block:: php

    times(n)

Declares that the expected method may only be called n times.

.. code-block:: php

    never()

Declares that the expected method may never be called. Ever!

.. code-block:: php

    atLeast()

Adds a minimum modifier to the next call count expectation. Thus
``atLeast()->times(3)`` means the call must be called at least three times
(given matching method args) but never less than three times.

.. code-block:: php

    atMost()

Adds a maximum modifier to the next call count expectation. Thus
``atMost()->times(3)`` means the call must be called no more than three times.
This also means no calls are acceptable.

.. code-block:: php

    between(min, max)

Sets an expected range of call counts. This is actually identical to using
``atLeast()->times(min)->atMost()->times(max)`` but is provided as a
shorthand.  It may be followed by a ``times()`` call with no parameter to
preserve the APIs natural language readability.

.. code-block:: php

    ordered()

Declares that this method is expected to be called in a specific order in
relation to similarly marked methods. The order is dictated by the order in
which this modifier is actually used when setting up mocks.

.. code-block:: php

    ordered(group)

Declares the method as belonging to an order group (which can be named or
numbered). Methods within a group can be called in any order, but the ordered
calls from outside the group are ordered in relation to the group, i.e. you
can set up so that method1 is called before group1 which is in turn called
before method 2.

.. code-block:: php

    globally()

When called prior to ``ordered()`` or ``ordered(group)``, it declares this
ordering to apply across all mock objects (not just the current mock). This
allows for dictating order expectations across multiple mocks.

.. code-block:: php

    byDefault()

Marks an expectation as a default. Default expectations are applied unless a
non-default expectation is created. These later expectations immediately
replace the previously defined default. This is useful so you can setup
default mocks in your unit test ``setup()`` and later tweak them in specific
tests as needed.

.. code-block:: php

    getMock()

Returns the current mock object from an expectation chain. Useful where you
prefer to keep mock setups as a single statement, e.g.

.. code-block:: php

    $mock = \Mockery::mock('foo')->shouldReceive('foo')->andReturn(1)->getMock();

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Final Methods Classes (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/final_methods_classes.rst`)

.. index::
    single: Mocking; Final Classes/Methods

Dealing with Final Classes/Methods
==================================

One of the primary restrictions of mock objects in PHP, is that mocking
classes or methods marked final is hard. The final keyword prevents methods so
marked from being replaced in subclasses (subclassing is how mock objects can
inherit the type of the class or object being mocked.

The simplest solution is not to mark classes or methods as final!

However, in a compromise between mocking functionality and type safety,
Mockery does allow creating "proxy mocks" from classes marked final, or from
classes with methods marked final. This offers all the usual mock object
goodness but the resulting mock will not inherit the class type of the object
being mocked, i.e.  it will not pass any instanceof comparison.

You can create a proxy mock by passing the instantiated object you wish to
mock into ``\Mockery::mock()``, i.e. Mockery will then generate a Proxy to the
real object and selectively intercept method calls for the purposes of setting
and meeting expectations.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Index (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/index.rst`)

Reference
=========

.. toctree::
    :hidden:

    startup_methods
    expectations
    argument_validation
    partial_mocks
    public_properties
    public_static_properties
    pass_by_reference_behaviours
    demeter_chains
    object_recording
    final_methods_classes
    magic_methods
    mockery/index

.. include:: map.rst.inc

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Instance Mocking (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/instance_mocking.rst`)

.. index::
    single: Mocking; Instance

Instance Mocking
================

Instance mocking means that a statement like:

.. code-block:: php

    $obj = new \MyNamespace\Foo;

...will actually generate a mock object. This is done by replacing the real
class with an instance mock (similar to an alias mock), as with mocking public
methods. The alias will import its expectations from the original mock of
that type (note that the original is never verified and should be ignored
after its expectations are setup). This lets you intercept instantiation where
you can't simply inject a replacement object.

As before, this does not prevent a require statement from including the real
class and triggering a fatal PHP error. It's intended for use where
autoloading is the primary class loading mechanism.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Magic Methods (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/magic_methods.rst`)

.. index::
    single: Mocking; Magic Methods

PHP Magic Methods
=================

PHP magic methods which are prefixed with a double underscore, e.g.
``__set()``, pose a particular problem in mocking and unit testing in general.
It is strongly recommended that unit tests and mock objects do not directly
refer to magic methods. Instead, refer only to the virtual methods and
properties these magic methods simulate.

Following this piece of advice will ensure you are testing the real API of
classes and also ensures there is no conflict should Mockery override these
magic methods, which it will inevitably do in order to support its role in
intercepting method calls and properties.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Object Recording (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/object_recording.rst`)

.. index::
    single: Mocking; Object Recording

Mock Object Recording
=====================

In certain cases, you may find that you are testing against an already
established pattern of behaviour, perhaps during refactoring. Rather then hand
crafting mock object expectations for this behaviour, you could instead use
the existing source code to record the interactions a real object undergoes
onto a mock object as expectations - expectations you can then verify against
an alternative or refactored version of the source code.

To record expectations, you need a concrete instance of the class to be
mocked.  This can then be used to create a partial mock to which is given the
necessary code to execute the object interactions to be recorded. A simple
example is outline below (we use a closure for passing instructions to the
mock).

Here we have a very simple setup, a class (``SubjectUser``) which uses another
class (``Subject``) to retrieve some value. We want to record as expectations
on our mock (which will replace ``Subject`` later) all the calls and return
values of a Subject instance when interacting with ``SubjectUser``.

.. code-block:: php

    class Subject
    {

        public function execute() {
            return 'executed!';
        }

    }

    class SubjectUser
    {

        public function use(Subject $subject) {
            return $subject->execute();
        }

    }

Here's the test case showing the recording:

.. code-block:: php

    class SubjectUserTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            \Mockery::close();
        }

        public function testSomething()
        {
            $mock = \Mockery::mock(new Subject);
            $mock->shouldExpect(function ($subject) {
                $user = new SubjectUser;
                $user->use($subject);
            });

            /**
            * Assume we have a replacement SubjectUser called NewSubjectUser.
            * We want to verify it behaves identically to SubjectUser, i.e.
            * it uses Subject in the exact same way
            */
            $newSubject = new NewSubjectUser;
            $newSubject->use($mock);
        }

    }

After the ``\Mockery::close()`` call in ``tearDown()`` validates the mock
object, we should have zero exceptions if ``NewSubjectUser`` acted on
`Subject` in a similar way to ``SubjectUser``. By default the order of calls
are not enforced, and loose argument matching is enabled, i.e. arguments may
be equal (``==``) but not necessarily identical (``===``).

If you wished to be more strict, for example ensuring the order of calls and
the final call counts were identical, or ensuring arguments are completely
identical, you can invoke the recorder's strict mode from the closure block,
e.g.

.. code-block:: php

    $mock->shouldExpect(function ($subject) {
        $subject->shouldBeStrict();
        $user = new SubjectUser;
        $user->use($subject);
    });

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Partial Mocks (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/partial_mocks.rst`)

.. index::
    single: Mocking; Partial Mocks

Creating Partial Mocks
======================

Partial mocks are useful when you only need to mock several methods of an
object leaving the remainder free to respond to calls normally (i.e.  as
implemented). Mockery implements three distinct strategies for creating
partials. Each has specific advantages and disadvantages so which strategy you
use will depend on your own preferences and the source code in need of
mocking.

#. Traditional Partial Mock
#. Passive Partial Mock
#. Proxied Partial Mock

Traditional Partial Mock
------------------------

A traditional partial mock, defines ahead of time which methods of a class are
to be mocked and which are to be left unmocked (i.e. callable as normal).  The
syntax for creating traditional mocks is:

.. code-block:: php

    $mock = \Mockery::mock('MyClass[foo,bar]');

In the above example, the ``foo()`` and ``bar()`` methods of MyClass will be
mocked but no other MyClass methods are touched. You will need to define
expectations for the ``foo()`` and ``bar()`` methods to dictate their mocked
behaviour.

Don't forget that you can pass in constructor arguments since unmocked methods
may rely on those!

.. code-block:: php

    $mock = \Mockery::mock('MyNamespace\MyClass[foo]', array($arg1, $arg2));

Passive Partial Mock
--------------------

A passive partial mock is more of a default state of being.

.. code-block:: php

    $mock = \Mockery::mock('MyClass')->makePartial();

In a passive partial, we assume that all methods will simply defer to the
parent class (``MyClass``) original methods unless a method call matches a
known expectation. If you have no matching expectation for a specific method
call, that call is deferred to the class being mocked. Since the division
between mocked and unmocked calls depends entirely on the expectations you
define, there is no need to define which methods to mock in advance. The
``makePartial()`` method is identical to the original ``shouldDeferMissing()``
method which first introduced this Partial Mock type.

Proxied Partial Mock
--------------------

A proxied partial mock is a partial of last resort. You may encounter a class
which is simply not capable of being mocked because it has been marked as
final. Similarly, you may find a class with methods marked as final. In such a
scenario, we cannot simply extend the class and override methods to mock - we
need to get creative.

.. code-block:: php

    $mock = \Mockery::mock(new MyClass);

Yes, the new mock is a Proxy. It intercepts calls and reroutes them to the
proxied object (which you construct and pass in) for methods which are not
subject to any expectations. Indirectly, this allows you to mock methods
marked final since the Proxy is not subject to those limitations. The tradeoff
should be obvious - a proxied partial will fail any typehint checks for the
class being mocked since it cannot extend that class.

Special Internal Cases
----------------------

All mock objects, with the exception of Proxied Partials, allow you to make
any expectation call the underlying real class method using the ``passthru()``
expectation call. This will return values from the real call and bypass any
mocked return queue (which can simply be omitted obviously).

There is a fourth kind of partial mock reserved for internal use. This is
automatically generated when you attempt to mock a class containing methods
marked final. Since we cannot override such methods, they are simply left
unmocked. Typically, you don't need to worry about this but if you really
really must mock a final method, the only possible means is through a Proxied
Partial Mock. SplFileInfo, for example, is a common class subject to this form
of automatic internal partial since it contains public final methods used
internally.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Pass By Reference Behaviours (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/pass_by_reference_behaviours.rst`)

.. index::
    single: Pass-By-Reference Method Parameter Behaviour

Preserving Pass-By-Reference Method Parameter Behaviour
=======================================================

PHP Class method may accept parameters by reference. In this case, changes
made to the parameter (a reference to the original variable passed to the
method) are reflected in the original variable. A simple example:

.. code-block:: php

    class Foo
    {

        public function bar(&$a)
        {
            $a++;
        }

    }

    $baz = 1;
    $foo = new Foo;
    $foo->bar($baz);

    echo $baz; // will echo the integer 2

In the example above, the variable $baz is passed by reference to
``Foo::bar()`` (notice the ``&`` symbol in front of the parameter?).  Any
change ``bar()`` makes to the parameter reference is reflected in the original
variable, ``$baz``.

Mockery 0.7+ handles references correctly for all methods where it can analyse
the parameter (using ``Reflection``) to see if it is passed by reference. To
mock how a reference is manipulated by the class method, you can use a closure
argument matcher to manipulate it, i.e. ``\Mockery::on()`` - see the
":doc:`argument_validation`" chapter.

There is an exception for internal PHP classes where Mockery cannot analyse
method parameters using ``Reflection`` (a limitation in PHP). To work around
this, you can explicitly declare method parameters for an internal class using
``/Mockery/Configuration::setInternalClassMethodParamMap()``.

Here's an example using ``MongoCollection::insert()``. ``MongoCollection`` is
an internal class offered by the mongo extension from PECL. Its ``insert()``
method accepts an array of data as the first parameter, and an optional
options array as the second parameter. The original data array is updated
(i.e. when a ``insert()`` pass-by-reference parameter) to include a new
``_id`` field. We can mock this behaviour using a configured parameter map (to
tell Mockery to expect a pass by reference parameter) and a ``Closure``
attached to the expected method parameter to be updated.

Here's a PHPUnit unit test verifying that this pass-by-reference behaviour is
preserved:

.. code-block:: php

    public function testCanOverrideExpectedParametersOfInternalPHPClassesToPreserveRefs()
    {
        \Mockery::getConfiguration()->setInternalClassMethodParamMap(
            'MongoCollection',
            'insert',
            array('&$data', '$options = array()')
        );
        $m = \Mockery::mock('MongoCollection');
        $m->shouldReceive('insert')->with(
            \Mockery::on(function(&$data) {
                if (!is_array($data)) return false;
                $data['_id'] = 123;
                return true;
            }),
            \Mockery::any()
        );

        $data = array('a'=>1,'b'=>2);
        $m->insert($data);

        $this->assertTrue(isset($data['_id']));
        $this->assertEquals(123, $data['_id']);

        \Mockery::resetContainer();
    }

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Phpunit Integration (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/phpunit_integration.rst`)

.. index::
    single: PHPUnit Integration

PHPUnit Integration
===================

Mockery was designed as a simple-to-use *standalone* mock object framework, so
its need for integration with any testing framework is entirely optional.  To
integrate Mockery, you just need to define a ``tearDown()`` method for your
tests containing the following (you may use a shorter ``\Mockery`` namespace
alias):

.. code-block:: php

    public function tearDown() {
        \Mockery::close();
    }

This static call cleans up the Mockery container used by the current test, and
run any verification tasks needed for your expectations.

For some added brevity when it comes to using Mockery, you can also explicitly
use the Mockery namespace with a shorter alias. For example:

.. code-block:: php

    use \Mockery as m;

    class SimpleTest extends PHPUnit_Framework_TestCase
    {
        public function testSimpleMock() {
            $mock = m::mock('simplemock');
            $mock->shouldReceive('foo')->with(5, m::any())->once()->andReturn(10);

            $this->assertEquals(10, $mock->foo(5));
        }

        public function tearDown() {
            m::close();
        }
    }

Mockery ships with an autoloader so you don't need to litter your tests with
``require_once()`` calls. To use it, ensure Mockery is on your
``include_path`` and add the following to your test suite's ``Bootstrap.php``
or ``TestHelper.php`` file:

.. code-block:: php

    require_once 'Mockery/Loader.php';
    require_once 'Hamcrest/Hamcrest.php';

    $loader = new \Mockery\Loader;
    $loader->register();

If you are using Composer, you can simplify this to just including the
Composer generated autoloader file:

.. code-block:: php

    require __DIR__ . '/../vendor/autoload.php'; // assuming vendor is one directory up

.. caution::

    Prior to Hamcrest 1.0.0, the ``Hamcrest.php`` file name had a small "h"
    (i.e. ``hamcrest.php``).  If upgrading Hamcrest to 1.0.0 remember to check
    the file name is updated for all your projects.)

To integrate Mockery into PHPUnit and avoid having to call the close method
and have Mockery remove itself from code coverage reports, use this in you
suite:

.. code-block:: php

    // Create Suite
    $suite = new PHPUnit_Framework_TestSuite();

    // Create a result listener or add it
    $result = new PHPUnit_Framework_TestResult();
    $result->addListener(new \Mockery\Adapter\Phpunit\TestListener());

    // Run the tests.
    $suite->run($result);

If you are using PHPUnit's XML configuration approach, you can include the
following to load the ``TestListener``:

.. code-block:: xml

    <listeners>
        <listener class="\Mockery\Adapter\Phpunit\TestListener"></listener>
    </listeners>

Make sure Composer's or Mockery's autoloader is present in the bootstrap file
or you will need to also define a "file" attribute pointing to the file of the
above ``TestListener`` class.

.. caution::

    PHPUnit provides a functionality that allows
    `tests to run in a separated process <http://phpunit.de/manual/4.0/en/appendixes.annotations.html#appendixes.annotations.runTestsInSeparateProcesses>`_,
    to ensure better isolation. Mockery verifies the mocks expectations using the
    ``Mockery::close()`` method, and provides a PHPUnit listener, that automatically
    calls this method for you after every test.

    However, this listener is not called in the right process when using PHPUnit's process
    isolation, resulting in expectations that might not be respected, but without raising
    any ``Mockery\Exception``. To avoid this, you cannot rely on the supplied Mockery PHPUnit
    ``TestListener``, and you need to explicitly calls ``Mockery::close``. The easiest solution
    to include this call in the ``tearDown()`` method, as explained previously.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Public Properties (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/public_properties.rst`)

.. index::
    single: Mocking; Public Properties

Mocking Public Properties
=========================

Mockery allows you to mock properties in several ways. The simplest is that
you can simply set a public property and value on any mock object. The second
is that you can use the expectation methods ``set()`` and ``andSet()`` to set
property values if that expectation is ever met.

You should note that, in general, Mockery does not support mocking any magic
methods since these are generally not considered a public API (and besides
they are a PITA to differentiate when you badly need them for mocking!). So
please mock virtual properties (those relying on ``__get()`` and ``__set()``)
as if they were actually declared on the class.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Public Static Properties (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/public_static_properties.rst`)

.. index::
    single: Mocking; Public Static Methods

Mocking Public Static Methods
=============================

Static methods are not called on real objects, so normal mock objects can't
mock them. Mockery supports class aliased mocks, mocks representing a class
name which would normally be loaded (via autoloading or a require statement)
in the system under test. These aliases block that loading (unless via a
require statement - so please use autoloading!) and allow Mockery to intercept
static method calls and add expectations for them.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Quick Examples (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/quick_examples.rst`)

.. index::
    single: Reference; Examples

Quick Examples
==============

Create a mock object to return a sequence of values from a set of method
calls.

.. code-block:: php

    class SimpleTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            \Mockery::close();
        }

        public function testSimpleMock()
        {
            $mock = \Mockery::mock(array('pi' => 3.1416, 'e' => 2.71));
            $this->assertEquals(3.1416, $mock->pi());
            $this->assertEquals(2.71, $mock->e());
        }

    }

Create a mock object which returns a self-chaining Undefined object for a
method call.

.. code-block:: php

    use \Mockery as m;

    class UndefinedTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            m::close();
        }

        public function testUndefinedValues()
        {
            $mock = m::mock('mymock');
            $mock->shouldReceive('divideBy')->with(0)->andReturnUndefined();
            $this->assertTrue($mock->divideBy(0) instanceof \Mockery\Undefined);
        }

    }

Creates a mock object which multiple query calls and a single update call.

.. code-block:: php

    use \Mockery as m;

    class DbTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            m::close();
        }

        public function testDbAdapter()
        {
            $mock = m::mock('db');
            $mock->shouldReceive('query')->andReturn(1, 2, 3);
            $mock->shouldReceive('update')->with(5)->andReturn(NULL)->once();

            // ... test code here using the mock
        }

    }

Expect all queries to be executed before any updates.

.. code-block:: php

    use \Mockery as m;

    class DbTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            m::close();
        }

        public function testQueryAndUpdateOrder()
        {
            $mock = m::mock('db');
            $mock->shouldReceive('query')->andReturn(1, 2, 3)->ordered();
            $mock->shouldReceive('update')->andReturn(NULL)->once()->ordered();

            // ... test code here using the mock
        }

    }

Create a mock object where all queries occur after startup, but before finish,
and where queries are expected with several different params.

.. code-block:: php

    use \Mockery as m;

    class DbTest extends PHPUnit_Framework_TestCase
    {

        public function tearDown()
        {
            m::close();
        }

        public function testOrderedQueries()
        {
            $db = m::mock('db');
            $db->shouldReceive('startup')->once()->ordered();
            $db->shouldReceive('query')->with('CPWR')->andReturn(12.3)->once()->ordered('queries');
            $db->shouldReceive('query')->with('MSFT')->andReturn(10.0)->once()->ordered('queries');
            $db->shouldReceive('query')->with("/^....$/")->andReturn(3.3)->atLeast()->once()->ordered('queries');
            $db->shouldReceive('finish')->once()->ordered();

            // ... test code here using the mock
        }

    }

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Startup Methods (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/startup_methods.rst`)

.. index::
    single: Reference; Quick Reference

Quick Reference
===============

Mockery implements a shorthand API when creating a mock. Here's a sampling of
the possible startup methods.

.. code-block:: php

    $mock = \Mockery::mock('foo');

Creates a mock object named "foo". In this case, "foo" is a name (not
necessarily a class name) used as a simple identifier when raising exceptions.
This creates a mock object of type ``\Mockery\Mock`` and is the loosest form
of mock possible.

.. code-block:: php

    $mock = \Mockery::mock(array('foo'=>1,'bar'=>2));

Creates an mock object named unknown since we passed no name. However we did
pass an expectation array, a quick method of setting up methods to expect with
their return values.

.. code-block:: php

    $mock = \Mockery::mock('foo', array('foo'=>1,'bar'=>2));

Similar to the previous examples and all examples going forward, expectation
arrays can be passed for all mock objects as the second parameter to
``mock()``.

.. code-block:: php

    $mock = \Mockery::mock('foo', function($mock) {
        $mock->shouldReceive(method_name);
    });

In addition to expectation arrays, you can also pass in a closure which
contains reusable expectations. This can be passed as the second parameter, or
as the third parameter if partnered with an expectation array. This is one
method for creating reusable mock expectations.

.. code-block:: php

    $mock = \Mockery::mock('stdClass');

Creates a mock identical to a named mock, except the name is an actual class
name. Creates a simple mock as previous examples show, except the mock object
will inherit the class type (via inheritance), i.e. it will pass type hints or
instanceof evaluations for stdClass. Useful where a mock object must be of a
specific type.

.. code-block:: php

    $mock = \Mockery::mock('FooInterface');

You can create mock objects based on any concrete class, abstract class or
even an interface. Again, the primary purpose is to ensure the mock object
inherits a specific type for type hinting. There is an exception in that
classes marked final, or with methods marked final, cannot be mocked fully. In
these cases a partial mock (explained later) must be utilised.

.. code-block:: php

    $mock = \Mockery::mock('alias:MyNamespace\MyClass');

Prefixing the valid name of a class (which is NOT currently loaded) with
"alias:" will generate an "alias mock". Alias mocks create a class alias with
the given classname to stdClass and are generally used to enable the mocking
of public static methods. Expectations set on the new mock object which refer
to static methods will be used by all static calls to this class.

.. code-block:: php

    $mock = \Mockery::mock('overload:MyNamespace\MyClass');

Prefixing the valid name of a class (which is NOT currently loaded) with
"overload:" will generate an alias mock (as with "alias:") except that created
new instances of that class will import any expectations set on the origin
mock (``$mock``). The origin mock is never verified since it's used an
expectation store for new instances. For this purpose we use the term
"instance mock" to differentiate it from the simpler "alias mock".

.. note::

    Using alias/instance mocks across more than one test will generate a fatal
    error since you can't have two classes of the same name. To avoid this,
    run each test of this kind in a separate PHP process (which is supported
    out of the box by both PHPUnit and PHPT).

.. code-block:: php

    $mock = \Mockery::mock('stdClass, MyInterface1, MyInterface2');

The first argument can also accept a list of interfaces that the mock object
must implement, optionally including no more than one existing class to be
based on. The class name doesn't need to be the first member of the list but
it's a friendly convention to use for readability. All subsequent arguments
remain unchanged from previous examples.

If the given class does not exist, you must define and include it beforehand
or a ``\Mockery\Exception`` will be thrown.

.. code-block:: php

    $mock = \Mockery::mock('MyNamespace\MyClass[foo,bar]');

The syntax above tells Mockery to partially mock the ``MyNamespace\MyClass``
class, by mocking the ``foo()`` and ``bar()`` methods only. Any other method
will be not be overridden by Mockery. This traditional form of "partial mock"
can be applied to any class or abstract class (e.g. mocking abstract methods
where a concrete implementation does not exist yet). If you attempt to partial
mock a method marked final, it will actually be ignored in that instance
leaving the final method untouched. This is necessary since mocking of final
methods is, by definition in PHP, impossible.

Please refer to ":doc:`partial_mocks`" for a detailed explanation on how to
create Partial Mocks in Mockery.

.. code-block:: php

    $mock = \Mockery::mock("MyNamespace\MyClass[foo]", array($arg1, $arg2));

If Mockery encounters an indexed array as the second or third argument, it
will assume they are constructor parameters and pass them when constructing
the mock object. The syntax above will create a new partial mock, particularly
useful if method ``bar`` calls method ``foo`` internally with
``$this->foo()``.

.. code-block:: php

    $mock = \Mockery::mock(new Foo);

Passing any real object into Mockery will create a Proxied Partial Mock. This
can be useful if real partials are impossible, e.g. a final class or class
where you absolutely must override a method marked final. Since you can
already create a concrete object, so all we need to do is selectively override
a subset of existing methods (or add non-existing methods!) for our
expectations.

A little revision: All mock methods accept the class, object or alias name to
be mocked as the first parameter. The second parameter can be an expectation
array of methods and their return values, or an expectation closure (which can
be the third param if used in conjunction with an expectation array).

.. code-block:: php

    \Mockery::self()

At times, you will discover that expectations on a mock include methods which
need to return the same mock object (e.g. a common case when designing a
Domain Specific Language (DSL) such as the one Mockery itself uses!). To
facilitate this, calling ``\Mockery::self()`` will always return the last Mock
Object created by calling ``\Mockery::mock()``. For example:

.. code-block:: php

    $mock = \Mockery::mock('BazIterator')
        ->shouldReceive('next')
        ->andReturn(\Mockery::self())
        ->mock();

The above class being mocked, as the ``next()`` method suggests, is an
iterator. In many cases, you can replace all the iterated elements (since they
are the same type many times) with just the one mock object which is
programmed to act as discrete iterated elements.

.. code-block:: php

    $mock = \Mockery::namedMock('MyClassName', 'DateTime');

The ``namedMock`` method will generate a class called by the first argument,
so in this example ``MyClassName``. The rest of the arguments are treat in the
same way as the ``mock`` method, so again, this example would create a class
called ``MyClassName`` that extends ``DateTime``.

Named mocks are quite an edge case, but they can be useful when code depends
on the ``__CLASS__`` magic constant, or when you need two derivatives of an
abstract type, that are actually different classes.

.. caution::

    You can only create a named mock once, any subsequent calls to
    ``namedMock``, with different arguments are likely to cause exceptions.

Behaviour Modifiers
-------------------

When creating a mock object, you may wish to use some commonly preferred
behaviours that are not the default in Mockery.

.. code-block:: php

    \Mockery::mock('MyClass')->shouldIgnoreMissing()

The use of the ``shouldIgnoreMissing()`` behaviour modifier will label this
mock object as a Passive Mock. In such a mock object, calls to methods which
are not covered by expectations will return ``null`` instead of the usual
complaining about there being no expectation matching the call.

You can optionally prefer to return an object of type ``\Mockery\Undefined``
(i.e.  a ``null`` object) (which was the 0.7.2 behaviour) by using an
additional modifier:

.. code-block:: php

    \Mockery::mock('MyClass')->shouldIgnoreMissing()->asUndefined()

The returned object is nothing more than a placeholder so if, by some act of
fate, it's erroneously used somewhere it shouldn't it will likely not pass a
logic check.

.. code-block:: php

    \Mockery::mock('MyClass')->makePartial()

also

.. code-block:: php

    \Mockery::mock('MyClass')->shouldDeferMissing()

Known as a Passive Partial Mock (not to be confused with real partial mock
objects discussed later), this form of mock object will defer all methods not
subject to an expectation to the parent class of the mock, i.e. ``MyClass``.
Whereas the previous ``shouldIgnoreMissing()`` returned ``null``, this
behaviour simply calls the parent's matching method.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Mockery Configuration (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/mockery/configuration.rst`)

.. index::
    single: Mockery; Configuration

Mockery Global Configuration
============================

To allow for a degree of fine-tuning, Mockery utilises a singleton
configuration object to store a small subset of core behaviours. The three
currently present include:

* Option to allow/disallow the mocking of methods which do not actually exist
* Option to allow/disallow the existence of expectations which are never
  fulfilled (i.e. unused)
* Setter/Getter for added a parameter map for internal PHP class methods
  (``Reflection`` cannot detect these automatically)

By default, the first two behaviours are enabled. Of course, there are
situations where this can lead to unintended consequences. The mocking of
non-existent methods may allow mocks based on real classes/objects to fall out
of sync with the actual implementations, especially when some degree of
integration testing (testing of object wiring) is not being performed.
Allowing unfulfilled expectations means unnecessary mock expectations go
unnoticed, cluttering up test code, and potentially confusing test readers.

You may allow or disallow these behaviours (whether for whole test suites or
just select tests) by using one or both of the following two calls:

.. code-block:: php

    \Mockery::getConfiguration()->allowMockingNonExistentMethods(bool);
    \Mockery::getConfiguration()->allowMockingMethodsUnnecessarily(bool);

Passing a true allows the behaviour, false disallows it. Both take effect
immediately until switched back. In both cases, if either behaviour is
detected when not allowed, it will result in an Exception being thrown at that
point. Note that disallowing these behaviours should be carefully considered
since they necessarily remove at least some of Mockery's flexibility.

The other two methods are:

.. code-block:: php

    \Mockery::getConfiguration()->setInternalClassMethodParamMap($class, $method, array $paramMap)
    \Mockery::getConfiguration()->getInternalClassMethodParamMap($class, $method)

These are used to define parameters (i.e. the signature string of each) for the
methods of internal PHP classes (e.g. SPL, or PECL extension classes like
ext/mongo's MongoCollection. Reflection cannot analyse the parameters of internal
classes. Most of the time, you never need to do this. It's mainly needed where an
internal class method uses pass-by-reference for a parameter - you MUST in such
cases ensure the parameter signature includes the ``&`` symbol correctly as Mockery
won't correctly add it automatically for internal classes.

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Mockery Exceptions (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/mockery/exceptions.rst`)

.. index::
    single: Mockery; Exceptions

Mockery Exceptions
==================

Mockery throws three types of exceptions when it cannot verify a mock object.

#. ``\Mockery\Exception\InvalidCountException``
#. ``\Mockery\Exception\InvalidOrderException``
#. ``\Mockery\Exception\NoMatchingExpectationException``

You can capture any of these exceptions in a try...catch block to query them
for specific information which is also passed along in the exception message
but is provided separately from getters should they be useful when logging or
reformatting output.

\Mockery\Exception\InvalidCountException
----------------------------------------

The exception class is used when a method is called too many (or too few)
times and offers the following methods:

* ``getMock()`` - return actual mock object
* ``getMockName()`` - return the name of the mock object
* ``getMethodName()`` - return the name of the method the failing expectation
  is attached to
* ``getExpectedCount()`` - return expected calls
* ``getExpectedCountComparative()`` - returns a string, e.g. ``<=`` used to
  compare to actual count
* ``getActualCount()`` - return actual calls made with given argument
  constraints

\Mockery\Exception\InvalidOrderException
----------------------------------------

The exception class is used when a method is called outside the expected order
set using the ``ordered()`` and ``globally()`` expectation modifiers. It
offers the following methods:

* ``getMock()`` - return actual mock object
* ``getMockName()`` - return the name of the mock object
* ``getMethodName()`` - return the name of the method the failing expectation
  is attached to
* ``getExpectedOrder()`` - returns an integer represented the expected index
  for which this call was expected
* ``getActualOrder()`` - return the actual index at which this method call
  occurred.

\Mockery\Exception\NoMatchingExpectationException
-------------------------------------------------

The exception class is used when a method call does not match any known
expectation.  All expectations are uniquely identified in a mock object by the
method name and the list of expected arguments. You can disable this exception
and opt for returning NULL from all unexpected method calls by using the
earlier mentioned shouldIgnoreMissing() behaviour modifier. This exception
class offers the following methods:

* ``getMock()`` - return actual mock object
* ``getMockName()`` - return the name of the mock object
* ``getMethodName()`` - return the name of the method the failing expectation
  is attached to
* ``getActualArguments()`` - return actual arguments used to search for a
  matching expectation

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Mockery Gotchas (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/mockery/gotchas.rst`)

.. index::
    single: Mockery; Gotchas

Gotchas!
========

Mocking objects in PHP has its limitations and gotchas. Some functionality
can't be mocked or can't be mocked YET! If you locate such a circumstance,
please please (pretty please with sugar on top) create a new issue on GitHub
so it can be documented and resolved where possible. Here is a list to note:

1. Classes containing public ``__wakeup()`` methods can be mocked but the
   mocked ``__wakeup()`` method will perform no actions and cannot have
   expectations set for it. This is necessary since Mockery must serialize and
   unserialize objects to avoid some ``__construct()`` insanity and attempting
   to mock a ``__wakeup()`` method as normal leads to a
   ``BadMethodCallException`` been thrown.

2. Classes using non-real methods, i.e. where a method call triggers a
   ``__call()`` method, will throw an exception that the non-real method does
   not exist unless you first define at least one expectation (a simple
   ``shouldReceive()`` call would suffice). This is necessary since there is
   no other way for Mockery to be aware of the method name.

3. Mockery has two scenarios where real classes are replaced: Instance mocks
   and alias mocks. Both will generate PHP fatal errors if the real class is
   loaded, usually via a require or include statement. Only use these two mock
   types where autoloading is in place and where classes are not explicitly
   loaded on a per-file basis using ``require()``, ``require_once()``, etc.

4. Internal PHP classes are not entirely capable of being fully analysed using
   ``Reflection``. For example, ``Reflection`` cannot reveal details of
   expected parameters to the methods of such internal classes. As a result,
   there will be problems where a method parameter is defined to accept a
   value by reference (Mockery cannot detect this condition and will assume a
   pass by value on scalars and arrays). If references as internal class
   method parameters are needed, you should use the
   ``\Mockery\Configuration::setInternalClassMethodParamMap()`` method.

The gotchas noted above are largely down to PHP's architecture and are assumed
to be unavoidable. But - if you figure out a solution (or a better one than
what may exist), let us know!

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Mockery Index (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/mockery/index.rst`)

Mockery
=======

.. toctree::
    :maxdepth: 2

    configuration
    exceptions
    reserved_method_names
    gotchas

---

### Samples Development Frameworks Laravel Vendor Mockery Mockery Docs Reference Mockery Reserved Method Names (`samples/development-frameworks/laravel/vendor/mockery/mockery/docs/reference/mockery/reserved_method_names.rst`)

.. index::
    single: Reserved Method Names

Reserved Method Names
=====================

As you may have noticed, Mockery uses a number of methods called directly on
all mock objects, for example ``shouldReceive()``. Such methods are necessary
in order to setup expectations on the given mock, and so they cannot be
implemented on the classes or objects being mocked without creating a method
name collision (reported as a PHP fatal error). The methods reserved by
Mockery are:

* ``shouldReceive()``
* ``shouldBeStrict()``

In addition, all mocks utilise a set of added methods and protected properties
which cannot exist on the class or object being mocked. These are far less
likely to cause collisions. All properties are prefixed with ``_mockery`` and
all method names with ``mockery_``.

---

--- METRICS ---
- Files Extracted: 97
- Estimated Token Budget: ~83719 tokens
- Canonical Reference: https://codewiki.google/github.com/microsoft/sql-server-samples