فصل اول: شروع ماجراجویی با Nextcloud: کشف معماری و امکانات¶

هدف فصل¶

به دنیای Nextcloud خوش آمدید! در این فصل، شما را با قلب تپنده این پلتفرم قدرتمند اوپن‌سورس آشنا می‌کنیم. Nextcloud یک فضای ابری ماژولار است که به شما اجازه می‌دهد از ذخیره‌سازی فایل تا اپلیکیشن‌های سفارشی را در دست بگیرید. هدف ما این است که شما ساختار کد Nextcloud نسخه ۳۲.۰.۰ (آخرین نسخه پایدار تا اکتبر ۲۰۲۵) را بشناسید، اپلیکیشن‌های خودتان را بسازید و با استفاده از API‌ها و هوک‌ها، آن را به یک ابزار منحصربه‌فرد تبدیل کنید. نسخه ۳۲.۰.۰ با پشتیبانی از PHP ۸.۲ و رابط کاربری مدرن Vue 3 (با @nextcloud/vue@8)، دنیایی از امکانات جدید را به شما معرفی می‌کند!

چه یک توسعه‌دهنده تازه‌کار باشید یا حرفه‌ای، این فصل شما را با ابزارهای لازم برای شروع ماجراجویی‌تان مجهز می‌کند. آماده‌اید که کد بزنید و Nextcloud را به سبک خودتان بازسازی کنید؟ بیایید شروع کنیم!

۱.۱ ساختار کد: نقشه گنج Nextcloud¶

Nextcloud مانند یک شهر هوشمند ماژولار طراحی شده است که هر بخش آن وظیفه‌ای خاص دارد. با شناخت این ساختار، می‌توانید به‌راحتی بخش‌های موردنظرتان را سفارشی کنید. در ادامه، نقشه این شهر را بررسی می‌کنیم:

• lib/: مغز متفکر Nextcloud! این پوشه شامل کلاس‌های اصلی PHP مانند UserManager (برای مدیریت کاربران) و AppFramework (برای توسعه اپلیکیشن‌ها) است. اینجا جایی است که منطق اصلی پلتفرم زندگی می‌کند.
• apps/: محله اپلیکیشن‌ها! اپ‌های پیش‌فرض مثل Files، Calendar و Talk و همچنین اپ‌های سفارشی شما در این پوشه قرار می‌گیرند.
• core/: قلب ظاهری Nextcloud! فایل‌های JavaScript، CSS و تم‌های پیش‌فرض در این بخش هستند که رابط کاربری را شکل می‌دهند.
• themes/: گالری هنر Nextcloud! تم‌های سفارشی برای تغییر ظاهر و حس‌وحال پلتفرم اینجا تعریف می‌شوند.
• config/: مرکز فرماندهی! فایل config.php تنظیمات اصلی سرور را در خود جای داده است.

نکته طلایی: نسخه ۳۲.۰.۰ (منتشرشده در سپتامبر ۲۰۲۵) از PHP ۸.۲ پشتیبانی می‌کند و با @nextcloud/vue@8، کامپوننت‌های Vue 3 را برای رابط کاربری مدرن‌تر جایگزین Vue 2 کرده است. این یعنی سرعت بیشتر، کد تمیزتر و امکانات پیشرفته‌تر!

دستورات برای کاوش ساختار:

cd server
tree -L 2
# خروجی نمونه:
# ├── apps        # اپلیکیشن‌های شما و پیش‌فرض
# ├── config      # تنظیمات سرور
# ├── core        # فایل‌های JS/CSS
# ├── lib         # کلاس‌های اصلی PHP
# ├── themes      # تم‌های سفارشی

چالش شروع: به پوشه core/ سر بزنید و فایل core/js/js.js را باز کنید. این فایل نقطه شروع اسکریپت‌های اصلی Nextcloud است!

۱.۲ توسعه اپلیکیشن جدید: ساخت اولین افزونه خودتان¶

حالا که نقشه را در دست دارید، وقت آن است که اولین اپلیکیشن Nextcloud خودتان را بسازید! ساخت اپلیکیشن در Nextcloud مثل ساختن یک خانه جدید در این شهر است: ساده، اما پر از امکانات. بیایید قدم‌به‌قدم یک اپلیکیشن نمونه بسازیم که یک پیام ساده نمایش دهد.

۱.۲.۱ ایجاد ساختار اپلیکیشن¶

1. ساخت پایه اپلیکیشن:

   mkdir -p apps/myapp

1. تعریف مشخصات اپلیکیشن: فایل appinfo/info.xml:

   <?xml version="1.0"?>
   <info>
       <id>myapp</id>
       <name>اپلیکیشن سفارشی من</name>
       <version>1.0.0</version>
       <summary>یک اپلیکیشن ساده برای شروع</summary>
       <description>این اپلیکیشن به شما امکان می‌دهد قابلیت‌های سفارشی به Nextcloud اضافه کنید.</description>
       <licence>agpl</licence>
       <author>شما، توسعه‌دهنده خلاق!</author>
       <dependencies>
           <nextcloud min-version="32" max-version="32"/>
       </dependencies>
   </info>

1. ایجاد نقطه ورود اپلیکیشن: فایل appinfo/app.php:

   <?php
   namespace OCA\MyApp;

   use OCP\AppFramework\App;
   use OCP\IContainer;

   class MyApp extends App {
       public function __construct(array $urlParams = []) {
           parent::__construct('myapp', $urlParams);
           $container = $this->getContainer();

           // افزودن اسکریپت و استایل هنگام بارگذاری فایل‌ها
           $container->getServer()->getEventDispatcher()->addListener(
               'OCA\Files::loadAdditionalScripts',
               function () {
                   \OCP\Util::addScript('myapp', 'main');
                   \OCP\Util::addStyle('myapp', 'style');
               }
           );
       }
   }

1. افزودن JavaScript: فایل js/main.js:

   console.log('اپلیکیشن سفارشی شما با موفقیت بارگذاری شد! 🚀');

1. افزودن استایل CSS: فایل css/style.css:

   .myapp-container {
       background-color: #e6f3ff;
       padding: 15px;
       border-radius: 5px;
       box-shadow: 0 2px 4px rgba(0,0,0,0.1);
       font-family: 'Vazir', sans-serif;
   }

1. فعال‌سازی اپلیکیشن:

   cd server
   php occ app:enable myapp

۱.۲.۲ تست اپلیکیشن¶

• سرور محلی را اجرا کنید:

  cd server
  php -S localhost:8080

• مرورگر را باز کنید و به http://localhost:8080 بروید.
• در بخش تنظیمات اپلیکیشن‌ها (Apps)، مطمئن شوید که اپلیکیشن سفارشی من فعال است.
• کنسول مرورگر (F12) را باز کنید و بررسی کنید که پیام اپلیکیشن سفارشی شما با موفقیت بارگذاری شد! 🚀 نمایش داده شود.

نکته حرفه‌ای: اگر پیام را ندیدید، مطمئن شوید که پوشه apps/myapp در مسیر درست قرار دارد و config.php تنظیمات دیباگ را فعال کرده است ('debug' => true).

۱.۳ API و هوک‌ها: قدرت ارتباط با Nextcloud¶

Nextcloud مثل یک ارکستر است و API‌ها و هوک‌ها به شما اجازه می‌دهند ساز خودتان را به این ارکستر اضافه کنید! با استفاده از OCP\AppFramework می‌توانید API‌های RESTful بسازید و با هوک‌ها به رویدادهای سیستم واکنش نشان دهید.

۱.۳.۱ ساخت یک API ساده¶

1. ایجاد کنترلر: فایل apps/myapp/lib/Controller/PageController.php:

   <?php
   namespace OCA\MyApp\Controller;

   use OCP\AppFramework\Controller;
   use OCP\AppFramework\Http\JSONResponse;
   use OCP\IRequest;

   class PageController extends Controller {
       public function __construct($appName, IRequest $request) {
           parent::__construct($appName, $request);
       }

       /**
        * @NoAdminRequired
        * @NoCSRFRequired
        * @return JSONResponse
        */
       public function index() {
           return new JSONResponse(['message' => 'سلام دنیا! 🌍']);
       }
   }

1. ثبت مسیر API: فایل appinfo/routes.php:

   <?php
   return [
       'routes' => [
           [
               'name' => 'page#index',
               'url' => '/api/index',
               'verb' => 'GET'
           ]
       ]
   ];

1. تست API:

   curl http://localhost:8080/index.php/apps/myapp/api/index
   # خروجی: {"message":"سلام دنیا! 🌍"}

۱.۳.۲ استفاده از هوک‌ها¶

فایل: appinfo/app.php:

$container->getServer()->getEventDispatcher()->addListener(
    'OCA\Files::fileUpdate',
    function ($event) {
        \OC::$server->getLogger()->info('فایل به‌روزرسانی شد: ' . $event->getPath());
    }
);

تست هوک:

• یک فایل را آپلود یا ویرایش کنید.
• لاگ را بررسی کنید:

  cat data/nextcloud.log

هشدار امنیتی: استفاده از @NoAdminRequired و @NoCSRFRequired را در تولید محدود کنید.

۱.۴ نکات تکمیلی و چالش‌ها¶

• چرا Nextcloud؟ این پلتفرم اوپن‌سورس با انعطاف‌پذیری بالا امکان ادغام با Active Directory و اپلیکیشن‌های موبایل را فراهم می‌کند.
• چالش: یک دکمه به رابط کاربری فایل‌ها اضافه کنید که پیام "خوش آمدید!" نمایش دهد.
• منابع:
• docs.nextcloud.com
• help.nextcloud.com