التسميات
`labels->list` و`listAll` و`iterate` و`listColors` و`get` و`create` و`update` و`delete`.
كل الدوالّ
$page = $client->labels->list(limit: 50);$every = $client->labels->listAll();$colors = $client->labels->listColors();echo count($page), ' ', count($every), ' ', count($colors), PHP_EOL; foreach ($client->labels->iterate() as $row) { echo $row['name'], ' ', $row['threadCount'], PHP_EOL;} $created = $client->labels->create([ 'name' => 'Invoices', 'color' => ['backgroundColor' => 'gradient:sunset'],]); $client->labels->update($created['id'], ['name' => 'Invoices 2027']);$client->labels->update($created['id'], ['color' => ['backgroundColor' => '#3B82F6']]); $label = $client->labels->get($created['id']);echo $label['name'], ' ', $label['color']['backgroundColor'] ?? 'no colour', PHP_EOL; $client->labels->delete($created['id']);يعيد list صفحة OpenEmail\Result\Page واحدة من التسميات مرتّبة حسب الاسم، ويمر listAll وiterate على كل الصفحات. ويعيد listAll مصفوفة واحدة، ويعيد iterate كائن Generator يسلّم تسمية واحدة في كل مرة. وكل تسمية مصفوفة مفاتيحها بصيغة camelCase تحمل لونها وthreadCount ووقت إنشائها وآخر تغيير لها. ويعيد listColors لوحة ألوان التطبيق، أربعة عشر لونًا مصمتًا وسبعة تدرّجات، في صورة قائمة بسيطة من المصفوفات دون ترقيم صفحات. وtype دائمًا user. والمعرّف مأخوذ من الاسم الذي أُنشئت به التسمية، فـ Invoices هو USER_INVOICES، ولا يتغيّر أبدًا.
حقول create وupdate مفاتيح مصفوفة واحدة بأسماء API، فاللون هو 'color' => ['backgroundColor' => '#3B82F6'].
التسمية تخصّ مساحة العمل، فإعادة تسميتها أو تغيير لونها أو حذفها يغيّرها لكل عضو وكل مفتاح. ويضع threads->update التسميات على محادثة ويزيلها، ويسرد $client->threads->list(folder: 'USER_INVOICES') كل محادثة تحمل تسمية. وتشرح صفحة المحادثات الأمرين كليهما.
المعاملات: labels->create وlabels->update
namestring- الاسم المعروض للتسمية، تُشذَّب فراغاته قبل قياسه، فالحد من 1 إلى 225 حرفًا بعد التشذيب. وهو إلزامي في `create` واختياري في `update`، حيث يُبقي إغفاله الاسم كما هو. والفراغات وحدها تعطي 422. والاسم الذي تحمله تسمية أخرى بالفعل، مع تجاهل حالة الأحرف، يعطي 409 `label_name_taken`، يُرمى في صورة `ConflictException`. ويرفض `create` بمجرد أن تضم مساحة العمل 50 تسمية، بالخطأ 422 `label_limit_reached`، يُرمى في صورة `ValidationException`.
colorarray or null- اختياري في كلا الاستدعاءين. إغفاله في `update` يُبقي اللون المخزَّن، و`'color' => null` يمسحه. والمتن صارم، فمفتاح قريب الشبه مثل `colour` يعطي 422 بدل عملية صامتة بلا أثر.
color.backgroundColorstringمطلوب- لون hex (`#RGB` أو `#RGBA` أو `#RRGGBB` أو `#RRGGBBAA`، ويُخزَّن بأحرف كبيرة) أو رمز تدرّج: `gradient:sunset` أو `gradient:ember` أو `gradient:meadow` أو `gradient:lagoon` أو `gradient:aurora` أو `gradient:berry` أو `gradient:midnight`. والسلسلة الفارغة تعني بلا لون، وأي شيء آخر يعطي 422 `invalid_parameter`.
color.textColorstring- يُقبل ويُتجاهل. يُحسب الحبر من `backgroundColor`، بالطريقة نفسها التي يتبعها التطبيق.
الاستجابة: تسمية
التسمية مصفوفة مفاتيحها بصيغة camelCase، فيقرأ $label['threadCount'] العدد، ويقرأ $label['color']['backgroundColor'] ?? null اللون ويعطي null حين لا يكون للتسمية لون.
objectstring- دائمًا السلسلة `label`. ويعيد `create` و`update` المصفوفة نفسها، مقروءًا كما هو مخزَّن.
idstring- معرّف التسمية، وهو ما يأخذه `get` و`update` و`delete` و`threads->update`. ولا يتغيّر أبدًا، حتى بعد إعادة التسمية.
namestring- ما يراه المستخدم.
typestring- دائمًا `user`. فتسميات النظام لا تُقدَّم هنا أبدًا، ومعرّف نظام في `get` يعطي 404، يُرمى في صورة `NotFoundException`.
colorarray or null- يكون null حين لا يكون للتسمية لون.
color.backgroundColorstring- اللون المخزَّن: قيمة ست عشرية أو رمز تدرّج. ويعطي `listColors` طرفَي التدرّج.
color.textColorstring- الحبر الذي يرسمه التطبيق على اللون، `#18181B` أو `#FFFFFF`، ويُحسب على الخادم ولا يُخزَّن.
threadCountint- عدد المحادثات التي تحمل التصنيف الآن. وبالنسبة إلى مفتاح مقيّد بعناوين معيّنة لا تُعدّ إلا المحادثات المُسلَّمة إليها.
createdAtstring or null- وقت إنشاء التصنيف بصيغة ISO 8601، أو null لتصنيف أُنشئ قبل تسجيل هذه الأوقات.
updatedAtstring or null- آخر إعادة تسمية أو تغيير لون بصيغة ISO 8601، أو null لتصنيف أُنشئ قبل تسجيل هذه الأوقات.
الاستجابة: عيّنة لون (labels->listColors)
kindstring- ما إذا كانت العيّنة لونًا واحدًا أو تدرّجًا: `solid` أو `gradient`.
namestring- اسم المربّع، مثل `red` أو `sunset`.
valuestring- ما يُرسل بوصفه `color.backgroundColor` لاستخدام هذا المربّع.
solidstring- قيمة hex واحدة للمواضع التي لا يمكن رسم تدرّج فيها. وهي نفسها `value` في اللون المصمت.
fromstring or null- حيث يبدأ التدرّج، مرسومًا بزاوية 135 درجة. ويكون null في اللون المصمت.
tostring or null- حيث ينتهي التدرّج. ويكون null في اللون المصمت.
textColorstring- الحبر الذي يرسمه التطبيق على هذا المربّع.