# RESOURCE  /v2/articles

# Article Resource Management

این بخش شامل ۵ اندپوینت استاندارد برای مدیریت کامل مقالات (Articles) می‌باشد.   
ویژگی‌های کلیدی این کنترلر شامل **فیلترینگ پیشرفته** در لیست‌گیری (بر اساس دسته‌بندی، تگ و مکان) و **مدیریت روابط متا تگ‌ها** (PageMetatags) هنگام ساخت و ویرایش است.

<div class="api-docs" id="bkmrk-">  ---

</div>## 1. List Articles (Index)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Farticles-me"><div class="endpoint-info"><div>**URL:** `/v2/articles`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** ArticleController@index</div></div></div>### پارامترهای فیلترینگ (Query Params)

<div class="api-docs" id="bkmrk-parameter-type-descr"><div class="table-wrapper"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>categories</td><td>string (JSON)</td><td>آرایه‌ای از دسته‌بندی‌ها به صورت رشته JSON.   
مثال: `["tech", "news"]`  
از منطق `orWhereJsonContains` استفاده می‌کند.</td></tr><tr><td>tags</td><td>string (JSON)</td><td>آرایه‌ای از تگ‌ها به صورت رشته JSON.   
مثال: `["laravel", "api"]`</td></tr><tr><td>place</td><td>mixed</td><td>شناسه (ID) یا نام مستعار (Slug) یک مکان.  
**منطق خاص:** ابتدا ID مکان را از جدول `articles_places` پیدا می‌کند، سپس دسته‌بندی‌های مرتبط را از `articles_categories` می‌یابد و مقالات را بر اساس ستون `places` فیلتر می‌کند.</td></tr><tr><td>sortById</td><td>boolean</td><td>اگر ارسال شود، ترتیب `DESC` (نزولی) بر اساس ID اعمال می‌شود. در غیر این صورت پیش‌فرض `ASC` است.</td></tr><tr><td>limit</td><td>integer</td><td>محدودیت تعداد رکوردها قبل از صفحه‌بندی (توجه: نتیجه نهایی همچنان Paginate شده است).</td></tr></tbody></table>

</div></div>### مثال پاسخ (Response)

```json
{
  "status": true,
  "time": 1715008000,
  "data": [
    { "id": 10, "title": "...", "views": 150, ... } // ArticleResource Object
  ],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  }
}
```

<div class="api-docs" id="bkmrk--1"><div dir="ltr"></div>  ---

</div>## 2. Create Article (Store)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Farticles-me-1"><div class="endpoint-info"><div>**URL:** `/v2/articles`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** ArticleController@store</div></div></div>یک مقاله جدید ایجاد می‌کند. همزمان اگر آرایه `metatags` ارسال شود، رکوردهای مربوطه در جدول `page_metatags` ساخته می‌شوند.   
فیلد `operator` به صورت خودکار از توکن کاربر احراز هویت شده برداشته می‌شود.

### بدنه درخواست (Body Parameters)

<div class="api-docs" id="bkmrk-field-type-descripti"><div class="table-wrapper"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>title</td><td>string</td><td>(الزامی) عنوان مقاله</td></tr><tr><td>slug</td><td>string</td><td>(الزامی) آدرس یکتا</td></tr><tr><td>branch</td><td>integer</td><td>(الزامی) شناسه شعبه</td></tr><tr><td>categories</td><td>array</td><td>لیست دسته‌بندی‌ها (در دیتابیس JSON می‌شود)</td></tr><tr><td>tags</td><td>array</td><td>لیست تگ‌ها (در دیتابیس JSON می‌شود)</td></tr><tr><td>sub\_title</td><td>string</td><td>عنوان فرعی</td></tr><tr><td>body</td><td>text</td><td>متن اصلی مقاله</td></tr><tr><td>summary</td><td>text</td><td>خلاصه مقاله</td></tr><tr><td>thumbnail</td><td>string</td><td>آدرس تصویر شاخص</td></tr><tr><td>published\_at</td><td>datetime</td><td>تاریخ انتشار (پیش‌فرض: زمان حال)</td></tr><tr><td>score</td><td>integer</td><td>امتیاز مقاله</td></tr><tr><td>metatags</td><td>array\[obj\]</td><td>لیست متا تگ‌ها برای سئو. ساختار هر آبجکت:   
`{ "key": "description", "value": "text..." }`</td></tr></tbody></table>

</div>  ---

</div>## 3. Show Article (Show)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Farticles%2F%7Bi"><div class="endpoint-info"><div>**URL:** `/v2/articles/{id}`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** ArticleController@show</div></div></div>جزئیات کامل یک مقاله را برمی‌گرداند. از Route Model Binding لاراول استفاده می‌کند (اگر پیدا نشود ۴۰۴ می‌دهد).

<div class="api-docs" id="bkmrk--2">  ---

</div>## 4. Update Article

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Farticles%2F%7Bi-1"><div class="endpoint-info"><div>**URL:** `/v2/articles/{id}`</div><div>**Method:** <span class="method-put">PUT/PATCH</span></div><div>**Controller:** ArticleController@update</div></div></div>اطلاعات مقاله را ویرایش می‌کند.   
**منطق هوشمند متاتگ‌ها:** در آرایه `metatags`، اگر آیتمی دارای `id` باشد، آن رکورد در دیتابیس **آپدیت** می‌شود. اگر فاقد ID باشد، به عنوان یک متاتگ **جدید** برای این مقاله ایجاد می‌شود.

<div class="api-docs" id="bkmrk-start-update-%E2%86%93-updat"><div class="flowchart"><div class="flow-item">Start Update</div><div class="flow-arrow">↓</div><div class="flow-item-process">Update Main Article Fields</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Has Metatags?</div><div class="flow-arrow">↓ Yes</div><div style="border: 1px dashed #999; padding: 10px; background: #f9f9f9; border-radius: 8px;">**Loop through items:**   
  
<span style="font-size: 12px;">Item has "id"?</span>   
<span style="color: green;">YES</span> → `PageMetatag::find($id)->update()`   
<span style="color: orange;">NO</span> → `PageMetatag::create()`</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return { status: true }</div></div>  ---

</div>## 5. Delete Article

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Farticles%2F%7Bi-2"><div class="endpoint-info"><div>**URL:** `/v2/articles/{id}`</div><div>**Method:** <span class="method-delete">DELETE</span></div><div>**Controller:** ArticleController@destroy</div></div></div>مقاله را حذف می‌کند. متاتگ‌های وابسته (اگر Cascade در دیتابیس تنظیم شده باشد) حذف می‌شوند، در غیر این صورت فقط رکورد مقاله حذف می‌شود.

```json
{
    "status": true,
    "time": 1715009000
}
```