mirror/processwire
1
0
Fork 0
mirror of https://github.com/processwire/processwire.git synced 2025-08-14 02:34:24 +02:00
Code Issues Releases Wiki Activity

Additional documentation updates and bump version to 3.0.42

Browse Source
This commit is contained in:
Ryan Cramer
2016-11-25 14:58:02 -05:00
parent 942cac2707
commit 35df716082
10 changed files with 254 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
wire/core/Field.php
View File

@@ -7,6 +7,8 @@
* and is managed by the 'Fields' class. * and is managed by the 'Fields' class.
* *
* #pw-summary Field represents a custom field that is used on a Page. * #pw-summary Field represents a custom field that is used on a Page.
* #pw-var $field
* #pw-instantiate $field = $fields->get('field_name');
* #pw-body Field objects are managed by the `$fields` API variable. * #pw-body Field objects are managed by the `$fields` API variable.
* #pw-use-constants * #pw-use-constants
* *
@@ -31,10 +33,10 @@
* @property int|null $paginationLimit Used by paginated WireArray values to indicate limit to use during load. #pw-internal * @property int|null $paginationLimit Used by paginated WireArray values to indicate limit to use during load. #pw-internal
* *
* Common Inputfield properties that Field objects store: * Common Inputfield properties that Field objects store:
* @property int|bool|null $required * @property int|bool|null $required Whether or not this field is required during input #pw-group-properties
* @property string|null $requiredIf * @property string|null $requiredIf A selector-style string that defines the conditions under which input is required #pw-group-properties
* @property string|null $showIf * @property string|null $showIf A selector-style string that defines the conditions under which the Inputfield is shown #pw-group-properties
* @property int|null $columnWidth * @property int|null $columnWidth The Inputfield column width (percent) 10-100. #pw-group-properties
* *
* @method bool viewable(Page $page = null, User $user = null) Is the field viewable on the given $page by the given $user? #pw-group-access * @method bool viewable(Page $page = null, User $user = null) Is the field viewable on the given $page by the given $user? #pw-group-access
* @method bool editable(Page $page = null, User $user = null) Is the field editable on the given $page by the given $user? #pw-group-access * @method bool editable(Page $page = null, User $user = null) Is the field editable on the given $page by the given $user? #pw-group-access
@@ -1003,6 +1005,8 @@ class Field extends WireData implements Saveable, Exportable {
/** /**
* Set an override table name, or omit (or null) to restore default table name * Set an override table name, or omit (or null) to restore default table name
* *
* #pw-group-advanced
*
* @param null|string $table * @param null|string $table
* *
*/ */

1
wire/core/HookEvent.php
View File

@@ -9,6 +9,7 @@
* Instances of HookEvent are passed to Hook handlers when their requested method has been called. * Instances of HookEvent are passed to Hook handlers when their requested method has been called.
* *
* #pw-summary HookEvent is a type provided to hook functions with information about the event. * #pw-summary HookEvent is a type provided to hook functions with information about the event.
* #pw-var $event
* #pw-body = * #pw-body =
* ~~~~~~ * ~~~~~~
* // Example * // Example

15
wire/core/Modules.php
View File

@@ -14,6 +14,17 @@
* https://processwire.com * https://processwire.com
* *
* #pw-summary Loads and manages all modules in ProcessWire. * #pw-summary Loads and manages all modules in ProcessWire.
* #pw-body =
* The `$modules` API variable is most commonly used for getting individual modules to use their API.
* ~~~~~
* // Getting a module by name
* $m = $modules->get('MarkupPagerNav');
*
* // Getting a module by name (alternate)
* $m = $modules->MarkupPagerNav;
* ~~~~~
*
* #pw-body
* *
* @todo Move all module information methods to a ModulesInfo class * @todo Move all module information methods to a ModulesInfo class
* @todo Move all module loading methods to a ModulesLoad class * @todo Move all module loading methods to a ModulesLoad class
@@ -1156,7 +1167,7 @@ class Modules extends WireArray {
* Get the requested Module (with options) * Get the requested Module (with options)
* *
* This is the same as `$modules->get()` except that you can specify additional options to modify default behavior. * This is the same as `$modules->get()` except that you can specify additional options to modify default behavior.
* These are the options you can speicfy in the `$options` array argument: * These are the options you can specify in the `$options` array argument:
* *
* - `noPermissionCheck` (bool): Specify true to disable module permission checks (and resulting exception). * - `noPermissionCheck` (bool): Specify true to disable module permission checks (and resulting exception).
* - `noInstall` (bool): Specify true to prevent a non-installed module from installing from this request. * - `noInstall` (bool): Specify true to prevent a non-installed module from installing from this request.
@@ -4717,6 +4728,8 @@ class Modules extends WireArray {
/** /**
* Compile and return the given file for module, if allowed to do so * Compile and return the given file for module, if allowed to do so
* *
* #pw-internal
*
* @param Module|string $moduleName * @param Module|string $moduleName
* @param string $file Optionally specify the module filename as an optimization * @param string $file Optionally specify the module filename as an optimization
* @param string|null $namespace Optionally specify namespace as an optimization * @param string|null $namespace Optionally specify namespace as an optimization

2
wire/core/ProcessWire.php
View File

@@ -45,7 +45,7 @@ class ProcessWire extends Wire {
* Reversion revision number * Reversion revision number
* *
*/ */
const versionRevision = 41; const versionRevision = 42;
/** /**
* Version suffix string (when applicable) * Version suffix string (when applicable)

2
wire/core/WireCache.php
View File

@@ -376,6 +376,8 @@ class WireCache extends Wire {
if($data === false) throw new WireException("Unable to encode array data for cache: $name"); if($data === false) throw new WireException("Unable to encode array data for cache: $name");
} }
if(is_null($data)) $data = '';
$sql = $sql =
'INSERT INTO caches (`name`, `data`, `expires`) VALUES(:name, :data, :expires) ' . 'INSERT INTO caches (`name`, `data`, `expires`) VALUES(:name, :data, :expires) ' .
'ON DUPLICATE KEY UPDATE `data`=VALUES(`data`), `expires`=VALUES(`expires`)'; 'ON DUPLICATE KEY UPDATE `data`=VALUES(`data`), `expires`=VALUES(`expires`)';

114
wire/core/WireDatabaseBackup.php
View File

@@ -2,20 +2,18 @@
/** /**
* #pw-summary ProcessWire Database Backup and Restore * #pw-summary ProcessWire Database Backup and Restore
* #pw-summary-initialization It’s not typically necessary to call these initialization methods unless doing manual initialization.
* #pw-var $backup
* #pw-instantiate $backup = $database->backup();
* #pw-order-groups actions,reporting,initialization,advanced
* #pw-body = * #pw-body =
* This class intentionally does not have any external dependencies (other than PDO) * This class intentionally does not have any external dependencies (other than PDO)
* so that it can be included by outside tools for restoring/exporting, with the main * so that it can be included by outside tools for restoring/exporting, with the main
* example of that being the ProcessWire installer. * example of that being the ProcessWire installer.
* *
* The recommended way to access these backup methods is via the `$database` API variable * The recommended way to access these backup methods is via the `$database` API variable
* method `$database->backups()`, which returns a `WireDatabaseBackup` instance. * method `$database->backups()`, which returns a `WireDatabaseBackup` instance, however
* * you can also initialize the class manually if you prefer, like this:
* ### Easy Initialization (recommended)
* ~~~~~
* $backup = $database->backups();
* ~~~~~
*
* ### Manual Initialization (if you need it)
* ~~~~~ * ~~~~~
* // determine where backups will go (should NOT be web accessible) * // determine where backups will go (should NOT be web accessible)
* $backupPath = $config->paths->assets . 'backups/'; * $backupPath = $config->paths->assets . 'backups/';
@@ -32,25 +30,21 @@
* ~~~~~ * ~~~~~
* ### Backup the database * ### Backup the database
* ~~~~~ * ~~~~~
* $options = array(); // optional * $file = $backup->backup();
* $file = $backup->backup($options);
* if($file) { * if($file) {
* print_r($backup->notes()); * echo "Backed up to: $file";
* } else { * } else {
* print_r($backup->errors()); * echo "Backup failed: " . implode("<br>", $backup->errors());
* } * }
* ~~~~~ * ~~~~~
* Note: the `print_r()` function calls are just for demonstration and testing purposes. We are not suggesting
* you actually do that except when testing.
* *
* ### Restore a database * ### Restore a database
* ~~~~~ * ~~~~~
* $options = array(); // optional * $success = $backup->restore($file);
* $success = $backup->restore($file, $options);
* if($success) { * if($success) {
* print_r($backup->notes()); * echo "Restored database from file: $file";
* } else { * } else {
* print_r($backup->errors()); * echo "Restore failed: " . implode("<br>", $backup->errors());
* } * }
* ~~~~~ * ~~~~~
* #pw-body * #pw-body
@@ -271,6 +265,8 @@ class WireDatabaseBackup {
* - $backups->setDatabase(PDO|WireDatabasePDO); * - $backups->setDatabase(PDO|WireDatabasePDO);
* - $backups->setDatabaseConfig(array|object); * - $backups->setDatabaseConfig(array|object);
* *
* #pw-group-initialization
*
* @param string $path Path where database files are stored * @param string $path Path where database files are stored
* @throws \Exception * @throws \Exception
* *
@@ -282,6 +278,8 @@ class WireDatabaseBackup {
/** /**
* Set the current ProcessWire instance * Set the current ProcessWire instance
* *
* #pw-internal
*
* @param ProcessWire $wire * @param ProcessWire $wire
* *
*/ */
@@ -292,8 +290,16 @@ class WireDatabaseBackup {
/** /**
* Set the database configuration information * Set the database configuration information
* *
* @param array|object $config Containing these properties: dbUser, dbHost, dbPort, dbName, * #pw-group-initialization
* and optionally: dbPass, dbPath, dbCharset *
* @param array|Config|object $config Containing these properties:
* - dbUser
* - dbHost
* - dbPort
* - dbName
* - dbPass
* - dbPath (optional)
* - dbCharset (optional)
* @return $this * @return $this
* @throws \Exception if missing required config settings * @throws \Exception if missing required config settings
* *
@@ -329,7 +335,9 @@ class WireDatabaseBackup {
} }
/** /**
* Set the database connection * Set the PDO database connection
*
* #pw-group-initialization
* *
* @param \PDO|WireDatabasePDO $database * @param \PDO|WireDatabasePDO $database
* @throws \PDOException on invalid connection * @throws \PDOException on invalid connection
@@ -346,6 +354,8 @@ class WireDatabaseBackup {
/** /**
* Get current database connection, initiating the connection if not yet active * Get current database connection, initiating the connection if not yet active
* *
* #pw-advanced
*
* @return null|\PDO|WireDatabasePDO * @return null|\PDO|WireDatabasePDO
* @throws \Exception * @throws \Exception
* *
@@ -377,6 +387,8 @@ class WireDatabaseBackup {
/** /**
* Add an error and return last error * Add an error and return last error
* *
* #pw-group-reporting
*
* @param string $str If omitted, no error is added * @param string $str If omitted, no error is added
* @return string * @return string
* *
@@ -389,6 +401,8 @@ class WireDatabaseBackup {
/** /**
* Return all error messages that occurred * Return all error messages that occurred
* *
* #pw-group-reporting
*
* @param bool $reset Specify true to clear out existing errors or omit just to return error messages * @param bool $reset Specify true to clear out existing errors or omit just to return error messages
* @return array * @return array
* *
@@ -402,6 +416,8 @@ class WireDatabaseBackup {
/** /**
* Record a note * Record a note
* *
* #pw-group-reporting
*
* @param $key * @param $key
* @param $value * @param $value
* *
@@ -414,6 +430,8 @@ class WireDatabaseBackup {
/** /**
* Get all notes * Get all notes
* *
* #pw-group-reporting
*
* @param bool $reset * @param bool $reset
* @return array * @return array
* *
@@ -427,6 +445,8 @@ class WireDatabaseBackup {
/** /**
* Set path where database files are stored * Set path where database files are stored
* *
* #pw-group-initialization
*
* @param string $path * @param string $path
* @return $this * @return $this
* @throws \Exception if path has a problem * @throws \Exception if path has a problem
@@ -440,6 +460,14 @@ class WireDatabaseBackup {
return $this; return $this;
} }
/**
* Get path where database files are stored
*
* #pw-group-reporting
*
* @return string
*
*/
public function getPath() { public function getPath() {
return $this->path; return $this->path;
} }
@@ -449,6 +477,8 @@ class WireDatabaseBackup {
* *
* To get additional info on any of them, call getFileInfo($basename) method * To get additional info on any of them, call getFileInfo($basename) method
* *
* #pw-group-reporting
*
* @return array of strings (basenames) * @return array of strings (basenames)
* *
*/ */
@@ -468,7 +498,9 @@ class WireDatabaseBackup {
/** /**
* Get information about a backup file * Get information about a backup file
* *
* @param $filename * #pw-group-reporting
*
* @param string $filename
* @return array Returns associative array of information on success, empty array on failure * @return array Returns associative array of information on success, empty array on failure
* *
*/ */
@@ -535,6 +567,8 @@ class WireDatabaseBackup {
/** /**
* Get array of all table names * Get array of all table names
* *
* #pw-group-reporting
*
* @param bool $count If true, returns array will be indexed by name and include count of records as value * @param bool $count If true, returns array will be indexed by name and include count of records as value
* @param bool $cache Allow use of cache? * @param bool $cache Allow use of cache?
* @return array * @return array
@@ -576,6 +610,8 @@ class WireDatabaseBackup {
/** /**
* Perform a database export/dump * Perform a database export/dump
* *
* #pw-group-actions
*
* @param array $options Options to modify default behavior: * @param array $options Options to modify default behavior:
* - `filename` (string): filename for backup: default is to make a dated filename, but this can also be used (basename only, no path) * - `filename` (string): filename for backup: default is to make a dated filename, but this can also be used (basename only, no path)
* - `description` (string): optional description of this backup * - `description` (string): optional description of this backup
@@ -641,6 +677,15 @@ class WireDatabaseBackup {
return $success ? $file : false; return $success ? $file : false;
} }
/**
* Set backup options
*
* #pw-internal
*
* @param array $options
* @return $this
*
*/
public function setBackupOptions(array $options) { public function setBackupOptions(array $options) {
$this->backupOptions = array_merge($this->backupOptions, $options); $this->backupOptions = array_merge($this->backupOptions, $options);
return $this; return $this;
@@ -869,7 +914,13 @@ class WireDatabaseBackup {
/** /**
* Import a database SQL file that was created by this class * Restore/import a MySQL database dump file
*
* This method is designed to restore dump files created by the backup() method of this
* class, however it *may* also work with dump files created from other sources like
* mysqldump or PhpMyAdmin.
*
* #pw-group-actions
* *
* @param string $filename Filename to restore, optionally including path (if no path, then path set to construct is assumed) * @param string $filename Filename to restore, optionally including path (if no path, then path set to construct is assumed)
* @param array $options Options to modify default behavior: * @param array $options Options to modify default behavior:
@@ -910,6 +961,15 @@ class WireDatabaseBackup {
return $success; return $success;
} }
/**
* Set restore options
*
* #pw-internal
*
* @param array $options
* @return $this
*
*/
public function setRestoreOptions(array $options) { public function setRestoreOptions(array $options) {
$this->restoreOptions = array_merge($this->restoreOptions, $options); $this->restoreOptions = array_merge($this->restoreOptions, $options);
return $this; return $this;
@@ -1049,6 +1109,8 @@ class WireDatabaseBackup {
* *
* This method assumes both files follow the SQL dump format created by this class. * This method assumes both files follow the SQL dump format created by this class.
* *
* #pw-advanced
*
* @param string $filename1 Original filename * @param string $filename1 Original filename
* @param string $filename2 Filename that may have statements that will update/override those in filename1 * @param string $filename2 Filename that may have statements that will update/override those in filename1
* @param array $options * @param array $options
@@ -1143,6 +1205,8 @@ class WireDatabaseBackup {
/** /**
* Returns array of all create table statements, indexed by table name * Returns array of all create table statements, indexed by table name
* *
* #pw-internal
*
* @param string $filename to extract all CREATE TABLE statements from * @param string $filename to extract all CREATE TABLE statements from
* @param array $options * @param array $options
* @return bool|array of CREATE TABLE statements, associative: indexed by table name * @return bool|array of CREATE TABLE statements, associative: indexed by table name
@@ -1165,7 +1229,9 @@ class WireDatabaseBackup {
} }
/** /**
* Returns array of all INSERT statements, indexed by table name * Returns array of all INSERT statements in given filename, indexed by table name
*
* #pw-internal
* *
* @param string $filename to extract all CREATE TABLE statements from * @param string $filename to extract all CREATE TABLE statements from
* @return array of arrays of INSERT statements. Base array is associative indexed by table name. * @return array of arrays of INSERT statements. Base array is associative indexed by table name.

6
wire/core/WireHttp.php
View File

@@ -6,9 +6,11 @@
* Provides capability for sending POST/GET requests to URLs * Provides capability for sending POST/GET requests to URLs
* *
* #pw-summary WireHttp enables you to send HTTP requests to URLs, download files, and more. * #pw-summary WireHttp enables you to send HTTP requests to URLs, download files, and more.
* #pw-var $http
* #pw-instantiate $http = new WireHttp();
* #pw-body = * #pw-body =
* ~~~~~ * ~~~~~
* $http = new WireHttp(); * // Get the contents of a URL
* $response = $http->get("http://domain.com/path/"); * $response = $http->get("http://domain.com/path/");
* if($response !== false) { * if($response !== false) {
* echo "Successful response: " . $sanitizer->entities($response); * echo "Successful response: " . $sanitizer->entities($response);
@@ -899,7 +901,7 @@ class WireHttp extends Wire {
* - `content-type`: {content-type} (replaced with actual content type) * - `content-type`: {content-type} (replaced with actual content type)
* - `content-transfer-encoding`: binary * - `content-transfer-encoding`: binary
* - `content-length`: {filesize} (replaced with actual filesize) * - `content-length`: {filesize} (replaced with actual filesize)
* - To remove a header completely, make its value NULL and it won't be sent. * - To remove a header completely, make its value NULL and it won't be sent.
* @throws WireException * @throws WireException
* *
*/ */

11
wire/core/WireInput.php
View File

@@ -586,7 +586,16 @@ class WireInput extends Wire {
} }
/** /**
* Return the current request method (i.e. GET, POST) or blank if not known * Return the current request method (i.e. GET, POST, etc.) or blank if not known
*
* Possible return values are:
* - GET
* - POST
* - HEAD
* - PUT
* - DELETE
* - OPTIONS
* - or blank if not known
* *
* @return string * @return string
* @since 3.0.39 * @since 3.0.39

141
wire/core/WireMail.php
View File

@@ -6,32 +6,49 @@
* ProcessWire 3.x, Copyright 2016 by Ryan Cramer * ProcessWire 3.x, Copyright 2016 by Ryan Cramer
* https://processwire.com * https://processwire.com
* *
* USAGE: * #pw-summary A module type that handles sending of email in ProcessWire
* #pw-var $m
* #pw-body =
* *
* $mail = new WireMail(); * Below are 3 different ways you can get a new instance of WireMail.
* * When possible we recommend using option A or B below.
* // chained method call usage * ~~~~~
* $mail->to('user@domain.com')->from('you@company.com')->subject('Message Subject')->body('Message Body')->send(); * $m = $mail->new(); // option A
* $m = wireMail(); // option B
* $m = new WireMail(); // option C
* ~~~~~
* Once you have an instance of WireMail (`$m`), you can use it to send email like in these examples below.
* ~~~~~
* // chained (fluent) method call usage
* $m->to('user@domain.com')
* ->from('you@company.com')
* ->subject('Message Subject')
* ->body('Message Body')
* ->send();
* *
* // separate method call usage * // separate method call usage
* $mail->to('user@domain.com'); // specify CSV string or array for multiple addresses * $m->to('user@domain.com'); // specify CSV string or array for multiple addresses
* $mail->from('you@company.com'); * $m->from('you@company.com');
* $mail->subject('Message Subject'); * $m->subject('Message Subject');
* $mail->body('Message Body'); * $m->body('Message Body');
* $mail->send(); * $m->send();
* *
* // you can also set values without function calls: * // optionally specify “from” or “to” names as 2nd argument
* $mail->to = 'user@domain.com'; * $m->to('user@domain.com', 'John Smith');
* $mail->from = 'you@company.com'; * $m->from('you@company.com', 'Mary Jane');
* ...and so on.
* *
* // other methods or properties you might set (or get) * // other methods or properties you might set (or get)
* $mail->bodyHTML('<html><body><h1>Message Body</h1></body></html>'); * $m->bodyHTML('<html><body><h1>Message Body</h1></body></html>');
* $mail->header('X-Mailer', 'ProcessWire'); * $m->attachment('/path/to/file.ext');
* $mail->param('-f you@company.com'); // PHP mail() param (envelope from example) * $m->fromName('Mary Jane');
* $m->toName('John Smith');
* $m->header('X-Mailer', 'ProcessWire');
* $m->param('-f you@company.com'); // PHP mail() param (envelope from example)
* *
* // note that the send() function always returns the quantity of messages sent * // note that the send() function always returns the quantity of messages sent
* $numSent = $mail->send(); * $numSent = $m->send();
* ~~~~~
* #pw-body
* *
* @method int send() * @method int send()
* @property array $to * @property array $to
@@ -43,7 +60,7 @@
* @property string $bodyHTML * @property string $bodyHTML
* @property array $header * @property array $header
* @property array $param * @property array $param
* @property array $attachments * @property array $attachments Array of file attachments (if populated) #pw-advanced
* *
*/ */
@@ -70,7 +87,6 @@ class WireMail extends WireData implements WireMailInterface {
$this->mail['header']['X-Mailer'] = "ProcessWire/" . $this->className(); $this->mail['header']['X-Mailer'] = "ProcessWire/" . $this->className();
} }
public function __get($key) { public function __get($key) {
if(array_key_exists($key, $this->mail)) return $this->mail[$key]; if(array_key_exists($key, $this->mail)) return $this->mail[$key];
return parent::__get($key); return parent::__get($key);
@@ -146,11 +162,11 @@ class WireMail extends WireData implements WireMailInterface {
* you specify NULL as the email address, in which case it clears them all. * you specify NULL as the email address, in which case it clears them all.
* *
* @param string|array|null $email Specify any ONE of the following: * @param string|array|null $email Specify any ONE of the following:
* 1. Single email address or "User Name <user@example.com>" string. * - Single email address or "User Name <user@example.com>" string.
* 2. CSV string of #1. * - CSV string of #1.
* 3. Non-associative array of #1. * - Non-associative array of #1.
* 4. Associative array of (email => name) * - Associative array of (email => name)
* 5. NULL (default value, to clear out any previously set values) * - NULL (default value, to clear out any previously set values)
* @param string $name Optionally provide a TO name, applicable * @param string $name Optionally provide a TO name, applicable
* only when specifying #1 (single email) for the first argument. * only when specifying #1 (single email) for the first argument.
* @return $this * @return $this
@@ -203,7 +219,7 @@ class WireMail extends WireData implements WireMailInterface {
* *
* This sets the 'to name' for whatever the last added 'to' email address was. * This sets the 'to name' for whatever the last added 'to' email address was.
* *
* @param string * @param string The 'to' name
* @return $this * @return $this
* @throws WireException if you attempt to set a toName before a to email. * @throws WireException if you attempt to set a toName before a to email.
* *
@@ -238,7 +254,7 @@ class WireMail extends WireData implements WireMailInterface {
* It is preferable to do this with the from() method, but this is provided to ensure that * It is preferable to do this with the from() method, but this is provided to ensure that
* all properties can be set with direct access, i.e. $mailer->fromName = 'User Name'; * all properties can be set with direct access, i.e. $mailer->fromName = 'User Name';
* *
* @param string * @param string The 'from' name
* @return $this * @return $this
* *
*/ */
@@ -250,7 +266,7 @@ class WireMail extends WireData implements WireMailInterface {
/** /**
* Set the email subject * Set the email subject
* *
* @param string $subject * @param string $subject Email subject text
* @return $this * @return $this
* *
*/ */
@@ -262,7 +278,12 @@ class WireMail extends WireData implements WireMailInterface {
/** /**
* Set the email message body (text only) * Set the email message body (text only)
* *
* @param string $body in text only * ~~~~~
* $m = wireMail();
* $m->body('Hello world');
* ~~~~~
*
* @param string $body Email body in text only
* @return $this * @return $this
* *
*/ */
@@ -274,7 +295,14 @@ class WireMail extends WireData implements WireMailInterface {
/** /**
* Set the email message body (HTML only) * Set the email message body (HTML only)
* *
* @param string $body in HTML * This should be the text from an entire HTML document, not just an element.
*
* ~~~~~
* $m = wireMail();
* $m->bodyHTML('<html><body><h1>Hello world</h1></body></html>');
* ~~~~~
*
* @param string $body Email body in HTML
* @return $this * @return $this
* *
*/ */
@@ -286,11 +314,13 @@ class WireMail extends WireData implements WireMailInterface {
/** /**
* Set any email header * Set any email header
* *
* Note: multiple calls will append existing headers. * - Multiple calls will append existing headers.
* To remove an existing header, specify NULL as the value. * - To remove an existing header, specify NULL as the value.
* *
* @param string $key * #pw-advanced
* @param string $value *
* @param string $key Header name
* @param string $value Header value
* @return $this * @return $this
* *
*/ */
@@ -311,10 +341,15 @@ class WireMail extends WireData implements WireMailInterface {
/** /**
* Set any email param * Set any email param
* *
* See $additional_parameters at: http://www.php.net/manual/en/function.mail.php * See `$additional_parameters` at <http://www.php.net/manual/en/function.mail.php>
* Note: multiple calls will append existing params. *
* To remove an existing param, specify NULL as the value. * - Multiple calls will append existing params.
* This function may only be applicable to PHP mail(). * - To remove an existing param, specify NULL as the value.
*
* This function may only be applicable if you don't have other WireMail modules
* installed as email params are only used by PHP's `mail()` function.
*
* #pw-advanced
* *
* @param string $value * @param string $value
* @return $this * @return $this
@@ -333,17 +368,19 @@ class WireMail extends WireData implements WireMailInterface {
* Add a file to be attached to the email * Add a file to be attached to the email
* *
* ~~~~~~ * ~~~~~~
* $mail = new WireMail(); * $m = wireMail();
* $mail->to('user@domain.com')->from('hello@world.com'); * $m->to('user@domain.com')->from('hello@world.com');
* $mail->subject('Test attachment'); * $m->subject('Test attachment');
* $mail->body('This is just a test of a file attachment'); * $m->body('This is just a test of a file attachment');
* $mail->attachment('/path/to/file.jpg'); * $m->attachment('/path/to/file.jpg');
* $mail->send(); * $m->send();
* ~~~~~~ * ~~~~~~
* *
* Multiple calls will append attachments. * #pw-advanced
* To remove the supplied attachments, specify NULL as the value. *
* This function may not be supported by 3rd party WireMail modules. * - Multiple calls will append attachments.
* - To remove the supplied attachments, specify NULL as the value.
* - Attachments may or may not be supported by 3rd party WireMail modules.
* *
* @param string $value Full path and filename of file attachment * @param string $value Full path and filename of file attachment
* @param string $filename Optional different basename for file as it appears in the mail * @param string $filename Optional different basename for file as it appears in the mail
@@ -363,7 +400,9 @@ class WireMail extends WireData implements WireMailInterface {
/** /**
* Send the email * Send the email
* *
* This is the primary method that modules extending this class would want to replace. * Call this method only after you have specified at least the `subject`, `to` and `body`.
*
* #pw-notes This is the primary method that modules extending this class would want to replace.
* *
* @return int Returns a positive number (indicating number of addresses emailed) or 0 on failure. * @return int Returns a positive number (indicating number of addresses emailed) or 0 on failure.
* *
@@ -462,7 +501,9 @@ class WireMail extends WireData implements WireMailInterface {
} }
/** /**
* Encode the subject, use mbstring if available * Encode a subject, use mbstring if available
*
* #pw-advanced
* *
* @param string $subject * @param string $subject
* @return string * @return string
@@ -532,6 +573,8 @@ class WireMail extends WireData implements WireMailInterface {
* Uses short notation for charset and encoding suitable for email headers * Uses short notation for charset and encoding suitable for email headers
* as laid out in rfc2047. * as laid out in rfc2047.
* *
* #pw-advanced
*
* @param string $text * @param string $text
* @return string * @return string
* *

29
wire/core/WireMailTools.php
View File

@@ -7,6 +7,21 @@
* https://processwire.com * https://processwire.com
* *
* #pw-summary Provides an API interface to email and WireMail. * #pw-summary Provides an API interface to email and WireMail.
* #pw-body =
* ~~~~~
* // Simple usage example
* $message = $mail->new();
* $message->subject('Hello world')
* ->to('user@domain.com')
* ->from('you@company.com');
* ->body('Hello there big world')
* ->bodyHTML('<h2>Hello there big world</h2>');
* $numSent = $message->send();
* ~~~~~
* #pw-body
*
* @method WireMail new() Create a new WireMail() instance
* @property WireMail new Get a new WireMail() instance (same as method version)
* *
* *
*/ */
@@ -17,10 +32,10 @@ class WireMailTools extends Wire {
* Get a new WireMail instance for sending email * Get a new WireMail instance for sending email
* *
* ~~~~~ * ~~~~~
* $mailer = $mail->new(); * $message = $mail->new();
* $mailer->to('user@domain.com')->from('you@company.com'); * $message->to('user@domain.com')->from('you@company.com');
* $mailer->subject('Mail Subject')->body('Mail Body Text')->bodyHTML('Body HTML'); * $message->subject('Mail Subject')->body('Mail Body Text')->bodyHTML('Body HTML');
* $numSent = $mailer->send(); * $numSent = $message->send();
* ~~~~~ * ~~~~~
* *
* @return WireMail * @return WireMail
@@ -41,6 +56,7 @@ class WireMailTools extends Wire {
} }
// if no module found, default to WireMail // if no module found, default to WireMail
if(is_null($mail)) $mail = $this->wire(new WireMail()); if(is_null($mail)) $mail = $this->wire(new WireMail());
/** @var WireMail $mail */
// reset just in case module was not singular // reset just in case module was not singular
$mail->to(); $mail->to();
@@ -138,4 +154,9 @@ class WireMailTools extends Wire {
return $numSent; return $numSent;
} }
public function __get($key) {
if($key === 'new') return $this->new();
return parent::__get($key);
}
} }