آموزش ساخت Extension یا افزونه برای phpBB

پنج‌شنبه 25 دی 1399, 10:47 am

با سلام سعی میکنیم در این تاپیک ساخت افزونه برای سیستم phpBB را به شما آموزش دهیم.

این تاپیک به مرور به روز رسانی خواهد شد.

لطفا اگه سوالی داشتید به صورت تاپیک جداگانه مطرح کنید تا ساختار این تاپیک بهم نریزه.

پنج‌شنبه 25 دی 1399, 10:48 am

شنبه 30 مرداد 1400, 12:53 pm

آموزش بخش اول - شروع

معرفی:
به بخش توسعه و ساخت افزونه های phpBB خوش آمدید.
این آموزش بر اساس یک افزونه آزمایشی که در اینجا قرار دارد توضیح داده میشود. https://github.com/phpbb/phpbb-ext-acme-demo

این افزونه بسیاری از ویژگی های افزونه های رایج را داراست ، مانند صفحه کنترلر جلویی front-controller ، همچنین استفاده از event های هسته و قالب ، تغییر پایگاه داده برای مهاجرت ها Migration و همچنین تنظیمات و کنترل افزونه از طریق مرکز مدیریت انجمن Admin Control Panel

این آموزش بر پایه اصول اولیه ساخت افزونه بیان میشود.

توجه:
ابزاری به نام phpBB Skeleton Extension وجود دارد که به صورت خودکار فایل ها مورد نیاز برای ساخت یک افزونه را برای شما ایجاد میکند. که میتوانید از اینجا پیدایش کنید:
https://area51.phpbb.com/docs/dev/maste ... nsion.html

پوشه افزونه
همه افزونه ها بایستی در پوشه ext روت phpBB قرار بگیرند. ساختار پوشه افزونه به این شکل بایستی باشد مثلا: vendor/extname

بنابراین آدرس درست پوشه افزونه به این شکل خواهد بود در نهایت: phpBB/ext/vendor/extname
خب در اینجا vendor میتواند نام کاربری و یا هر هر نام دیگری از مشخصات شما یا گروه شما باشد و extname نام افزونه شماست. مثلا ما در افزونه تاریخ شمسی پوشه این افزونه را بدین صورت قرار دادیم. meis2m/shamsidate

ما در این آموزش از acme به عنوان نام و demo به عنوان نام افزونه استفاده کردیم.

نکته مهم:
هر دو نام vendor و extname باید با حروف کوچک شروع شود. و میتوانید از اعداد هم استفاده کنید. حروف بزرگ ، دش و سایر کاراکترها مجاز نیست.

مثلا چنین نامی مشکل ندارد iamuser1/iamanextension

Composer JSON
همه افزونه ها بایستی دارای یک فایل متا دیتا به نام composer.json باشند. که این فایل وظیفه شناسایی افزونه شما را دارد.
این فایل شامل اطلاعات اولیه افزونه شما و پیشنیازها و وابستگی هاست. این فایل بر اساس فرمت JSON نوشته میشود و باید در پوشه اصلی افزونه قرار گیرد. به عنوان مثال مسیر درستش بدین صورت است:
phpBB/ext/acme/demo/composer.json

اطلاعات موجود در این فایل در بخش مدیریت افزونه ها در مرکز مدیریت انجمن مورد استفاده قرار میگیرد. نمونه ای از یک فایل composer.json

کد: انتخاب همه

{
"name": "acme/demo",
"type": "phpbb-extension",
"description": "Acme Demo Extension for phpBB 3.2",
"homepage": "https://github.com/phpbb/phpbb-ext-acme-demo",
"version": "0.1.0",
"time": "2013-11-05",
"keywords": ["phpbb", "extension", "acme", "demo"],
"license": "GPL-2.0-only",
"authors": [
{
"name": "Nickv",
"email": "nickvergessen@localhost",
"homepage": "https://github.com/nickvergessen/",
"role": "Lead Developer"
}
],
"require": {
"php": ">=5.4.0",
"composer/installers": "~1.0"
},
"require-dev": {
"phpbb/epv": "dev-master"
},
"extra": {
"display-name": "Acme Demo Extension",
"soft-require": {
"phpbb/phpbb": "~3.2"
}
}
}

توجه:
نکته مهمی که وجود دارد این است که در آخرین خط هر آرایه مطلقا نباید از کاما , استفاده کنید.

حالا به فیلدهای مورد نظر میپردازیم.

name - نام پوشه و نام افزونه که با / از هم جدا میشوند - فیلد ضروری
type - نوع پکیج که باید همیشه phpbb-extension باشد - فیلد ضروری
description - توضیحات افزونه شما - فیلد ضروری

homepage - آدرس افزونه شما یا سایت شما و یا آدرس گیت هاب افزونه شما - غیر ضروری

version - نسخه افزونه شما که باید از نوع X.Y.Z باشد مثلا 2.0.1 و میتواند از پسوندهای -dev, -patch, -alpha, -beta or -RC نیز استفاده کند - ضروری

time - تاریخ انتشار افزونه شما - غیر ضروری
keywords - کلمات کلیدی افزونه - غیر ضروری

license - لایسنس افزونه شما که باید همانند phpBB از GPL-2.0 باشد - ضروری

authors - نویسنده که میتواند نام خودتان باشد - ضروری
require - پیش نیازهای افزونه شما - ضروری

require-dev - پیش نیاز های توسعه افزونه - غیر ضروری

extra - مجموعه ای از داده های اضافی برای افزونه شما - ضروری

حالا توضیحات اضافه تر برای بعضی بخش ها

authors
name - نام نویسنده - ضروری
email- ایمیل نویسنده - غیر ضروری
homepage- آدرس صفحه نویسنده - غیر ضروری
role - نقش نویسنده - مثلا توسعه دهنده ، اسپانسر یا مترجم و ... - غیر ضروری

require
لیست متغیر های پیش نیاز در اینجا موجوده
https://packagist.org/

php - حداقل پیش نیاز ورژن php برای افزونه ها در phpBB 3.2 ورژن 5.4.0 است پس مقدارش رو >= 5.4.0 در نظر میگیریم.
composer/installers - توصیه شده توسط phpBB. هنگام نصب از طریق Composer ، برنامه های افزودنی در محل صحیح phpBB نصب می شوند.

require-dev
در بخش اختیاری افزونه ، شما میتوانید لیست وابستگی ها و نیازهای افزونه را وارد کنید. افزونه Acme Demo که جهت آموزش قرار دارد توسط ابزار https://packagist.org/packages/phpbb/epv که توسط تیم توسعه افزونه طراحی شده است ، تایید شده است. که در هنگام تست Travis CI مورد تست قرار میگیرد. که بعدا توضیحات آن داده میشود.

extra
این بخش میتواند حاوی هرگونه داده دلخواه با توجه به composer باشد. با این حال phpBB توضیه به این دو میکند.

display-name - نام افزونه شما
soft-require - حداقل نسخه phpBB برای نصب افزونه که 3.1 می باشد. که با ~ شروع شده و "phpbb/phpbb": "~3.2" قرار میگیرد.

توضیجات کامل composer.json در سایت اصلی خودش موجود است
https://getcomposer.org/doc/04-schema.md

اطلاعات بیشتر در مورد پکیج ها
https://getcomposer.org/doc/articles/ve ... onstraints

بخش اول تمام

شنبه 6 شهریور 1400, 4:24 pm

آموزش بخش دوم - مفاهیم کلیدی

قبل از اینکه بریم برای ساخت یک افزونه باید برخی مفاهیم و شیوه های کلیدی را یاد بگیریم.

تزریق وابستگی یا Dependency Injection
بخش بزرگی از کدهای phpBB از 3.1 بر اساس یک مکانیسم اساسی ، یعنی تزریق وابستگی است.

مفهوم تزریق وابستگی:
https://ditty.ir/posts/dependency-injection/5jVm5

هدف آن این است که شما نگران مدیریت وابستگی ها و اجزای آن نباشید مثل لایه های پایگاه داده ، سیستم کش و یا اجزاء کاربر فعلی. همچنین ابزاریست برای توقف استفاده از متغیر های گلوبال ( جهانی )

از زمان عرضه phpBB 3.1 تا به امروز ما از سیستم Symfony DependencyInjection استفاده میکنیم. تمام سرویس ها Service در phpBB به صورت قالب YAML و در فایل /config/services.yml پوشه افزونه قرار میگیرد. افزونه ها میتوانند از خدمات تعریف شده phpBB استفاده کنند و یا از کلاس تعریف شده شما استفاده کنند که در اینجا config/services.yml قرار میگیرند.

برای ارائه یک مثال ساده از تزریق وابستگی در عمل ، بیایید به روش سازنده کلاس کنترل کننده افزونه مثال ما در فایل main.php نگاهی بیندازیم.

کد: انتخاب همه

public function __construct(\phpbb\config\config $config, \phpbb\controller\helper $helper, \phpbb\template\template $template, \phpbb\user $user)
{
$this->config = $config;
$this->helper = $helper;
$this->template = $template;
$this->user = $user;
}

همانطور که مشاهده میکنید ما به اجزای $config و $helper و $template و $user نیاز داریم. برای اینکه این سرویس ها به صورت خودکار توسط تزریق وابستگی حل شوند ، افزونه demo ما باید کلاس های کنترلر را در این فایل config/services.yml تعریف کند.

کد: انتخاب همه

services:
acme.demo.controller:
class: acme\demo\controller\main
arguments:
- '@config'
- '@controller.helper'
- '@template'
- '@user'

نکته:
توجه داشته باشید که acme.demo.controller نام سرویس منحصر به فرد برای این کلاس است. افزونه باید پیشوند نام پوشه و نام افزونه را که در این مثال acme.demo را همراه داشته باشد ، این به خاطر عدم تداخل با افزونه های دیگر است که باید یکتا باشد.

این کلاس به راحتی از مسیر name-spaced پیدا میشود.

آرگومان ها arguments وابستگی های سرویس مورد نیاز کلاس هستند. مهم این است که ترتیب آرگومان ها باید با ترتیب پارامترهای تعریف متد __construct () مطابقت داشته باشد. هر آرگومانی هم باید با @ یا % شروع شود و بین تک کوتیشین قرار بگیرد ، از نسخه phpBB 3.2 به بعد لازم است این باشد.

بیشتر فایل های php یک افزونه باید مدل تزریق وابستگی با سرویس تعریف شده و کنترل ها و سیستم event را داشته باشند. موارد استثنا در این مورد شامل هر فایل ACP/MCP/UCP ، فایل های زبان و پرونده های مهاجرت migration (که در حال حاضر از sdsjl سرویس استفاده نمی کنند) است.

فایل های PHP
به عنوان بخشی از تغییر phpBB به سمت استفاده گسترده از جهت گیری شی ، توصیه می شود که توسعه دهندگان از کلاس ها برای سازماندهی داده ها در موارد مناسب استفاده کنند.

افزونه ها تشویق شده اند تا توابع مربوطه را در کلاسها و کلاسها را در فایلهای خود ذخیره کنند.

نام گزاری کلاس ها برای استحکام و ثبات افزونه ها بسیار حیاتی و مهم هستند. همه کلاسها باید بین نام ها فاصله space-name داشته باشند و یک کلاس مستقیم برای نگاشت نام مسیر داشته باشند. به عبارت دیگر ، نام فضای و نام کلاس باید شامل ساختار دایرکتوری باشد. مثلا:

کد: انتخاب همه

<?php

namespace acme\demo\controller;

class main
{
// do something
}

کد فوق با فاصله بالا برای یک فایل کلاس در مسیر مثلا acme/demo/controller/main.php خواهد بود. کلاسهای با فاصله توسط phpBB بارگیری خودکار می شوند ، بدین معنی که برای دسترسی به سایر کلاسها نیازی به ایجاد توابع accessor نیست.

نکته:
از نسخه phpBB 3.1 نیاز نیست انتهای فایل php خود را با ?> ببندین.

امنیت IN_PHPBB Security

فایل های PHP که فقط دارای کلاس هستند ، نیازی به استفاده از تست امنیتی IN_PHPBB ندارند. هرچند اگر فایل شما حاوی هرکدام از عملکردهای اجرایی مانند define() و include() و require() باشد بایستی از IN_PHPBB استفاده کنید مانند.

کد: انتخاب همه

<?php

if (!defined('IN_PHPBB'))
{
exit;
}

include('somefile.php');

function do_something ()
{
// do something
}

فایل های Template یا قالب

قالب بندی در phpBB3 تفاوتی با قالب بندی در phpBB 3.1 و بعد آن ندارد. با اینکه phpBB 3.1 از موتور Twig در قالب بندی خود استفاده میکند اما همچنان از سیستم قدیمی نیز پشتیبانی میکند. بنابر این از هر دو سیستم میتوانید استفاده کنید. اگر با سیستم Twig آشنا نیستید میتوانید از سیستم phpBB قدیمی در نسخه 3.0 استفاده کنید ولی پیشنهاد ما استفاده از سیستم جدید است.

هر افزونه ای میتواند شامل دو نوع فایل قالبی باشد: 1 - قالب کاستوم شده 2- سیستم Events & Listeners
هر فایل قالبی کاستوم بایستی یک نام منحصر به فرد داشته باشد مثلا نام افزونه و پوشه که تداخلی با سایر افزونه ها ایجاد نشود. به علاوه فایل html قالبی شما میتوانید فایل های css , javascript , image هم داشته باشید.

فایل های قالبی باید از ساختار phpBB پیروی کند. پوشه styles/ در افزونه شامل همه فایل های قالبی شماست. قالب پیشفرض phpbb در حال حاضر prosilver است که میتوانید فایل های قالبی html , css, image و ... را درون آن قرار دهید و این فایل ها در قالب هایی که قالب مادر آن پروسیلور هم نیز لود میشود.

چنانچه قالب خاصی دارید مثلا به نام Milk شما باید فایل های قالب را درون پوشه ای به نام Milk قرار دهید و یا اگثر میخواهید برای همه قالب ها فایل های قالبی شما لود شود میتوانید درون پوشه ای به نام all قرار دهید که در همه قالب ها لود شود.

فایل های قالبی برای مرکز مدیریت نیز در پوشه adm/style/ قرار میگیرد. دقیقا اینجا /adm/style

ساختار شبیه سازی شده فایل ها

کد: انتخاب همه

styles
├── all
│ ├── template
│ │ └── event
│ │ └── overall_header_head_append.html
│ └── theme
│ ├── css
│ │ └── acme_demo_main.css
│ └── images
│ └── acme_demo_image.png
├── prosilver
│ └── template
│ ├── acme_demo_body.html
│ └── event
│ └── overall_header_navigation_append.html
└── subsilver2
└── template
├── acme_demo_body.html
└── event
└── overall_header_navigation_append.html

هشدار:
از نام های عمومی قالب ها برای فایل ها خودداری نمایید مثلا فایل overal_header.html به صورت پیشفرض در قالب اصلی انجمن وجود دارد پس نباید از آن برای نام فایل خود استفاده کنید که در این صورت نادیده گرفته میشود. فایلهای قالب اصلی برای افزونه های منتشر شده عمومی توصیه نمی شود زیرا ممکن است با سایر افزونه ها در تعارض باشد.

Twig Template Syntax
http://twig.sensiolabs.org/

phpBB Template Syntax
https://wiki.phpbb.com/Tutorial.Templat ... x_elements

فایل های زبان

فایل های زبانی برای افزونه ها باید با ساختار phpBB هماهنگ باشد. فایل ها زبانی که به صورت php تعریف میشوند بایستی در پوشه language افزونه شما قرار گیرند. ضمنا بایستی برای هر زبان از iso آن استفاده کنید مثلا فایل زبانی شما برای فارسی زبانان باید در این پوشه باشد language/fa

فایل زبانی ما مثلا بدین صورت است:

کد: انتخاب همه

<?php

if (!defined('IN_PHPBB'))
{
exit;
}

if (empty($lang) || !is_array($lang))
{
$lang = [];
}

$lang = array_merge($lang, [
'DEMO_PAGE' => 'Demo',
'DEMO_HELLO' => 'Hello %s!',
'DEMO_GOODBYE' => 'Goodbye %s!',
'ACP_DEMO_TITLE' => 'Demo Module',
'ACP_DEMO' => 'Settings',
'ACP_DEMO_GOODBYE' => 'Should say goodbye?',
'ACP_DEMO_SETTING_SAVED' => 'Settings have been saved successfully!',
]);

بارگیری فایل های زبانی در افزونه بسیار ساده است که باید از متد add_lang() در شی $language استفاده شود. پس به دو آرگومان نیاز دارد ، یکی نام فایل زبان (یا مجموعه ای از نام فایل های زبان) و دیگری vendor/package افزونه.

به دلایل عملکرد بهتر ، ترجیح داده می شود از روش زیر برای بارگذاری فایل های زبان در هر نقطه از اجرای کدهای افزونه تان استفاده کنید ، جایی که کلیدهای زبان مورد نیاز است . با این حال ، اگر بارگیری کلیدهای زبانی افزونه به صورت جهانی ضروری باشد ، بنابراین ، باید از رویداد PHP core.user_setup استفاده شود.

فایل های زبانی میتواند هر نامی داشته باشد اما اگر مثلا با پسوند permissions_ یا info_acp_ آغاز شود میتواند به صورت خودکار مثلا در مرکز مدیریت بخش دسترسی ها و ... لود شود و نیاز به اضافه کردن کدهای روش قبلی نیست.

فایل های css و جاوا اسکریپت

این نوع فایل ها میتوانند در هر جایی از پوشه افزونه شما ذخیره شوند. اما به صورت معمول در پوشه style افزونه قرار میگیرند. اضافه کردن اسکریپت ها میتواند توسط سینتکس phpBB با {% INCLUDECSS %} و {% INCLUDEJS %} نیز انجام شود.

مثلا:

کد: انتخاب همه

{% INCLUDECSS '@vendor_extname/scriptname.css' %}

{% INCLUDEJS '@vendor_extname/scriptname.js' %}

تگ INCLUDECSS به صورت خودکار وارد پوشه theme قالب مثلا all در پوشه style افزونه شما میشود. و به صورت خودکار تگ <link> را بین تگ های <head> قالب کاربر برای لود فایل css شما میکند.

همچنین تگ INCLUDEJS نیز به صورت خودکار وارد پوشه template قالب میشود. به صورت خودکار تگ <script> در قالب کاربر برای لود فایل های جاوا اسکریپت میکند.

این دو تگ را میتوانید در هر قالب یا event مورد نظر استفاده کنید.

هنگام استفاده از کتابخانه های جاوا اسکریپت/CSS و فریم ورک هایی مانند jQuery-UI یا Font Awesome ، می توان با استفاده از یک راه حل ساده که توسط تیم افزونه های phpBB تأیید شده است ، از همپوشانی یا اورلب منابع بین برنامه های افزودنی کاسته شود.

با استفاده از تگ {٪ DEFINE٪} میتوانید آزمایش کنید که آیا اسکریپتی که افزونه شما می خواهد شامل شود از قبل تعریف شده است و اگر نه ، اسکریپت خود را وارد کرده و اسکریپت را تعریف کنید. مثلا:

کد: انتخاب همه

{% if not $INCLUDED_JQUERYUIJS %}
{% INCLUDEJS '@vendor_extname/jquery-ui.js' %}
{% DEFINE $INCLUDED_JQUERYUIJS = true %}
{% endif %}

برخی از قالب های تعریف شده برای استفاده در کتابخانه های رایج بدین صورت است که نام متغیر را بعد از نام فایل کتابخانه نامگذاری کنید ، به عنوان مثال highslide.js به HIGHSLIDEJS تبدیل می شود.

کد: انتخاب همه


HighSlide JS: $INCLUDED_HIGHSLIDEJS

Font Awesome CSS: $INCLUDED_FONTAWESOMECSS

ColorBox JS: $INCLUDED_COLORBOXJS

ColPick JS: $INCLUDED_COLPICKJS

MoTools JS: $INCLUDED_MOTOOLSJS

Dojo JS: $INCLUDED_DOJOJS

Angular JS: $INCLUDED_ANGULARJS