پرش به مطلب اصلی

محیط اجرای PHP

▶
ویدیو: استقرار اپلیکیشن PHP روی ابرکلیکplaceholder — ویدیو را اینجا جایگزین کنید

ابرکلیک از استقرار و اجرای پروژه‌های PHP پشتیبانی می‌کند. بیلدپکِ ابری به‌صورت خودکار پروژه را تحلیل کرده، فریم‌ورک‌هایی مانند Laravel یا Symfony را شناسایی کرده و برنامه شما را بر روی وب‌سرور مستقر می‌کند.

تشخیص خودکار پروژه (Detection)​

ابرکلیک پروژه‌های نوشته‌شده با زبان PHP را از روی وجود یکی از فایل‌های زیر در ریشه پروژه شناسایی می‌کند:

  • فایل composer.json (سیستم مدیریت پکیج‌های PHP Composer).
  • فایل index.php (نقطه ورود برنامه شما).

در صورت یافت شدن هر یک از این فایل‌ها، پروژه به‌طور خودکار تحت پلتفرم PHP بیلد می‌شود.

نسخه‌های پشتیبانی‌شده​

  • PHP 8.3 (نسخه پیش‌فرض)
  • PHP 8.2
  • PHP 8.1
  • PHP 8.0

شما می‌توانید نسخه PHP خود را در فایل composer.json مشخص کنید:

{
  "require": {
    "php": "^8.3"
  }
}

همچنین سیستم از فایل .php-version در ریشه پروژه نیز پشتیبانی می‌کند:

8.3

وب‌سرور (Web Server)​

به‌صورت پیش‌فرض، وب‌سرور قدرتمند Apache 2.4 به همراه ماژول‌های فعال mod_rewrite و mod_php برای سرویس‌دهی پروژه‌ها نصب و فعال می‌شود.

در صورتی که مایلید از وب‌سرور Nginx استفاده کنید، تنظیمات زیر را به فایل composer.json اضافه کنید:

{
  "extra": {
    "abrclick": {
      "web-server": "nginx"
    }
  }
}

نصب وابستگی‌ها (Dependencies)​

تمام وابستگی‌ها و پکیج‌های معرفی‌شده در فایل پروژه شما با ابزار کامپوزر در مرحله بیلدپک دانلود و نصب خواهند شد:

composer install --no-dev --optimize-autoloader

توصیه مهم: همواره فایل composer.lock را به گیت خود متعهد (Commit) کنید تا کدهای کامپایل‌شده کپی دقیق وابستگی‌های محلی شما باشند.

تنظیمات پیشرفته و شخصی‌سازی (Configuration)​

۱. متغیرهای محیطی (Environment Variables)​

متغیرهای خود را از طریق داشبورد وب یا دستور زیر در CLI تنظیم کنید:

abrclick env:set MY_VAR=value

در کدهای PHP خود به راحتی به آن‌ها دسترسی خواهید داشت:

$value = getenv('MY_VAR');
// یا استفاده از سوپرگلوبال
$value = $_ENV['MY_VAR'];

۲. پوشه ریشه وب (Document Root)​

به‌طور پیش‌فرض، ریشه وب بر روی پوشه public/ تنظیم می‌شود (مناسب برای فریم‌ورک‌های استاندارد). اگر ساختار پروژه شما متفاوت است، می‌توانید متغیر محیطی DOCUMENT_ROOT را از طریق داشبورد یا CLI تنظیم کنید:

abrclick env set DOCUMENT_ROOT=www

مثال برای فریم‌ورک‌های معروف:

  • لاراول (Laravel): پوشه public/ (به‌طور پیش‌فرض تنظیم است)
  • سیمفونی (Symfony): پوشه public/ (به‌طور پیش‌فرض تنظیم است)
  • وردپرس (WordPress): ریشه اصلی پروژه ./

۳. ماژول‌ها و اکستنشن‌های PHP Extensions​

پکیج‌های مورد نیاز خود را در فیلد require فایل composer.json بنویسید تا سیستم به‌طور خودکار آن‌ها را لود کند:

{
  "require": {
    "ext-pdo": "*",
    "ext-json": "*",
    "ext-curl": "*"
  }
}

اکستنشن‌های رایج زیر به‌صورت پیش‌فرض بر روی تمام سرورها نصب و فعال هستند:

  • pdo / pdo_pgsql / pdo_mysql
  • json
  • curl
  • openssl
  • mbstring
  • xml
  • gd

۴. تنظیمات سفارشی در php.ini​

شما می‌توانید تنظیمات حساس php.ini را بدون نیاز به دسترسی سرور، مستقیماً از طریق تعریف متغیرهای محیطی تغییر دهید:

abrclick env:set PHP_MEMORY_LIMIT=256M
abrclick env:set PHP_UPLOAD_MAX_FILESIZE=50M
abrclick env:set PHP_POST_MAX_SIZE=50M

همچنین می‌توانید فایلی به نام php.ini در ریشه پروژه خود بسازید و کانفیگ‌ها را در آن ثبت کنید:

memory_limit = 256M
upload_max_filesize = 50M
post_max_size = 50M

اتصال پایگاه داده و رشته‌های اتصال​

اتصال به دیتابیس PostgreSQL مدیریت‌شده​

پایگاه داده خود را از داشبورد به اپلیکیشن لینک کنید، سپس با متغیر DATABASE_URL به‌صورت مستقیم به آن متصل شوید:

$pdo = new PDO($_ENV['DATABASE_URL']);

مشاهده لاگ‌ها​

برای بررسی لاگ‌های برنامه PHP خود، از دستور زیر استفاده کنید:

abrclick logs <app>

این دستور لاگ‌های زمان اجرا را به‌صورت زنده نمایش می‌دهد. لاگ‌های بیلد نیز در حین اجرای abrclick deploy استریم می‌شوند.

همچنین می‌توانید لاگ‌ها را از داشبورد مشاهده کنید: وارد صفحه برنامه شوید و بر روی تب لاگ‌ها کلیک کنید.

نکته فنی

در برنامه‌های سالم PHP که از Apache استفاده می‌کنند، پیام‌هایی مانند Apache/2.4.x configured -- resuming normal operations را در لاگ خواهید دید. اگر این پیام ظاهر نشود، احتمالاً مشکلی در کانفیگ یا راه‌اندازی وب‌سرور وجود دارد.

برای اطلاعات بیشتر، راهنمای کامل لاگ‌ها را مطالعه کنید.

رفع خطاهای رایج​

اپ بالا نمی‌آید / خطای ۵۰۳​

علت: برنامه شما به درستی شروع نشده است. این می‌تواند به دلیل خطای سینتکس در کدهای PHP، مشکل در مسیر ریشه وب (document root) یا عدم وجود فایل index.php باشد.

راه‌حل: مطمئن شوید فایل index.php در پوشه مناسب (معمولاً public/) قرار دارد. اگر ساختار پروژه شما متفاوت است، متغیر محیطی DOCUMENT_ROOT را تنظیم کنید:

abrclick env set DOCUMENT_ROOT=www

composer.json یا composer.lock پیدا نشد / بیلد ناموفق​

علت: وابستگی‌های پروژه شما به درستی مشخص نشده‌اند یا فایل composer.lock وجود ندارد. در محیط بیلد ابرکلیک، اینترنت عمومی در دسترس نیست و آینه داخلی به‌صورت خودکار استفاده می‌شود.

راه‌حل: مطمئن شوید هم composer.json و هم composer.lock را کامیت کرده‌اید:

composer install
git add composer.json composer.lock

مشکل mod_rewrite / URL های زیبا کار نمی‌کنند​

علت: ماژول mod_rewrite فعال نیست یا فایل .htaccess به درستی پیکربندی نشده است. این برای فریم‌ورک‌هایی مانند Laravel که از URL rewriting استفاده می‌کنند ضروری است.

راه‌حل: به‌طور پیش‌فرض، ماژول mod_rewrite در وب‌سرور Apache ابرکلیک فعال است. مطمئن شوید فایل .htaccess در پوشه public/ وجود دارد و قوانین rewrite مناسب را دارد. برای Laravel:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

خطای اکستنشن PHP پیدا نشد​

علت: پروژه شما به اکستنشن PHP خاصی نیاز دارد که نصب نیست.

راه‌حل: اکستنشن مورد نیاز خود را در بخش require فایل composer.json اضافه کنید:

{
  "require": {
    "ext-pdo": "*",
    "ext-gd": "*"
  }
}

اکستنشن‌های رایج مانند pdo, json, curl, mbstring و gd به‌طور پیش‌فرض نصب هستند.

OOMKilled / خطای حافظه​

علت: برنامه شما از حافظه بیشتر از محدودیت تعریف‌شده (پیش‌فرض ۵۱۲Mi) استفاده کرده است.

راه‌حل: محدودیت حافظه برنامه را از طریق داشبورد یا تغییر پلن افزایش دهید. همچنین می‌توانید memory_limit را در تنظیمات PHP کاهش دهید تا از خطاهای OOM جلوگیری کنید:

abrclick env set PHP_MEMORY_LIMIT=256M