creativehandles/ch-contact-form

使用此包，我们可以轻松地在项目中实现联系表单。

维护者

详细信息

bitbucket.org/creativehandles/ch-contact-form

主页

源代码

安装: 3

依赖项: 0

建议者: 0

安全性: 0

0.1.1 2021-11-04 12:04 UTC

Requires

Requires (Dev)

MIT 042273904a9de68f6797b92206e9359b0d07760a

  • Kasun Eranda <kasun.eranda.woop@creativehandles.com>

creativehandlesch-contact-form

This package is auto-updated.

Last update: 2024-09-04 18:24:05 UTC

README

Latest Version on Packagist

Total Downloads

GitHub Actions

此包旨在通过简单的配置操作多个表单。此包包括带有附件的通知、文件上传、表单验证等。

安装

您可以通过composer安装此包。

composer require creativehandles/ch-contact-form

然后构建插件环境并发布其资源。

php artisan creativehandles:build-ch-contact-forms

用法

安装后，您可以在config目录下看到默认的ch-contact-form.php配置文件。这是此包最重要的部分。通过编辑此文件，您可以创建多个您想要的联系表单。

基本配置文件结构

以下是配置文件的基本结构。此文件主要包含两个重要部分：

1. 默认配置

2. 表单块

[

/** Default Values **/
	'default' => [
		'storage' => 'local',
		'path' => 'temp',
		'file_name' => md5(uniqid(time())),
		'locale' => 'cs',  // Set `Content-locale` header to override this value
	],
/** END Default Values **/

/** START Form BLOCK Configuration */
'YOUR_FORM_NAME' => [ 			// 1
	'recaptcha' => [..],		// 2
	'param' => [..],			// 3
	'attachments' => [..],		// 4
	'message_on' => [..],		// 5
	'notifications' => [..],	// 6
];
/** END Form BLOCK Configuration*/

表单块配置

注意 - 当未提供相关值时，应用默认值。

  1. YOUR_FORM_NAME

    这是您的表单名称，它应该是唯一的值。当您通过API调用此表单时，您需要在请求的form_name参数下传递此键名，插件将选择相关的配置。

/** START Form BLOCK Configuration */
'YOUR_FORM_NAME' => [
		//other configurations
];
/** END Form BLOCK Configuration*/

  1. Recaptcha

    此配置允许您在表单中添加google recaptcha V2、V3验证。首先，您需要在您的应用中启用google recaptcha，在您的services.php配置文件中提供以下配置。注意：您需要在您的应用中安装 "google/recaptcha": "^1.2", 库才能使recaptcha正常工作。

    composer require google/recaptcha": "^1.2

config/services.php

'google' => [
	'recaptcha' => [
		'site_key' => env('GOOGLE_RECAPTCHA_SITE_KEY'),
		'secret_key' => env('GOOGLE_RECAPTCHA_SECRET_KEY'),
		'default_score_threshold' =>env('GOOGLE_RECAPTCHA_DEFAULT_SCORE_THRESHOLD'),
		'default_challenge_timeout' => env('GOOGLE_RECAPTCHA_DEFAULT_CHALLENGE_TIMEOUT')
	]
],

通过将enabled设置为TRUE，您可以在表单中启用recaptcha。然后，您需要添加以下值以使其正常工作，否则recaptcha将无法工作。action值是您提供给recaptcha JS库的值。在成功执行API调用后，google recaptcha将返回recaptcha token。然后，您需要将此token传递给插件以使用recaptcha验证表单。因此，后端需要识别包含在表单请求本身的token字段名称。您可以通过提供该字段名称在token_field键下定义该字段。

默认情况下，recaptcha启用为V2版本。如果您需要使用V3版本，请将v3提供在版本键下。

'recaptcha' =>[
	'enabled' => false,
	'action' => 'ACTION',
	'token_field' => 'TOKEN_FIELD_NAME',
	'version'=> null,  //v2 or v3 
]

  1. 参数

    在此键下，您可以定义您的表单字段名称及其后端验证规则。您可以使用字段名称作为key，后端验证作为value。

'param' => [
	//'field_name' => 'FIELD_VALIDATION_RULES'
	'name' => 'required|string',
	'file' => 'sometimes|nullable|file|mimes:docx,doc,odt,pdf,jpeg,png',
],

  1. 附件

    如果您的表单包含文件上传，您可以选择如何保存它。

'attachments' => [

	/** START Attachment block */
	[
		'field' => 'FILE_UPLOAD_FIELD_NAME',
		'save' => [
			'file' => [
				'name' => 'original',
				'given_name' => null
			],
			'in' => [
				'path' => null,
				'disk' => null
			],
	]
	/** END Attachment Block */
]

因此，您需要通过field键传递请求文件上传表单字段的精确名称。为了确定如何保存此文件在您的存储中，您可以使用save数组键。位于field数组键下的name键可以有三个主要值：random | given | original。其功能如下：

  • random - 这将在保存文件时生成随机文件名
  • original - 这将使用上传的文件名作为保存文件名
  • given - 如果您选择此选项，您可以在given_name键下提供所需的名称作为保存文件名。如果没有提供，将应用默认文件名到在default->file_name键下生成的文件。
'file' => [
	'name' => 'original',
	'given_name' => null
],

通过使用 in 数组键来确定保存文件的位置。您可以指定保存路径和磁盘。如果数组键值不存在，将应用默认值。

'in' => [
	'path' => null,
	'disk' => null
],

  1. 消息开启

    当表单操作成功或失败时，将返回这些值。

'message_on' => [
	'success' => 'Form Submission Successful',
	'fail' => 'Form Submission Unsuccessful',
],
  1. 通知

您还可以使用此插件发送通知。因此，您需要添加通知配置块。

'notifications' => [

	/** START Notification Block */
	[
		'name' => 'YOUR_NOTIFICATION_NAME_SPACE',
		'notify' => [
			'form_input' => true,
			'values' => 'email'
		],
		'attachments' => [
			[
				'type' => 'url',
				'link' => 'FILE_URL'
			],
			[
				'type' => 'local',
				'field' => 'FILE_NAME_FIELD_ON_REQUEST',
				'disk' => 'FILE_SAVE_DISK',
				'delete_on_success' => true,
				'link' => null
			],
		]
	]
	/** END Notification Block */
]

您可以使用自己的通知类，因此您需要在 name 键下传递通知类命名空间。然后，您可以通过配置 notify 键来选择谁需要收到通知。

'notify' => [
	'form_input' => true,
	'values' => 'email'
],

如果您使用表单字段值作为通知，则需要将 form_input 键设置为 TRUE，然后在 values 键下传递该表单字段名作为值。或者，您可以设置 form_input 为 FALSE 并通过逗号（,）分隔提供一些电子邮件地址。

如果您计划通过通知发送一些附件，可以通过使用位于 notification 对象内的 attachments 对象来完成。还需要在通知的 notify 方法内调用以下方法，以便将附件添加到通知中。默认情况下，插件会将在通知构造方法中注入表单数据。

\Creativehandles\ChContactForm\ChContactFormFacade::pushAttachments($notify,$notification_data)

以下示例显示了邮件通知示例。

/** This is a Notification Class */
public  $data; // form data injected by plugin

public  function  __construct(array  $data)
{
	$this->data = $data;
}

public  function  toMail($notifiable)
{
	$mail = (new  MailMessage)
		->subject('Something')
		->line('hello');
	return  \Creativehandles\ChContactForm\ChContactFormFacade::pushAttachments($mail,$this->data);
}

'attachments' => [
	[
		'type' => 'url',
		'link' => 'FILE_URL'
	],
	[
		'type' => 'local',
		'field' => 'FILE_NAME_FIELD_ON_REQUEST',
		'disk' => 'FILE_SAVE_DISK',
		'delete_on_success' => true
	],
]

您可以附加 表单输入文件 或 来自URL的外部文件

  • 要附加表单请求输入文件，请执行以下配置：将 type 设置为 local，然后在 field 键下提供表单字段名。然后在 disk 键下提供文件保存磁盘。如果您希望在通知发送后从您的存储中删除文件附件，则将 delete_on_success 设置为 TRUE。

  • 要附加来自外部URL的外部文件，请将 type 设置为 url。最后，在 link 键下放置URL。

如何为创建的表单进行API调用

插件已提供API端点以调用您的表单。为了识别您的表单，您需要将表单名称作为请求参数传递，与请求一起传递。

端点 - BASE_URL/api/v1/forms 方法 - POST 标头 - Content-locale:YOUR_LOCAL //未提供标头，将应用插件配置中的默认区域设置 表单参数 -

{
	"form_name": "YOUR_FORM_NAME", //must include this
	......other form fields.......
}

错误状态码

  • 403 - 无效的Recaptcha
  • 200 - 表单提交成功
  • 422 - 验证错误
  • 500 - 内部服务器错误

注意 - 通过提供内容区域设置标头，您可以将本地化通知传递。

完整配置文件

<?php

return [
	/** Default Values **/
	'default' => [
		'storage' => 'local',
		'path' => 'temp',
		'file_name' => md5(uniqid(time())),
		'locale' => 'cs'  // Set `Content-locale` header to override this value
	],
	/** END Default Values **/

	/** START Form BLOCK Configuration */
	'YOUR_FORM_NAME' => [
		'recaptcha' =>[
			'enabled' => false,
			'action' => 'ACTION',
			'token_field' => 'TOKEN_FIELD_NAME',
			'version'=> null,  //v2 or v3 | By default v2
		],
		'param' => [
			//'field_name' => 'FIELD_VALIDATION_RULES'
			'name' => 'required|string',
		],
		'attachments' => [
			/** START Attachment block */
			[
			'field' => 'FILE_UPLOAD_FIELD_NAME',
			'save' => [
				'file' => [
					'name' => 'original', // random|original|given
					'given_name' => null
				],
				'in' => [
					'path' => null,
					'disk' => null
				],
			]
			/** END Attachment Block */
		],
		'message_on' => [
			'success' => 'Form Submission Successful',
			'fail' => 'Form Submission Unsuccessful',
		],
		'notifications' => [
			/** START Notification Block */
			[
				'name' => 'YOUR_NOTIFICATION_NAMESPACE',
				'notify' => [
					'form_input' => true,
					'values' => 'email'
				],
				'attachments' => [
					[
						'type' => 'url',
						'link' => 'FILE_URL'
					],
					[
						'type' => 'local',
						'field' => 'FILE_NAME_FIELD_ON_REQUEST',
						'disk' => 'FILE_SAVE_DISK',
						'delete_on_success' => true,
						'link' => null
					],
				]
			]
			/** END Notification Block */
		],
	]
		/** END Form BLOCK Configuration*/
]

测试


composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献。

安全性

如果您发现任何安全相关的问题，请通过电子邮件kasun.eranda@creativehandles.com联系，而不是使用问题跟踪器。

鸣谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。