تبدیل فایلهای DOCX به Markdown یک نیاز مکرر برای توسعهدهندگانی است که میخواهند مستنداتی سبک و سازگار با کنترل نسخه داشته باشند. Aspose.HTML Cloud SDK for PHP به شما امکان میدهد این تبدیل DOCX به MD را در PHP تنها با چند فراخوانی API انجام دهید. در این راهنما، تنظیمات مورد نیاز را مرور میکنیم، یک مثال کامل کد را نشان میدهیم و نحوه تنظیم دقیق خروجی برای تولید Markdown تمیز را توضیح میدهیم. همچنین خواهید دید که چگونه میتوان همان تبدیل را از طریق REST با استفاده از cURL برای سناریوهای ابری‑محور فراخوانی کرد.
Steps to DOCX to MD Conversion in PHP
- دریافت توکن دسترسی - از شناسه مشتری (client ID) و رمز عبور (secret) Aspose Cloud خود برای درخواست یک توکن دسترسی موقت از طریق نقطه انتهایی OAuth استفاده کنید.
- بارگذاری DOCX منبع - فایل را یا با استفاده از متد
UploadFileبه ذخیرهسازی Aspose بارگذاری کنید یا یک URL قابل دسترسی عمومی ارائه دهید. - ایجاد درخواست تبدیل - یک شیء
ConvertDocumentRequestبسازید، مقدارformatرا بهmdتنظیم کنید و بهصورت اختیاری گزینههای تبدیل را مشخص کنید. - اجرای تبدیل - متد
ConvertDocumentاز کلاس HtmlApi را فراخوانی کنید (مرجع API). - بارگیری Markdown - فایل
.mdحاصل را از جریان پاسخ دریافت کنید و بهصورت محلی ذخیره کنید یا برای پردازشهای بعدی استفاده کنید.
اسکریپت تبدیل DOCX به MD در PHP - مثال کامل کد
اسکریپت زیر یک تبدیل کامل انتها به انتها را با استفاده از Aspose.HTML Cloud SDK for PHP نشان میدهد.
<?php
require 'vendor/autoload.php';
use Aspose\HTML\Cloud\Sdk\Api\HtmlApi;
use Aspose\HTML\Cloud\Sdk\Configuration;
use Aspose\HTML\Cloud\Sdk\Model\ConvertDocumentRequest;
// ---------------------------------------------------------------------
// 1. Configure SDK with your client credentials
// ---------------------------------------------------------------------
$config = new Configuration();
$config->setClientId('YOUR_CLIENT_ID');
$config->setClientSecret('YOUR_CLIENT_SECRET');
// ---------------------------------------------------------------------
// 2. Initialize HtmlApi
// ---------------------------------------------------------------------
$htmlApi = new HtmlApi($config);
// ---------------------------------------------------------------------
// 3. Prepare conversion request
// ---------------------------------------------------------------------
$inputFile = 'sample.docx'; // Path to your DOCX file
$outputFormat = 'md'; // Target format
$request = new ConvertDocumentRequest($inputFile, $outputFormat);
// ---------------------------------------------------------------------
// 4. Perform conversion
// ---------------------------------------------------------------------
try {
$response = $htmlApi->convertDocument($request);
$markdown = $response->getBody()->getContents();
// -----------------------------------------------------------------
// 5. Save the Markdown output
// -----------------------------------------------------------------
file_put_contents('output.md', $markdown);
echo "Conversion successful. Markdown saved to output.md\n";
} catch (Exception $e) {
echo "Error during conversion: " . $e->getMessage() . "\n";
}
?>
توجه: این مثال کد عملکرد اصلی را نشان میدهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید مسیرهای فایل (
sample.docx,output.md) بهروز شدهاند، تأیید کنید تمام وابستگیهای مورد نیاز بهدرستی نصب شدهاند و بهطور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک با تیم پشتیبانی تماس بگیرید.
تبدیل DOCX به Markdown مبتنی بر ابر از طریق REST API با استفاده از cURL
میتوانید بدون استفاده از SDK، همان نتیجه را با فراخوانی مستقیم نقاط انتهایی REST سرویس Aspose.HTML Cloud به دست آورید.
- احراز هویت و دریافت توکن دسترسی
curl -X POST "https://api.aspose.cloud/connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
- بارگذاری فایل منبع (اگر از URL عمومی استفاده نمیکنید)
curl -X PUT "https://api.aspose.cloud/v4.0/html/storage/file/sample.docx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
--data-binary "@sample.docx"
- اجرای تبدیل
curl -X POST "https://api.aspose.cloud/v4.0/html/convert/md" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"inputPath":"sample.docx","outputPath":"output.md"}'
- دانلود خروجی Markdown
curl -X GET "https://api.aspose.cloud/v4.0/html/storage/file/output.md" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" -o output.md
برای جزئیات بیشتر در مورد پارامترهای درخواست، به مستندات رسمی API مراجعه کنید.
نصب و راهاندازی در PHP
- نصب SDK از طریق Composer
composer require aspose-html-cloud - دانلود آخرین نسخه اگر نصب دستی را ترجیح میدهید: دانلود بسته.
- پیکربندی اعتبارنامههای خود - مقدار
client_idوclient_secretرا در شیءConfigurationتنظیم کنید (مثال کد را ببینید). - تأیید نصب با اجرای یک اسکریپت ساده
php -r "echo phpinfo();"برای اطمینان از کارکرد autoloader. - اعمال یک لایسنس موقت برای تست: به صفحه لایسنس موقت مراجعه کنید و دستورالعملها را دنبال کنید.
تبدیل DOCX به MD در PHP با Aspose.HTML
Aspose.HTML یک موتور تبدیل مبتنی بر ابر فراهم میکند که تمام مشخصات DOCX را درک میکند، از جمله طرحهای پیچیده، جداول و تصاویر جاسازیشده. با ارسال سند به سرویس، پردازش را به یک بکاند مقیاسپذیر واگذار میکنید و نیازی به کتابخانههای سنگین محلی ندارید.
Aspose.HTML ویژگیها
- رندر با دقت بالا – هنگام تبدیل به Markdown، استایلها، جداول و تصاویر را حفظ میکند.
- قالبهای خروجی متعدد – از HTML، PDF، PNG، JPEG و Markdown (MD) پشتیبانی میکند.
- معماری بومی ابری – بهصورت خودکار مقیاس مییابد و از پشت فایروالها از طریق HTTPS کار میکند.
- API گسترده – کنترل دقیق بر گزینههای تبدیل را از طریق REST و SDKها فراهم میکند.
پیکربندی گزینههای تبدیل برای خروجی بهینه Markdown
درخواست ConvertDocumentRequest به شما امکان تنظیم دقیق نتیجه Markdown را میدهد.
| Option | Description |
|---|---|
preserveTableStructure |
سطرها و ستونهای جدول را دستنخورده نگه دارد (پیشفرض: true). |
includeImages |
تصاویر را بهصورت رشتههای base64 جاسازی میکند یا بهعنوان فایلهای خارجی نگه میدارد. |
headingLevelOffset |
سطوح عنوان را برای مطابقت با سلسلهمراتب مستندات شما تنظیم میکند. |
removeStyles |
استایلهای درونخطی CSS را حذف میکند تا خروجی متنی پاکتری داشته باشید. |
قبل از فراخوانی convertDocument، این گزینهها را از طریق مدل درخواست تنظیم کنید.
بهینهسازی عملکرد تبدیل
- پردازش دستهای چندین فایل - چندین فایل DOCX را بارگذاری کنید و در یک فراخوانی API تبدیل کنید تا تاخیر رفتوآمد کاهش یابد.
- استفاده مجدد از توکنهای دسترسی - توکنها برای یک ساعت معتبر هستند؛ به جای درخواست توکن جدید برای هر فایل، آنها را کش کنید.
- فشردهسازی فایلهای ورودی - بارهای کوچکتر سرعت بارگذاری و پردازش را افزایش میدهند.
- درخواستهای همزمان - برای بارهای کاری بزرگ، درخواستهای تبدیل همزمان را با رعایت محدودیتهای نرخ سرویس ارسال کنید.
بهترین روشها برای تبدیل DOCX به MD
- اعتبارسنجی ورودی - اطمینان حاصل کنید که فایل DOCX قبل از بارگذاری خراب نشده باشد.
- پاکسازی Markdown - پس از تبدیل، یک linter اجرا کنید تا هر گونه ناهماهنگی قالببندی را برطرف کنید.
- ذخیرهسازی ایمن نتایج - فایلهای
.mdتولید شده را در مخزنی تحت کنترل نسخه ذخیره کنید. - نظارت بر استفاده از API - تعداد درخواستها و زمانهای پاسخ را از طریق داشبورد Aspose Cloud پیگیری کنید تا از محدود شدن جلوگیری شود.
نتیجهگیری
با بهرهگیری از Aspose.HTML Cloud SDK for PHP، میتوانید بهصورت قابل اعتماد فایلهای DOCX را به Markdown تبدیل کنید با حداقل کد. این SDK چیدمانهای پیچیده را مدیریت میکند، قالببندیهای ضروری را حفظ میکند و گزینههای قابل تنظیمی برای خروجی MD تمیز ارائه میدهد. برای استقرارهای تولیدی، یک لایسنس کامل را از فروشگاه Aspose خریداری کنید؛ یک لایسنس موقت برای ارزیابی از طریق صفحه لایسنس موقت در دسترس است. نمونه کد ارائهشده را در جریان کار خود یکپارچه کنید و از تبدیل یکپارچه اسناد در برنامههای PHP خود لذت ببرید.
سوالات متداول
چگونه میتوانم فایلهای بزرگ DOCX را در حین تبدیل مدیریت کنم؟
فایل را ابتدا در ذخیرهسازی Aspose بارگذاری کنید، سپس تبدیل را آغاز کنید. سرویس ابری بهصورت کارآمد فایلهای بزرگ را پردازش میکند و میتوانید پیشرفت را از طریق API نظارت کنید.
آیا میتوانم چندین فایل DOCX را در یک درخواست به Markdown تبدیل کنم؟
بله. از نقطه انتهای تبدیل دستهای استفاده کنید یا با SDK فایلها را بهصورت حلقهای پردازش کنید و برای بهبود عملکرد، توکن دسترسی یکسان را مجدداً استفاده کنید.
اگر نیاز داشته باشم تصاویر را بهجای فایلهای خارجی بهصورت درونخط نگه دارم چه میشود؟
گزینه includeImages را به true تنظیم کنید و حالت embedImages را انتخاب کنید. SDK تصاویر را بهعنوان رشتههای base64 مستقیماً در Markdown جاسازی میکند.
آیا SDK با PHP 8.x سازگار است؟
Aspose.HTML Cloud SDK برای PHP از PHP 7.4 و بالاتر، از جمله PHP 8.x پشتیبانی میکند. اطمینان حاصل کنید که افزونههای مورد نیاز (cURL، JSON) فعال باشند.