النماذج
`forms->list` و`listAll` و`iterate` و`get` و`create` و`design` و`redesign` و`update` و`delete` و`publish` و`pause` و`resume` و`duplicate` و`analytics` و`listStarters` و`getStarter` و`listSubmissions` و`getSubmission` و`deleteSubmission` و`deleteSubmissions` و`approveSubmission` و`resendConfirmation` و`subscribe`.
كل الدوالّ
use OpenEmail\Constants\FormStarterSlugs;use OpenEmail\Constants\FormSubmissionStatuses; $form = $client->forms->create([ 'name' => 'Newsletter sign-up', 'starter' => FormStarterSlugs::NEWSLETTER, 'settings' => ['audienceIds' => ['aud_4c1b8e2a7d9f05c36b4e8a71']], 'publish' => true,]); echo $form['url'], ' ', $form['subscribeUrl'], PHP_EOL; $saved = $client->forms->update($form['id'], [ 'settings' => ['doubleOptIn' => true, 'senderAddress' => '[email protected]'], 'expectedUpdatedAt' => $form['updatedAt'],]); $signup = $client->forms->subscribe($form['id'], [ 'email' => '[email protected]', 'first_name' => 'Ann', 'consent' => true,]); foreach ($client->forms->iterateSubmissions($form['id'], status: FormSubmissionStatuses::PENDING) as $submission) { if ($submission['expired']) { $client->forms->resendConfirmation($form['id'], $submission['id']); }} $stats = $client->forms->analytics($form['id'], days: 30);$starters = $client->forms->listStarters(); $client->forms->pause($form['id']);$client->forms->resume($form['id']);$copy = $client->forms->duplicate($form['id']);$client->forms->delete($copy['id']); echo $saved['senderIssue'] ?? 'ready to send', ' ', $signup['outcome'], ' ', $stats['totals']['conversion'] ?? 'no views yet', ' ', count($starters), PHP_EOL;يحتفظ النموذج بمسودة document وبـ publishedDocument الذي يراه الزوار. ويغيّر update المسودة والإعدادات، وينشر publish المسودة. وتسري الإعدادات فورًا، سواء نُشر النموذج أم لا، ويرفض expectedUpdatedAt بالخطأ 409 version_conflict، المرمي في صورة ConflictException، أي حفظ قد يكتب فوق حفظ شخص آخر.
حقول النموذج مفاتيح مصفوفة واحدة بأسماء API بصيغة camelCase (expectedUpdatedAt وdoubleOptIn)، بينما المرشِّحات والخيارات وسائط مسمّاة (status: في listSubmissions وoffsetMinutes: في analytics). ويعود النموذج في صورة مصفوفة مفاتيحها بصيغة camelCase، فيقرأ $form['subscribeUrl'] العنوان الذي يستقبل الاشتراكات.
يبني design نموذجًا جديدًا في صورة مسودة انطلاقًا من وصف مكتوب، كما يفعل «إنشاء بالذكاء الاصطناعي» في صفحة النماذج، ويطبّق redesign تعليمات مكتوبة على مسودة نموذج، كما يفعل «اسأل الذكاء الاصطناعي» في منشئ النماذج. ويستهلك كل منهما إجراء ذكاء اصطناعي واحدًا ولا يكتب إلا المسودة، فلا يرى الزوار أي جديد حتى publish.
القراءة تتطلب forms:read والتغيير يتطلب forms:write. ويتطلب approveSubmission أيضًا contacts:write، لأنه يضيف جهة اتصال. ويتطلب resendConfirmation أيضًا emails:send، وكذلك الاستدعاء الذي يجعل النموذج يرسل بريدًا: تفعيل doubleOptIn، أو تعيين senderAddress أو رسالة التأكيد، أو نشر نموذج ذي تأكيد مزدوج أو استئنافه. ويطلب delete رمز تحقق من رمز وصول OAuth، ولا يطلبه من مفتاح API أبدًا. وإلى أن يحصل الرمز على تحقق، يرمي delete استثناء PermissionException تكون قيمة isStepUpRequired() فيه true.
يسجّل subscribe اشتراك الشخص كما تفعل صفحة النموذج، ولا يرسل أي بيانات اعتماد، حتى من عميل يحملها، فيُتجاهل apiKey:. والإجابات وسيطه الثاني، وهي مصفوفة واحدة مفاتيحها مفاتيح حقول النموذج. وكل الاشتراكات من شبكة واحدة تتقاسم حدًّا واحدًا قدره 40 اشتراكًا كل عشر دقائق، لذا فالخادم الذي ينقل اشتراكات أشخاص كثيرين يبلغه سريعًا: أضف من تعرفهم بالفعل عبر audiences->importContacts بدلًا من ذلك. وبعد تجاوز الحد يرمي الاستدعاء RateLimitException. ومرّر الصفحة التي كان عليها النموذج بوصفها oe_source، ولا ترسل oe_started، وأرسل oe_website فارغًا أو لا ترسله أصلًا.
الخطأ 422 من subscribe هو invalid_form_submission، يُرمى في صورة ValidationException، ويسرد fields الخاص بالاستثناء كل إجابة ناقصة أو غير صالحة في صورة مصفوفة فيها key وerror، بأسباب مثل required وemail وoption. ويسمّي OpenEmail\Constants\FormFieldErrors كل الأسباب. والحزمة تعمل على خادم. أما المتصفح فيرسل الإجابات بنفسه إلى subscribeUrl الخاص بالنموذج، كمتن JSON أو مع ترويسة Accept: application/json، ويتلقى JSON من أي أصل. ودون أيٍّ منهما يتلقى إعادة توجيه 303 إلى الصفحة المستضافة.
الاستجابة: نموذج
يعيد list صفحة OpenEmail\Result\Page واحدة من النماذج، من الأحدث، دون document وsettings. ويعيد listAll كل النماذج في مصفوفة واحدة، ويعيد iterate كائن Generator يمر على كل الصفحات نموذجًا تلو الآخر. ويعيد get وcreate وupdate وpublish وpause وresume وduplicate النموذج كاملًا في صورة مصفوفة، تضيف document وpublishedDocument وsettings وaudiences وsenderIssue وsenderProblem.
idstring- المعرّف الدائم، `frm_` يليه 24 حرفًا ست عشريًا.
statusstring- `draft` حتى أول نشر، ثم `live` ما دام يستقبل الاشتراكات و`paused` ما دام لا يستقبلها. ولا يعود النموذج أبدًا إلى `draft`. ويسمّي `OpenEmail\Constants\FormStatuses` الحالات الثلاث.
urlstring- الصفحة المستضافة للنموذج المنشور، لمشاركتها رابطًا.
subscribeUrlstring- المكان الذي يرسل إليه نموذج HTML عادي، أو سكربت في المتصفح، الإجابات.
documentarray- المسودة: `fields` بالترتيب، ونصوص `copy` المحيطة بها، و`style`.
publishedDocumentarray or null- ما يراه الزوار الآن، أو null حتى أول نشر.
settingsarray- إلى أين تذهب الاشتراكات وما يحدث بعد كل اشتراك: `audienceIds` و`doubleOptIn` و`senderAddress` ورسالة التأكيد و`successAction` و`redirectUrl` و`notifyAddresses`.
hasUnpublishedChangesbool- قيمته true حين تختلف المسودة عما يراه الزوار. وقيمته false دائمًا قبل أول نشر.
senderIssuestring or null- لماذا يتعذّر على نموذج ذي تأكيد مزدوج إرسال رسائل التأكيد الآن: `missing` أو `not_sendable` أو `not_allowed`. ويكون null حين يمكنه ذلك. ويسمّي `OpenEmail\Constants\FormSenderIssues` الثلاثة.
statsarray- `views` و`submissions` و`added` و`pending` و`lastSubmittedAt`، محسوبةً لحظة القراءة.
الردود
يرقّم listSubmissions الصفحات من الأحدث، مع q: للبحث في عناوين البريد الإلكتروني وstatus: لاختيار pending أو added، ويمر listAllSubmissions وiterateSubmissions على كل الصفحات. ويسمّي OpenEmail\Constants\FormSubmissionStatuses الحالتين. وكل رد على النموذج مصفوفة تحتفظ بالإجابات كما أُرسلت، بتسمياتها، فتبقى قراءته صحيحة بعد تغيّر النموذج.
يعيد resendConfirmation الرد مع confirmationSent. وتكون قيمته false حين لا يخرج شيء: فالعنوان الواحد يتلقى تأكيدًا واحدًا لكل نموذج كل عشر دقائق وخمسة في اليوم على مستوى مساحة العمل، والرد المضاف لا يتلقى أي تأكيد. ويعلّم expired اشتراكًا معلّقًا انتهت صلاحية أحدث رابط له.