get_args() as $arg ) {
$group = explode( '.', $arg['flag'], 2 )[0];
$grouped[ $group ][] = $arg;
}
// Order known groups first, then anything else in registry order.
$ordered = [];
foreach ( self::$group_order as $group ) {
if ( isset( $grouped[ $group ] ) ) {
$ordered[ $group ] = $grouped[ $group ];
unset( $grouped[ $group ] );
}
}
foreach ( $grouped as $group => $args ) {
$ordered[ $group ] = $args;
}
$lines = [];
$lines[] = '## ' . __( 'CONFIGURATION FLAGS', 'wp-mail-smtp' );
$lines[] = '';
$lines[] = __( 'These flags accept their value as a literal (--flag=value), from a file (--flag-file=), or from an environment variable (WPMS_).', 'wp-mail-smtp' );
$lines[] = '';
foreach ( $ordered as $group => $args ) {
$lines[] = self::group_label( $group ) . ':';
$lines[] = '';
foreach ( $args as $arg ) {
$lines[] = '[--' . $arg['flag'] . '=' . self::value_shape( $arg ) . ']';
$lines[] = ': ' . self::description( $arg );
$lines[] = '';
}
}
return rtrim( implode( "\n", $lines ) ) . "\n";
}
/**
* The `` placeholder for an arg's `--flag=...` form.
*
* Enum shapes stay ``; the allowed values are listed in the description.
*
* @since 4.9.0
*
* @param array $arg Registry arg.
*
* @return string
*/
private static function value_shape( array $arg ) {
$shapes = [
'int' => '',
'bool' => '',
'email' => '',
'enum' => '',
];
return $shapes[ $arg['type'] ] ?? '';
}
/**
* Assemble the description line: registry description, then any
* required / required_if / sensitive notes appended in that order.
*
* @since 4.9.0
*
* @param array $arg Registry arg.
*
* @return string
*/
private static function description( array $arg ) {
$parts = [ wp_strip_all_tags( $arg['description'] ) ];
if ( ! empty( $arg['required'] ) ) {
$parts[] = __( 'Required.', 'wp-mail-smtp' );
}
if ( ! empty( $arg['required_if'] ) && is_array( $arg['required_if'] ) ) {
$conditions = [];
foreach ( $arg['required_if'] as $flag => $value ) {
$conditions[] = '--' . $flag . '=' . self::format_required_if_value( $value );
}
$parts[] = sprintf(
/* translators: %s is a list of "--flag=value" conditions joined by " and " (e.g. "--mail.mailer=smtp and --smtp.auth=true"). Flags and values are not translated. */
__( 'Required when %s.', 'wp-mail-smtp' ),
implode( ' ' . __( 'and', 'wp-mail-smtp' ) . ' ', $conditions )
);
}
if ( ! empty( $arg['sensitive'] ) ) {
$env_var = ! empty( $arg['env_var'] )
? $arg['env_var']
: 'WPMS_' . strtoupper( str_replace( '.', '_', $arg['flag'] ) );
$parts[] = sprintf(
/* translators: %1$s is the dotted CLI flag (e.g. smtp.pass). %2$s is the matching environment variable name (e.g. WPMS_SMTP_PASS). Flag and env var name are not translated. */
__( 'Sensitive: also accepts --%1$s-file= or env var %2$s.', 'wp-mail-smtp' ),
$arg['flag'],
$env_var
);
}
return implode( ' ', $parts );
}
/**
* Map a group slug to its section-header label.
*
* Brand names stay literal (untranslated); generic labels are translatable;
* unknown groups fall back to `ucfirst`.
*
* @since 4.9.0
*
* @param string $group Group slug.
*
* @return string
*/
private static function group_label( $group ) {
$labels = [
'mail' => __( 'Mail', 'wp-mail-smtp' ),
'general' => __( 'General', 'wp-mail-smtp' ),
'smtp' => 'SMTP',
'sendgrid' => 'SendGrid',
'mailgun' => 'Mailgun',
'postmark' => 'Postmark',
'sendlayer' => 'SendLayer',
'resend' => 'Resend',
'smtpcom' => 'SMTP.com',
'smtp2go' => 'SMTP2GO',
'sparkpost' => 'SparkPost',
'mailjet' => 'Mailjet',
'mailersend' => 'MailerSend',
'brevo' => 'Brevo',
'elasticemail' => 'Elastic Email',
'amazonses' => 'Amazon SES',
'mandrill' => 'Mandrill',
'logs' => __( 'Email Logs', 'wp-mail-smtp' ),
'rate_limit' => __( 'Rate Limiting', 'wp-mail-smtp' ),
'control' => __( 'Email Controls', 'wp-mail-smtp' ),
'alert' => __( 'Alerts', 'wp-mail-smtp' ),
];
return $labels[ $group ] ?? ucfirst( $group );
}
/**
* Render a `required_if` value for display. Booleans become the literal
* strings `true`/`false`; everything else passes through as-is. Matches
* how operators type the value on the command line.
*
* @since 4.9.0
*
* @param mixed $value Condition value.
*
* @return string
*/
private static function format_required_if_value( $value ) {
if ( is_bool( $value ) ) {
return $value ? 'true' : 'false';
}
return (string) $value;
}
}