Docs home / HareAdmin Handbook

Addon drivers

Business modules must not hardcode a vendor name. Providers register through AddonDriver channels; consumers call generic APIs and hooks only.

Channels

  • editor — rich text (class="editor")
  • sms — SMS OTP / notice
  • payment — checkout gateways
  • oauth — third-party login
  • storage — upload disks
  • ai — LLM chat (hub: llmhub)
  • map — maps / geocode (hub: maphub)

Active driver for sms / payment / editor / storage / ai / map: site.driver_{channel} or yetuadmin.driver_{channel}; otherwise the highest priority wins. OAuth is multi-active — every configured provider can show a button.

SMS

  • Hooks: sms_send, sms_notice, sms_check. Inactive drivers return null so only the active channel sends.
  • Register in configInit / appInit: AddonDriver::register('sms', $name, …)
  • Official store plugins: alisms, tencentsms, huaweisms, twilio, vonage
  • Register captcha: when yetuadmin.user_register_captcha = mobile, the site must have an SMS plugin enabled. The register page shows an Addon-store install hint if missing; api/sms/send returns the same error.
  • UI must distinguish email vs mobile codes (labels and send buttons). Do not reuse a generic “Captcha” label when the destination matters.
  • Config mode=dryrun validates locally without calling the remote SMS API. Switch to live with real credentials for production.

Payment

  • Register: AddonDriver::register('payment', $name, ['gateway' => Gateway::class, 'class' => Client::class])
  • Gateway implements app\common\library\payment\GatewayInterface. Consumer sites use payment\Manager; the store API uses GatewayManager.
  • Official store plugins: alipay, wechatpay, douyinpay, stripe, paypal
  • Notify URL pattern: /addons/{name}/notify/index. On success the platform fires hook payment_notify_success.
  • mode=dryrun returns a fake pay URL without remote calls.

OAuth (third-party login)

  • Channel oauth. Login and register templates call hook user_third_login.
  • Important: hook() returns an array of listener results. Always implode before output:
    $html = hook('user_third_login');
    echo is_array($html) ? implode('', array_map('strval', $html)) : (string) $html;
    Never echo hook('user_third_login') directly (PHP “Array to string conversion”).
  • Core: app\common\library\oauth\Manager and table yt_user_third (created by Manager::ensureTable() on install / enable).
  • Providers include: wechatlogin, qqlogin, weibologin, douyinlogin, googlelogin, applelogin, facebooklogin, xlogin, tiktoklogin, microsoftlogin
  • Flow: /addons/{name}/index/connect → provider → callback. Dry-run skips the remote redirect.
  • Plugin Settings: set Mode + provider credentials only (WeChat: AppID / AppSecret; QQ: APP ID / APP Key; …). The readonly Callback path is for copy/paste.
  • Provider console (required for Live): register the full URL {your-site-domain}{Callback path} with exact match (no .html suffix). Example: https://example.com/addons/wechatlogin/index/callback.
  • Mode=dryrun needs no real keys and verifies install / bind / cookie login locally. Switch to live only after credentials and console callback are ready.

AI (LLM Hub)

  • Models: one table row = one concrete vendor model id (pin versions in production). Optional family groups versions (e.g. gpt-4o); version_label is display-only; is_latest marks the preferred row when callers pass family. Filter with capability (e.g. vision).
  • Providers: OpenAI, Anthropic, Google AI, DeepSeek, Qwen, DashScope, Doubao, Kimi, GLM, Muse, Hunyuan, MiniMax, Qianfan, xAI, custom OpenAI-compatible.
  • Channel ai. Official hub addon: llmhub (store category AI).
  • Business code calls new \addons\llmhub\library\Client() → chat(['messages'=>…, 'tag'=>'translation', 'model'=>'…']). Do not hardcode OpenAI / Anthropic SDKs in apps.
  • Providers inside the hub: OpenAI, Anthropic, Google AI, DeepSeek, DashScope (Qwen), custom OpenAI-compatible. API keys live in addon Settings; models are rows with optional tags (empty = general).
  • Routing modes: always default / match by tag / caller picks model code (route_mode).
  • Multi-locale: lang/zh|en|es.php; model titles via ContentLang; chat may hint the current UI language unless lang=>false.
  • Prefer site setting site.driver_ai / yetuadmin.driver_ai when multiple AI hubs exist later.

Map (Map Hub)

  • Channel map. Official hub addon: maphub (store category Maps).
  • UI: class="map-picker" → Form.events.mappicker → YetuDrivers.bindMap → module map/maphub.
  • Providers: Google Maps, Mapbox, Amap, Baidu Map — pick one in Settings (no region lock).
  • Map / geocode language: follow UI language by default, or a fixed BCP-47 code (lang_mode / fixed_lang).
  • PHP: Client::geocode() / reverse(); admin AJAX maphub.api/geocode & reverse.

Language packs (required)

Every new addon must ship lang/zh.php, lang/en.php, and lang/es.php with the same keys. English phrasing is the source of truth. Other locales may follow later. Prefer shared platform keys (Operate success, Are you sure?, …).

Do / Don't

  • Do: one provider → one addon; use official HTTP / signing APIs; document notify URLs and dry-run in Settings tips.
  • Do: write for a global audience — name the provider/product, do not frame product copy by market or geography.
  • Do: add only necessary integration tips to this handbook when shipping drivers — not every commit note.
  • Don't: hardcode Alipay / Twilio / Google class names in business modules.
  • Don't: add page-specific admin JS/CSS files for driver config (use addon Settings).