مرجع Gotenberg API

لمحة سريعة

توفّر حزمة ⁨Gotenberg⁩ جسر خدمة واحدًا هو GotenbergBridge. يحوّل هذا الجسر مستند ⁨Office⁩ (docx، xlsx، pptx، odt، ods، odp) إلى صيغة المستندات المحمولة (⁨PDF⁩) عبر إرسال طلب ⁨POST⁩ إلى خدمة ⁨Gotenberg⁩ خارجية. يعمل الجسر مع كائنات القيمة التي تمرّرها إليه أو تقرؤها منه: GotenbergConfig (واصف الخدمة غير القابل للتغيير وحدوده)، وOfficeFormat (تعداد الصيغ المدعومة)، وGotenbergConvertPayload (متن الطلب متعدد الأجزاء)، وGotenbergConvertResult (استجابة ⁨PDF⁩ بعد تحليلها). وتوفّر طبقة ثانية، هي GotenbergSecurityPolicy وGotenbergResponseParser وPinnedCurlTransport، آليات التحقق والتحليل والنقل المثبَّت التي يشغّلها الجسر داخليًا. استخدم هذه الطبقة فقط عند كتابة شيفرة نقل مخصصة أو شيفرة اختبار.

ابدأ من هنا: أنشئ GotenbergConfig باستخدام عنوان ⁨URL⁩ لخدمتك عبر بروتوكول نقل النص التشعبي الآمن (⁨HTTPS⁩)، ثم مرّره إلى GotenbergBridge مع عميل ⁨PSR-18⁩ ومصانع ⁨PSR-17⁩ الخاصة بك. استدعِ convertFile() أو convertString()، ثم اقرأ pdfData من GotenbergConvertResult المُعاد.

المهام الشائعة

استخدم هذه المقتطفات المتحقَّق منها والقابلة للتشغيل للمهام الأكثر شيوعًا في الحزمة.

تحويل ملف على القرص إلى ⁨PDF⁩

وجّه الجسر إلى مسار الملف، فهو يكتشف الصيغة من الامتداد.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;
use NextPDF\Gotenberg\GotenbergConfig;

$config = new GotenbergConfig(
    apiUrl: 'https://gotenberg.example.com',
    timeout: 60,
    apiKey: $apiKey,
);

$bridge = new GotenbergBridge(
    config: $config,
    httpClient: $psrHttpClient,
    requestFactory: $psrRequestFactory,
    streamFactory: $psrStreamFactory,
    responseFactory: $psrResponseFactory,
);

$result = $bridge->convertFile('/path/to/report.docx');

\file_put_contents('/path/to/report.pdf', $result->pdfData);

ما يفعله: يتحقق من عنوان ⁨URL⁩ والمسار والحجم واسم الملف؛ ويرسل طلبًا واحدًا متعدد الأجزاء؛ ثم يكتب بايتات ⁨PDF⁩ المُعادة إلى القرص.

تحويل بايتات في الذاكرة إلى ⁨PDF⁩

استخدم convertString() عندما تكون البايتات لديك بالفعل. ويُستخدم اسم الملف لاكتشاف الصيغة.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
$result = $bridge->convertString($xlsxBytes, 'spreadsheet.xlsx');

if (! $result->isValid()) {
    throw new \RuntimeException('Conversion did not return a valid PDF.');
}

ما يفعله: يكتشف xlsx من اسم الملف، ويحوّل البايتات، ويتأكد قبل استخدامها من أن النتيجة تبدأ بالتوقيع %PDF.

فحص جاهزية الخدمة قبل التحويل

تحكّم في بدء العمل عبر isAvailable(). فهو يتحقق من عنوان ⁨URL⁩ دون أي حركة مرور على الشبكة، ثم يرسل طلب HEAD واحدًا إلى /health.

<?php

declare(strict_types=1);

use NextPDF\Gotenberg\GotenbergBridge;

/** @var GotenbergBridge $bridge */
if (! $bridge->isAvailable()) {
    throw new \RuntimeException('Gotenberg is not reachable.');
}

ما يفعله: يُعيد false (ولا يطرح استثناءً أبدًا) إذا كان عنوان ⁨URL⁩ فارغًا أو غير ⁨HTTPS⁩ أو يشير إلى عنوان خاص، وكذلك عند حدوث أي خطأ في الشبكة، حتى تتمكن من الفشل المبكر قبل إرسال عملية تحويل.

الجسر

يغطي هذا الجدول واجهة الجسر. استخدمه عند إنشاء GotenbergBridge أو عند استدعاء طرائق التحويل والجاهزية الخاصة به.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح أو يفشل بـ	ملاحظات
`new GotenbergBridge(GotenbergConfig $config, ClientInterface $httpClient, RequestFactoryInterface $requestFactory, StreamFactoryInterface $streamFactory, ?LoggerInterface $logger = null, ?HtmlSecurityPolicyInterface $htmlSecurityPolicy = null, ?ResponseFactoryInterface $responseFactory = null)`	الإعداد، وعميل ⁨PSR-18⁩، ومصانع ⁨PSR-17⁩، ومسجّل اختياري، وسياسة ⁨HTML⁩ اختيارية، ومصنع استجابة اختياري.	يستخدم `DefaultHtmlSecurityPolicy` عند عدم تزويده بسياسة.	`GotenbergBridge`	أخطاء توصيل الحاوية.	يتيح مصنع الاستجابة استخدام نقل ⁨cURL⁩ المثبَّت عندما يكون التثبيت مطلوبًا.
`GotenbergBridge::convertFile(string $filePath)`	مسار نظام الملفات إلى مستند ⁨Office.⁩	يستخدم امتداد الملف لاكتشاف الصيغة.	`GotenbergConvertResult`	`GotenbergConvertException`، `RuntimeException`، `ValueError` للصيغة غير المدعومة.	يحلّ المسار الحقيقي ويتحقق من قابلية القراءة والحجم واسم الملف.
`GotenbergBridge::convertString(string $content, string $fileName)`	البايتات الخام واسم الملف الأصلي.	يستخدم امتداد اسم الملف لاكتشاف الصيغة.	`GotenbergConvertResult`	مثل `convertFile`.	استخدمه عندما يمتلك تطبيقك بايتات الملف بالفعل.
`GotenbergBridge::isAvailable()`	لا شيء.	يرسل ⁨HEAD⁩ إلى `/health` عندما يكون الإعداد صالحًا.	`bool`	يُعيد `false` عند حدوث أخطاء.	إشارة جاهزية فقط.
`GotenbergBridge::getHtmlSecurityPolicy()`	لا شيء.	يُعيد سياسة طبقة التحليل المُعدَّة.	`HtmlSecurityPolicyInterface`	لا شيء متوقع.	يكمّل سياسة الأمان على مستوى النقل.

الإعداد والحمولات

يغطي هذا الجدول كائنات القيمة التي تنشئها مباشرةً: واصف الخدمة GotenbergConfig وحاملا الطلب والاستجابة GotenbergConvertPayload/GotenbergConvertResult. استخدمها عندما تحتاج إلى تحكّم أدق مما توفّره نقطتا الدخول للتحويل.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح أو يفشل بـ	ملاحظات
`new GotenbergConfig(string $apiUrl = '', int $timeout = 30, int $maxFileSize = 52428800, string $apiKey = '', array $pinnedPublicKeys = [], array $backupPublicKeys = [])`	عنوان ⁨URL⁩ لواجهة ⁨API⁩، والمهلة، والحجم الأقصى للملف، والرمز المميز من نوع ⁨bearer⁩، ومجموعات التثبيت.	عنوان ⁨URL⁩ الفارغ غير صالح؛ والحجم الأقصى الافتراضي هو 50 ⁨MiB.⁩	`GotenbergConfig`	لا شيء متوقع.	أبقِ مفتاح ⁨API⁩ سريًا.
`GotenbergConfig::fromArray(array $config)`	`api_url`، `timeout`، `max_file_size`، `api_key`، ومصفوفات التثبيت.	تستخدم القيم الاختيارية المفقودة الإعدادات الافتراضية للباني.	`GotenbergConfig`	لا شيء متوقع.	تتجاهل قوائم السلاسل النصية القيم غير النصية.
`GotenbergConfig::isValid()`	لا شيء.	صالح عندما يكون عنوان ⁨URL⁩ لواجهة ⁨API⁩ غير فارغ.	`bool`	لا شيء متوقع.	يُتحقَّق من أمان عنوان ⁨URL⁩ قبل أي عملية على الشبكة.
`GotenbergConfig::allPublicKeyPins()`	لا شيء.	يجمع بين التثبيتات الأساسية والاحتياطية.	`list<string>`	لا شيء متوقع.	القائمة الفارغة تعطّل التثبيت.
`new GotenbergConvertPayload(string $fileName, string $fileContent, OfficeFormat $format, bool $landscape = false, string $nativePageRanges = '')`	اسم الملف، والبايتات، والصيغة، وعلَم الاتجاه، ونطاقات الصفحات.	عمودي؛ كل الصفحات.	`GotenbergConvertPayload`	لا شيء متوقع.	تُحوَّل الحمولة إلى بيانات نموذج متعددة الأجزاء.
`GotenbergConvertPayload::toMultipartBody(string $boundary)`	حدّ متعدد الأجزاء.	يتضمّن حقل نطاق الصفحات فقط عندما يكون غير فارغ.	`string`	لا شيء متوقع.	يولّد الجسر الحدّ.
`GotenbergConvertPayload::contentType(string $boundary)`	حدّ متعدد الأجزاء.	يستخدم `multipart/form-data`.	`string`	لا شيء متوقع.	أرفقه باعتباره `Content-Type` للطلب.
`new GotenbergConvertResult(string $pdfData, OfficeFormat $sourceFormat, float $renderTimeMs = 0.0)`	بايتات ⁨PDF⁩ بعد التحويل، وصيغة المصدر، ومدة العرض الاختيارية.	تكون مدة العرض `0.0` عندما لا تُقاس.	`GotenbergConvertResult`	لا شيء متوقع.	تُعاد بواسطة `GotenbergResponseParser::parse()`.
`GotenbergConvertResult::isValid()`	لا شيء.	صالح عندما تكون بايتات ⁨PDF⁩ المُحوَّلة غير فارغة وتبدو كبيانات ⁨PDF.⁩	`bool`	لا شيء متوقع.	تحقّق قبل حفظ النتيجة أو بثّها.
`GotenbergConvertResult::size()`	لا شيء.	يحسب عدد بايتات ⁨PDF⁩ المُحوَّلة.	`int`	لا شيء متوقع.	استخدمه للحصص والقياس عن بُعد وحدود الاستجابة.

صيغ ⁨Office⁩

يغطي هذا الجدول تعداد OfficeFormat. استخدمه لربط امتداد بصيغة، أو قراءة نوع ⁨MIME⁩ الخاص بالرفع، أو التحقق من الصيغ الست المدعومة.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح أو يفشل بـ	ملاحظات
`OfficeFormat::fromExtension(string $ext)`	امتداد الملف مع نقطة بادئة أو دونها.	يطابق دون حساسية لحالة الأحرف.	`OfficeFormat`	`ValueError` للامتداد غير المدعوم.	القيم المدعومة: `docx`، `xlsx`، `pptx`، `odt`، `ods`، `odp`.
`OfficeFormat::mimeType()`	لا شيء.	يربط حالة التعداد بنوع ⁨MIME⁩ الخاص بالرفع.	`string`	لا شيء متوقع.	يُستخدم في جزء الملف متعدد الأجزاء.
`OfficeFormat::extension()`	لا شيء.	يُعيد القيمة المسنِدة.	`string`	لا شيء متوقع.	مفيد في التشخيص وأسماء الملفات.

الأمان والتحليل والنقل

يغطي هذا الجدول الآليات الداخلية التي يشغّلها الجسر نيابةً عنك. استخدمه فقط عند كتابة نقل مخصص، أو إجراء استدعاء مخصص لبروتوكول نقل النص التشعبي (⁨HTTP⁩) لا يزال يحتاج إلى تحليل الحزمة، أو فحص سلوك الأمان والتثبيت منخفض المستوى.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يطرح أو يفشل بـ	ملاحظات
`GotenbergSecurityPolicy::validateApiUrl(string $url)`	عنوان ⁨URL⁩ الأساسي لواجهة ⁨API.⁩	يحلّل الوجهة ويتحقق منها قبل أي عملية على الشبكة.	`array`	`RuntimeException` لعناوين ⁨URL⁩ غير الآمنة أو غير الصالحة.	يُبعد أخطاء نقاط النهاية من نوع تزييف الطلبات من جانب الخادم (⁨SSRF⁩) عن شيفرة التحويل.
`GotenbergSecurityPolicy::assertPinsStillValid(string $host, array $pinnedIps)`	المضيف وقائمة بروتوكول الإنترنت (⁨IP⁩) المثبَّتة.	يتحقق من توقّعات تثبيت نظام أسماء النطاقات (⁨DNS⁩).	`void`	`RuntimeException` عندما تكون التثبيتات قديمة أو غير صالحة.	استخدمه في عمليات النشر المثبَّتة والتشخيص التشغيلي.
`GotenbergSecurityPolicy::validateFileSize(int $size, int $maxSize)`	الحجم الفعلي والحد الأقصى المُعدّ.	يقبل الملفات التي تساوي الحد المُعدّ أو تقلّ عنه.	`void`	`RuntimeException` عندما يكون الملف أكبر من اللازم.	افرضه قبل إنشاء الطلب.
`GotenbergSecurityPolicy::validateFileName(string $name)`	اسم الملف الأصلي.	يرفض أشكال أسماء الملفات غير الآمنة أو غير المدعومة.	`void`	`RuntimeException` للأسماء غير الصالحة.	يمنع أسماء الملفات المتعددة الأجزاء المُشوَّهة.
`GotenbergResponseParser::parse(ResponseInterface $response, OfficeFormat $format)`	استجابة ⁨PSR-7⁩ وصيغة ⁨Office⁩ المتوقعة.	يستخرج بايتات ⁨PDF⁩ المُحوَّلة من استجابة ناجحة.	`GotenbergConvertResult`	`GotenbergConvertException` للاستجابات الفاشلة أو مخرجات ⁨PDF⁩ غير الصالحة.	المحلّل المركزي لتحويل الملفات والسلاسل النصية.
`new PinnedCurlTransport(ResponseFactoryInterface $responseFactory, StreamFactoryInterface $streamFactory, array $pinnedIps = [], array $pinnedPublicKeys = [], int $timeoutSeconds = 30)`	مصانع ⁨PSR-17⁩، وعناوين ⁨IP⁩ المثبَّتة، والمفاتيح العامة المثبَّتة، والمهلة.	بلا تثبيتات ومهلة 30 ثانية.	`PinnedCurlTransport`	لا شيء متوقع.	استخدمه فقط عندما يكون التثبيت على مستوى ⁨cURL⁩ مطلوبًا.
`PinnedCurlTransport::sendRequest(RequestInterface $request)`	طلب ⁨PSR-7.⁩	يرسل عبر ⁨cURL⁩ مع المهلة المُعدَّة وضوابط التثبيت.	`ResponseInterface`	`GotenbergConvertException` عند فشل ⁨cURL/⁩النقل.	استخدمه عندما لا يمكن إسناد التثبيت إلى عميل ⁨HTTP⁩ آخر.
`PinnedCurlTransport::buildCurlOptions(RequestInterface $request, string $host, int $port)`	الطلب والمضيف والمنفذ.	يبني مصفوفة خيارات ⁨cURL⁩ التي يستخدمها `sendRequest()`.	`array`	أخطاء في الطلب غير الصالح أو إعداد التثبيت.	تشخيص منخفض المستوى وخطّاف اختبار.

ملاحظات التطوير

تعامل مع ⁨Gotenberg⁩ باعتباره حدًّا لخدمة خارجية. اضبط المهلة والحجم وعنوان ⁨URL⁩ وسياسة التثبيت بعناية.
يقرأ convertFile() الملف بأكمله إلى الذاكرة قبل إنشاء الطلب.
سجّل بيانات وصفية مثل اسم الملف وطول المحتوى، وليس محتويات الملف.