MODX

https://docs.modx.pro/
Admin
MODX is an open-source content management system with comprehensive documentation for components,...
Tokens:877,899
Snippets:9,051
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and Run Development Server

Source: https://docs.modx.pro/guide/getting-started

Commands to install dependencies and start the local development server for previewing changes.

```shell
pnpm install
pnpm dev
```

```shell
npm install
npm run dev
```

```shell
yarn install
yarn dev
```

--------------------------------

### Example URLs for MobileDetect GET parameters

Source: https://docs.modx.pro/components/mobiledetect/settings

Demonstrates how to use GET parameters to force a specific device mode or reset detection.

```text
https://example.com/page?browser=mobile
https://example.com/page?browser=detect
```

--------------------------------

### Install MS3 Demo Data from source

Source: https://docs.modx.pro/components/ms3demodata

Commands to clone the repository and navigate to the directory for development installation.

```bash
git clone https://github.com/biz87/ms3DemoData.git
cd ms3demodata
```

--------------------------------

### Use useApi Examples

Source: https://docs.modx.pro/components/vuetools/composables

Demonstrates performing GET, POST, PUT, and DELETE requests using the MODX connector API.

```javascript
const { get, post, put, delete: del } = useApi()

// GET запрос
const users = await get('security/user/getlist', { limit: 20 })

// POST запрос
const result = await post('security/user/create', {
  username: 'newuser',
  email: 'user@example.com'
})

// PUT запрос
await put('security/user/update', {
  id: 1,
  fullname: 'New Name'
})

// DELETE запрос
await del('security/user/remove', { id: 1 })
```

--------------------------------

### Install CLI Utilities

Source: https://docs.modx.pro/components/imageoptimizer/troubleshooting

Install necessary image processing binaries via Homebrew.

```bash
brew install webp libavif libheif imagemagick
```

--------------------------------

### Order Options JSON Examples

Source: https://docs.modx.pro/components/msfastorder/api

Examples of the options parameter structure for order creation.

```json
{"variant_id": 42}
```

```json
{"variant_id": 42, "options": {"color": "red", "size": "L"}}
```

```json
{"color": "red"}
```

--------------------------------

### Install and Build MiniShop3

Source: https://docs.modx.pro/components/minishop3/index

Commands to clone the repository, install PHP dependencies, build Vue widgets, and run the build script.

```bash
git clone https://github.com/modx-pro/MiniShop3.git
cd MiniShop3

# Установка PHP зависимостей
composer install

# Сборка Vue виджетов (требуется Node.js 18+)
cd vueManager
npm install
npm run build
cd ..

# Сборка и установка компонента
# Откройте _build/build.php в браузере или выполните:
php _build/build.php
```

--------------------------------

### CRON command example

Source: https://docs.modx.pro/components/msimportexport/msimportexport-1

Example of a standard CRON command for the import script.

```console
...... /core/components/msimportexport/cron.php 1> /dev/null 2>&1 &
```

--------------------------------

### Where Parameter Examples

Source: https://docs.modx.pro/components/simplefilters/snippets

Examples of using the &where parameter for filtering resources and MiniShop3 products.

```text
'where' => '{"new":"1"}'
```

```text
'where' => '{"price:>":"2000"}'
```

```text
'where' => '{"longtitle:like":"скидка"}'
```

--------------------------------

### API Routing Examples

Source: https://docs.modx.pro/components/reactions/api

Examples of how to access API endpoints using query parameters or PATH_INFO.

```http
GET  /assets/components/reactions/api.php?action=counts
GET  /assets/components/reactions/api.php/counts
POST /assets/components/reactions/api.php?action=react
GET  /assets/components/reactions/api.php?action=admin/types
```

--------------------------------

### Impex Configuration File Example

Source: https://docs.modx.pro/components/impex/configuration

A complete example of an Impex configuration file defining field mappings, default values, and import settings.

```php
<?php
$impex_config['content_row'] = [
    ['Категории', 5, 'categories'],
    ['Наименование', 'pagetitle', 'resource'],
    ['Артикул', 'article', 'ms'],
    ['Расширенный заголовок', 'longtitle', 'resource'],
    ['Краткое описание', 'introtext', 'resource'],
    ['Содержимое', 'content', 'resource'],
    ['Цена', 'price', 'ms'],
    ['Производитель', 'vendor', 'ms'],
    ['Новинка', 'new', 'ms'],
    ['Теги', 'tags', 'ms'],
    ['Цвет', 'color', 'ms'],
    ['Материал', 'material', 'msoption'],
    ['На складе', 1, 'tv'],
    ['Галерея', 'images/import/', 'msgallery'],
    ['Дополнительные категории', '', 'mscats'],
];

// значения по умолчанию при импорте или проверка при экспорте
$impex_config['content_default'] = [
    ['template', 2],
];

// класс товаров (msProduct / modResource)
$impex_config['resource_class'] = 'msProduct';

// класс категорий (msCategory / modResource / CollectionContainer)
$impex_config['category_class'] = 'msCategory';

// поле идентификации категории (если указывается напрямую, а не цепочкой)
$impex_config['category_id_field'] = '';

// по какому полю проверять соответствие товара при обновлении
$impex_config['chk_field'] = ['pagetitle', 'resource'];

// пропускать несуществующие ресурсы (только обновление, без создания)
$impex_config['skip_new'] = false;

// первая строка — названия полей
$impex_config['include_captions'] = true;

// разделители для MIGX-полей: между элементами, между полями внутри элемента
$impex_config['migx_separators'] = ['||', '--'];

// ресурсов за один проход; 0 — без ограничения
$impex_config['batch_import'] = 100;

// поле для генерации alias при импорте (пусто — alias только из файла)
$impex_config['alias_field'] = 'pagetitle';
```

--------------------------------

### pdoTools log output examples

Source: https://docs.modx.pro/components/pdotools/classes/pdotools

Example output logs showing cache misses and hits.

```text
0.0000281: pdoTools загружен
0.0004001: No cached data for key "default/e713939a1827e7934ff0242361c06b4b10c53d97"
0.0000079: Кэш не найден, генерируем данные
0.0581820: Saved data to cache "default/e713939a1827e7934ff0242361c06b4b10c53d97"
0.0000181: Данные сохранены в кэш
0.0586412: Total time
1 835 008: Memory usage
```

```text
0.0000310: pdoTools загружен
0.0007479: Retrieved data from cache "default/e713939a1827e7934ff0242361c06b4b10c53d97"
0.0000081: Данные загружены из кэша
0.0007918: Total time
1 572 864: Memory usage
```

--------------------------------

### Example product card template

Source: https://docs.modx.pro/components/msproductdiscounts

A complete example of a product card structure using Fenom syntax and MSProductDiscounts attributes.

```fenom
{'!msOptionsPrice.initialize' | snippet : []}

<div class="text-center text-md-left mb-2 mb-md-0">
  {if $_modx->resource.new?}
  <span class="badge badge-secondary badge-pill col-auto">{'ms2_frontend_new' | lexicon}</span>
  {/if}
  {if $_modx->resource.popular?}
  <span class="badge badge-secondary badge-pill col-auto">{'ms2_frontend_popular' | lexicon}</span>
  {/if}
  {if $_modx->resource.favorite?}
  <span class="badge badge-secondary badge-pill col-auto">{'ms2_frontend_favorite' | lexicon}</span>
  {/if}
</div>
<div id="msProduct" class="row align-items-center" itemtype="http://schema.org/Product" itemscope>
  <meta itemprop="name" content="{$_modx->resource.pagetitle}">
  <meta itemprop="description" content="{$_modx->resource.description ?: $_modx->resource.pagetitle}">
  <div class="col-12 col-md-6">
    {'!msGallery' | snippet : []}
  </div>
  <div class="col-12 col-md-6" itemtype="http://schema.org/AggregateOffer" itemprop="offers" itemscope data-mspd-observe>
    <meta itemprop="category" content="{$_modx->resource.parent | resource: 'pagetitle'}">
    <meta itemprop="offerCount" content="1">
    <meta itemprop="price" content="{$price | replace:' ':''}">
    <meta itemprop="lowPrice" content="{$price | replace:' ':''}">
    <meta itemprop="priceCurrency" content="RUR">

    <form class="form-horizontal ms2_form msoptionsprice-product" method="post" data-mspd-product="{$_modx->resource.id}">
      <input type="text" name="options[modification]" value="0" data-mspd-option>
      <h1 class="text-center text-md-left msoptionsprice-name msoptionsprice-[[*id]]">{$_modx->resource.pagetitle}</h1>
      <input type="hidden" name="id" value="{$_modx->resource.id}"/>
```

--------------------------------

### Configure mFilter URL Examples

Source: https://docs.modx.pro/components/mfilter/settings

Examples of how URL structures are generated based on different separator configurations.

```text
/catalog/brand--apple/color--red-or-blue/price--1000-5000/
```

```text
/catalog/brand_apple/color_red,blue/price_1000-5000/
```

--------------------------------

### Use usePermission Examples

Source: https://docs.modx.pro/components/vuetools/composables

Demonstrates checking for single, any, or all permissions.

```javascript
const { hasPermission, hasAnyPermission, hasAllPermissions } = usePermission()

// Проверить одно право
if (hasPermission('my_component_edit')) {
  // Пользователь может редактировать
}

// Проверить любое из прав
if (hasAnyPermission(['edit', 'save', 'delete'])) {
  // Пользователь имеет хотя бы одно право
}

// Проверить все права
if (hasAllPermissions(['view', 'edit'])) {
  // Пользователь имеет оба права
}
```

--------------------------------

### API Routing Example

Source: https://docs.modx.pro/components/bannerpro/development/rest-api

Example of how to structure a request URL using the route parameter.

```text
https://example.com/assets/components/bannerpro/api.php?route=/ads&limit=10
```

--------------------------------

### Example Template Chunk Configurations

Source: https://docs.modx.pro/components/pdotools/snippets/pdomenu

Examples of custom inline templates for parent rows and inner menu structures.

```text
@INLINE <li class="submenu_wrap [[+classnames]]"><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a>[[+wrapper]]</li>
```

```text
@INLINE <ul class="submenu [[+classnames]]">[[+wrapper]]</ul>
```

```text
@INLINE <li class="submenu_item [[+classnames]]"><a href="[[+link]]" [[+attributes]]>[[+menutitle]]</a>[[+wrapper]]</li>
```

--------------------------------

### Examples of Boosted Total Calculation

Source: https://docs.modx.pro/components/msviewcounter/integration

Practical examples showing how raw totals are transformed using specific multipliers, bases, and jitter values.

```text
boosted = floor(12 × 2) + 3 = 27
display = max(100, 27) = 100
```

```text
boosted = floor(80 × 2) + 2 = 162
display = max(100, 162) = 162
```

--------------------------------

### Examples of Boosted Online Calculation

Source: https://docs.modx.pro/components/msviewcounter/integration

Practical examples showing how raw online counts are transformed using specific bases and jitter values.

```text
display = max(2, 0 + 1) = 2
```

```text
display = max(2, 4) = 4
```

--------------------------------

### Initialize OptionService

Source: https://docs.modx.pro/components/minishop3/development/backend-api/product

Retrieve the main service for managing product options.

```php
$optionService = $modx->services->get('ms3_option_service');
```

--------------------------------

### Perform an autocomplete request

Source: https://docs.modx.pro/components/msearch/javascript-api

Example of a GET request to the suggest endpoint.

```http
GET /assets/components/msearch/api.php?route=/search/suggest&query=те&form=abc123def456
```

--------------------------------

### Minimal msReviews Setup

Source: https://docs.modx.pro/components/msreviews/frontend/product

The essential components required for basic functionality.

```fenom
{'!msReviewsLexiconScript' | snippet}
{'!msRatingSummary' | snippet : ['product_id' => $_modx->resource.id]}
{'!msReviews' | snippet : ['product_id' => $_modx->resource.id]}
{'!msReviewForm' | snippet : ['product_id' => $_modx->resource.id]}
{raw ('!msReviewSchema' | snippet : ['product_id' => $_modx->resource.id])}
```

```modx
[[!msReviewsLexiconScript]]
[[!msRatingSummary? &product_id=`[[*id]]`]]
[[!msReviews? &product_id=`[[*id]]`]]
[[!msReviewForm? &product_id=`[[*id]]`]]
[[!msReviewSchema? &product_id=`[[*id]]`]]
```

--------------------------------

### Perform a search request

Source: https://docs.modx.pro/components/msearch/javascript-api

Example of a GET request to the search endpoint with query parameters.

```http
GET /assets/components/msearch/api.php?route=/search&query=текст&offset=0&form=abc123def456
```

--------------------------------

### Full Integration Plugin Example

Source: https://docs.modx.pro/components/minishop3/development/events/msproducts

Demonstrates adding custom badges to products based on creation date and price comparison using multiple events.

```php
<?php
/**
 * Плагин: Бейджи товаров
 * События: msOnProductsLoad, msOnProductPrepare
 */

switch ($modx->event->name) {

    case 'msOnProductsLoad':
        // Проверяем параметр
        $usePackages = $scriptProperties['usePackages'] ?? [];
        if (!in_array('msBadges', $usePackages)) {
            return;
        }

        $rows = $scriptProperties['rows'];
        $weekAgo = strtotime('-7 days');

        // Определяем новинки (созданы за последние 7 дней)
        $newProducts = [];
        foreach ($rows as $row) {
            if (strtotime($row['createdon']) > $weekAgo) {
                $newProducts[$row['id']] = true;
            }
        }

        // Сохраняем для msOnProductPrepare
        $modx->eventData['msBadges'] = [
            'newProducts' => $newProducts,
        ];
        break;

    case 'msOnProductPrepare':
        $badgesData = $modx->eventData['msBadges'] ?? null;
        if ($badgesData === null) {
            return;
        }

        $productId = $scriptProperties['productId'];
        $row = $scriptProperties['row']; // читаем, не мутируем — для записи нужен returnedValues

        $badges = [];

        // Бейдж "Новинка"
        if (!empty($badgesData['newProducts'][$productId])) {
            $badges[] = [
                'type' => 'new',
                'label' => 'Новинка',
                'color' => '#28a745',
            ];
        }

        // Бейдж "Скидка" (если есть старая цена)
        if (!empty($row['old_price']) && $row['old_price'] > $row['price']) {
            $discount = round((($row['old_price'] - $row['price']) / $row['old_price']) * 100);
            $badges[] = [
                'type' => 'sale',
                'label' => "-{$discount}%",
                'color' => '#dc3545',
            ];
        }

        $modx->event->returnedValues = [
            'row' => [
                'badges' => $badges,
                'badges_json' => json_encode($badges),
                'has_badges' => !empty($badges),
            ],
        ];
        break;
}
```

--------------------------------

### GET Parameters for service=addresses

Source: https://docs.modx.pro/components/minishop3/snippets/mscustomer

Examples of URL parameters used to manage user addresses.

```text
/cabinet/addresses/              — список адресов
/cabinet/addresses/?mode=create  — создание адреса
/cabinet/addresses/?mode=edit&id=5  — редактирование адреса #5
```

--------------------------------

### GET Parameters for service=orders

Source: https://docs.modx.pro/components/minishop3/snippets/mscustomer

Examples of URL parameters used to filter or paginate order data.

```text
/cabinet/?order_id=15      — детали заказа #15
/cabinet/?status=2         — заказы со статусом 2
/cabinet/?offset=20        — вторая страница
```

--------------------------------

### Configuration Examples

Source: https://docs.modx.pro/components/mfilter/settings

Various configuration snippets for SEO, high-load environments, and custom frontend stacks.

```text
mfilter.seo_max_filters = 2
mfilter.seo_max_values = 1
mfilter.non_canonical_url_handling = 404
```

```text
mfilter.cache_enabled = true
mfilter.cache_lifetime = 7200
mfilter.default_limit = 24
```

```text
mfilter.register_frontend = false
mfilter.auto_submit = true
mfilter.auto_submit_delay = 500
```

--------------------------------

### Example Grid Configuration Response

Source: https://docs.modx.pro/components/minishop3/development/routing

Structure of the JSON response returned by the GET /grid-config/{grid_key} endpoint.

```json
{
  "columns": [
    { "name": "id", "label": "ID", "type": "model", "visible": true, ... }
  ],
  "direct_filter_keys": ["query", "status_id", "delivery_id", ...],
  "editor_references": [
    { "key": "vendors", "path": "/api/mgr/references/vendors" }
  ]
}
```

--------------------------------

### Build Reactions from Source

Source: https://docs.modx.pro/components/reactions

Commands to install dependencies and build the frontend widget from the source code.

```bash
composer install
php _build/build.php
```

--------------------------------

### Order Identification via GET Parameters

Source: https://docs.modx.pro/components/minishop3/frontend/thanks

Examples of URL structures used to identify orders on the thanks page.

```text
/thanks/?msorder=15
```

```text
/thanks/?msorder=a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

--------------------------------

### API Configuration Example

Source: https://docs.modx.pro/components/ms3promocode/frontend/js-api

Shows how to globally configure the MS3 Promo Code API, including setting a custom API URL and enabling debug logging.

```javascript
<script>
window.ms3PromoCodeFrontConfig = {
    apiUrl: '/custom-api/v1/promo',  // редко нужно
    debug: true,                      // выводить запросы в консоль
    currencySymbol: '₽',
    currencyPosition: 'after',
};
</script>
<script src=".../ms3promocode.headless.js"></script>
```

--------------------------------

### Fetch Banners via cURL

Source: https://docs.modx.pro/components/bannerpro/development/rest-api

Example of retrieving a list of active banners using a GET request with authentication.

```bash
curl -s -H "Authorization: Bearer YOUR_API_KEY" \
  "https://example.com/assets/components/bannerpro/api.php?route=/ads&limit=10&active=1"
```

--------------------------------

### Display Recipe Help

Source: https://docs.modx.pro/components/mxmigrations/custom-recipes

Use the CLI to view help information for a registered recipe.

```bash
php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/components/site/config/migrations.php \
  recipe:help site:seed-warehouse
```

--------------------------------

### Use usePermission in Vue Template

Source: https://docs.modx.pro/components/vuetools/composables

Example of using usePermission within a Vue component setup script to control UI visibility.

```vue
<script setup>
import { computed } from 'vue'
import { usePermission } from '@vuetools/usePermission'

const { hasPermission } = usePermission()

const canEdit = computed(() => hasPermission('my_component_edit'))
const canDelete = computed(() => hasPermission('my_component_delete'))
</script>

<template>
  <Button v-if="canEdit" label="Редактировать" />
  <Button v-if="canDelete" label="Удалить" severity="danger" />
</template>
```

--------------------------------

### Comprehensive Plugin Example

Source: https://docs.modx.pro/components/minishop3/development/events/plugins-guide

A full implementation demonstrating product validation, quantity limiting, and logging within cart events.

```php
<?php
/**
 * Плагин: Контроль добавления в корзину
 *
 * События: msOnBeforeAddToCart, msOnAddToCart
 *
 * Функционал:
 * - Запрет добавления товаров без цены
 * - Ограничение максимального количества
 * - Логирование добавлений
 */

switch ($modx->event->name) {

    case 'msOnBeforeAddToCart':
        /** @var \MiniShop3\Model\msProduct $product */
        $product = $scriptProperties['msProduct'];
        $count = $scriptProperties['count'];
        $options = $scriptProperties['options'] ?? [];

        // Проверка: товар должен иметь цену
        if ($product->get('price') <= 0) {
            $modx->event->output($modx->lexicon('ms3_cart_product_not_available'));
            return;
        }

        // Проверка: максимум 99 единиц
        $maxCount = 99;
        if ($count > $maxCount) {
            $values = &$modx->event->returnedValues;
            $values['count'] = $maxCount;

            // Сохраняем для уведомления в msOnAddToCart
            $modx->eventData['cartControl']['count_limited'] = true;
            $modx->eventData['cartControl']['original_count'] = $count;
        }

        // Добавляем метку времени в опции
        $values = &$modx->event->returnedValues;
        $options['added_timestamp'] = time();
        $values['options'] = $options;
        break;

    case 'msOnAddToCart':
        $product = $scriptProperties['msProduct'];
        $count = $scriptProperties['count'];
        $productKey = $scriptProperties['product_key'];

        // Логируем добавление
        $modx->log(modX::LOG_LEVEL_INFO, sprintf(
            '[CartControl] Товар добавлен: %s (ID: %d), количество: %d, ключ: %s',
            $product->get('pagetitle'),
            $product->get('id'),
            $count,
            $productKey
        ));

        // Проверяем, было ли ограничено количество
        if (!empty($modx->eventData['cartControl']['count_limited'])) {
            $original = $modx->eventData['cartControl']['original_count'];
            $modx->log(modX::LOG_LEVEL_WARN, sprintf(
                '[CartControl] Количество ограничено: запрошено %d, добавлено %d',
                $original,
                $count
            ));
        }
        break;
}
```

--------------------------------

### JSON Output Example

Source: https://docs.modx.pro/components/geolocation2/snippets/GeoLocation2Current

Example of the JSON structure returned when asJson=1 is set.

```json
{
  "gl2_current_id": "1",
  "gl2_current_name_ru": "Москва",
  "gl2_current_name_en": "Moscow",
  "gl2_display_name_ru": "Москва",
  "gl2_real_name_ru": "Москва",
  "gl2_confirmed": "0",
  "gl2_csrf": "a1b2c3…"
}
```

--------------------------------

### simpleFilters Call Example

Source: https://docs.modx.pro/components/simplefilters/seopages

Example of a simpleFilters snippet call with filter and alias parameters.

```modx
[[!simpleFilters?
  &filters=`ms_color,ms_vendor_id`
  &aliases=`ms_color==color,ms_vendor_id==brand`
  ...
]]
```

--------------------------------

### Initialize and Apply Promo Code via JS Client

Source: https://docs.modx.pro/components/ms3promocode/api

Example usage of the headless JavaScript client to initialize and apply a promo code.

```javascript
await window.ms3PromoCode.init();
const result = await window.ms3PromoCode.apply('SALE10');
```

--------------------------------

### List and inspect migration recipes via CLI

Source: https://docs.modx.pro/components/mxmigrations/recipes

Use these commands to list all available recipes or view detailed help for a specific recipe template.

```bash
php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php recipe:list

php core/components/mxmigrations/bin/mxmigrations.php \
  --config=core/config/mxmigrations.php recipe:help create-tables
```

--------------------------------

### Custom Chunk Template Example

Source: https://docs.modx.pro/components/msviewcounter/frontend/product

Example implementation of a custom social proof chunk.

```fenom
<aside class="product-social-proof">
    {if $total_text}
        <div class="product-social-proof__item">{$total_text}</div>
    {/if}
    {if $online_text}
        <div class="product-social-proof__item product-social-proof__item--online">{$online_text}</div>
    {/if}
</aside>
```

```modx
<aside class="product-social-proof">
    [[+total_text:notempty=`<div class="product-social-proof__item">[[+total_text]]</div>`]]
    [[+online_text:notempty=`<div class="product-social-proof__item product-social-proof__item--online">[[+online_text]]</div>`]]
</aside>
```

--------------------------------

### Use useModx Examples

Source: https://docs.modx.pro/components/vuetools/composables

Demonstrates accessing configuration properties, site ID, and calling MODX methods like alerts and confirmations.

```javascript
const { modx, config, siteId } = useModx()

// Доступ к конфигурации
const assetsUrl = config.assets_url
const connectorUrl = config.connector_url
const baseUrl = config.base_url

// MODX Site ID для авторизации API
console.log(siteId) // "modx68ed50b266b7e9.17779601_168f40d849ba6b1.18395696"

// Использование MODX методов
modx.msg.alert('Заголовок', 'Сообщение')
modx.msg.confirm({
  title: 'Подтверждение',
  text: 'Вы уверены?',
  url: config.connector_url,
  params: { action: 'myaction' }
})
```

--------------------------------

### Example Cron Request

Source: https://docs.modx.pro/components/msreviews/api

Example of a POST request to trigger the cron queue processing.

```text
POST assets/components/msreviews/connector.php
action=request/process&key=ВАШ_КЛЮЧ
```

--------------------------------

### Clone Repository

Source: https://docs.modx.pro/guide/getting-started

Initial step to download the documentation repository to a local machine.

```shell
git clone https://github.com/your-fork/Docs.git
```

--------------------------------

### Install PostCSS Prefix Selector

Source: https://docs.modx.pro/components/vuetools/integration

Installs the required PostCSS plugin for style isolation.

```bash
npm install postcss-prefix-selector --save-dev
```

--------------------------------

### Initialize xPDO Connection

Source: https://docs.modx.pro/system/xpdo/xpdo-class

Demonstrates establishing a basic database connection and executing a query using the xPDO class.

```php
<?php

define('MODX_CORE_PATH', '/path/to/revo/core/');
define('MODX_CONFIG_KEY','config');
require_once MODX_CORE_PATH . 'model/modx/modx.class.php';

// Параметры базы данных
$host = 'localhost';
$username = 'your_username';
$password = 'your_password';
$dbname = 'your_database';
$port = 3306;
$charset = 'utf-8';

$dsn = "mysql:host=$host;dbname=$dbname;port=$port;charset=$charset";
$xpdo = new xPDO($dsn, $username, $password);

// Тестирование соединения
echo $o = ($xpdo->connect()) ? 'Connected' : 'Not Connected';

// Делаем запрос к базе данных и выводим количество результатов:
$results = $xpdo->query("SELECT id FROM some_table");
$recordCount = $results->rowCount();
print $recordCount;
```

--------------------------------

### Configure filters and aliases

Source: https://docs.modx.pro/components/simplefilters/snippets

Example configuration for the &filters and &aliases parameters, demonstrating various field types and prefixes.

```text
&filters=`
    parent:select,
    ms_vendor_id:select,
    ms_price:slider,
    tv_instock:slider,
    migx_chars_Высота:slider:title|value,
    ms_color,
    ms_tags:select
`
&aliases=`
    ms_vendor_id==brand,
    ms_price==price,
    tv_instock==instock,
    migx_chars_Высота==height,
    ms_color==color,
    ms_tags==tags
`
```

--------------------------------

### Install Imagick for FPM

Source: https://docs.modx.pro/components/imageoptimizer/troubleshooting

Install the Imagick extension specifically for the FPM PHP environment.

```bash
pecl install imagick
```

--------------------------------

### Example JSON-LD Output

Source: https://docs.modx.pro/components/reactions/integrations/seo

Example of the generated JSON-LD structure for an object with 80 likes and 20 dislikes.

```json
{
  "@context": "https://schema.org",
  "@type": "AggregateRating",
  "ratingValue": 4.2,
  "ratingCount": 100,
  "bestRating": 5,
  "worstRating": 1
}
```

--------------------------------

### Manage msOption objects

Source: https://docs.modx.pro/components/minishop3/development/backend-api/options

Demonstrates creating, retrieving, assigning, and listing product options using the msOption model.

```php
use MiniShop3\Model\msOption;

// Создать опцию
$option = $modx->newObject(msOption::class);
$option->set('key', 'material');
$option->set('caption', 'Материал');
$option->set('type', 'combo-multiple');
$option->save();

// Получить опцию
$option = $modx->getObject(msOption::class, ['key' => 'color']);

// Назначить категориям
$assigned = $option->setCategories([5, 12, 18]);

// Получить все опции
$options = $modx->getIterator(msOption::class);
```

--------------------------------

### Connector Request Example

Source: https://docs.modx.pro/components/mxquickview/api

Example of how to trigger a render action via the connector using the Fetch API.

```javascript
const response = await fetch('/assets/components/mxquickview/connector.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    action: 'render',
    data_action: 'chunk',
    element: 'mxqv_product',
    id: '7'
  })
});

const data = await response.json();
```

--------------------------------

### Programmatic Data Generation

Source: https://docs.modx.pro/components/ms3demodata

Example of how to initialize the service and trigger data generation programmatically.

```php
// Получить сервис
$ms3demodata = $modx->services->get('ms3demodata');

// Создать генератор
$generator = new \MS3DemoData\Services\DemoDataGenerator($modx);

// Запустить генерацию
$result = $generator->run([
    'package' => 'S',           // S, M или L
    'parent_id' => 0,           // ID родительского ресурса
    'category_template' => 1,   // ID шаблона категории
    'product_template' => 2,    // ID шаблона товара
    'source_id' => 1,           // ID Media Source
    'generate_customers' => true,
    'generate_orders' => true,
]);

if ($result['success']) {
    echo $result['message'];
    // "Генерация завершена за 5.23 сек. Создано: производителей — 4, категорий — 6, товаров — 100, клиентов — 20, заказов — 50"
}
```

--------------------------------

### Example Task File

Source: https://docs.modx.pro/components/minishop3/development/scheduler

This PHP code demonstrates the basic structure of a task file for the Scheduler component. It shows how to access MiniShop3 services and log task completion or errors.

```php
<?php
/**
 * @var modX $modx
 * @var sFileTask $task
 * @var sTaskRun $run
 * @var array $scriptProperties
 */

// Получение сервиса MiniShop3
$ms3 = $modx->services->get('ms3');

// Ваша логика
try {
    // ... выполнение задачи ...

    $modx->log(modX::LOG_LEVEL_INFO, "[myTask] Completed successfully");
    return true;
} catch (\Exception $e) {
    $run->addError($e->getMessage());
    return false;
}

```

--------------------------------

### Manage Vendors and Product Links in PHP

Source: https://docs.modx.pro/components/minishop3/development/backend-api/product

Demonstrates creating a vendor, linking it to a product, and retrieving the vendor object from a product.

```php
use MiniShop3\Model\msVendor;
use MiniShop3\Model\msProductData;

// Создать производителя
$vendor = $modx->newObject(msVendor::class);
$vendor->set('name', 'Samsung');
$vendor->set('country', 'Южная Корея');
$vendor->save();

// Привязать к товару
$productData = $modx->getObject(msProductData::class, $productId);
$productData->set('vendor_id', $vendor->get('id'));
$productData->save();

// Получить производителя товара
$vendor = $productData->getOne('Vendor');
echo $vendor->get('name');  // "Samsung"
```

--------------------------------

### Install Component Dependencies

Source: https://docs.modx.pro/components/ms3demodata

Commands to install PHP dependencies for the component and build the Vue manager interface.

```bash
cd core/components/ms3demodata
composer install

cd ../../../vueManager
npm install
npm run build
```

--------------------------------

### Example Plugin for Logging

Source: https://docs.modx.pro/components/mspricetiers/events

A sample plugin implementation that logs the resolved price for a product when the mspricetiersOnResolvePrice event occurs.

```php
<?php
switch ($modx->event->name) {
    case 'mspricetiersOnResolvePrice':
        $rp = $scriptProperties['resolved_price'] ?? null;
        if ($rp) {
            $modx->log(modX::LOG_LEVEL_INFO, '[msPT] product ' . $scriptProperties['product_id']
                . ' qty ' . $scriptProperties['quantity']
                . ' price ' . $rp->getPrice());
        }
        break;
}
```

--------------------------------

### MyFavorites.btn Template Example

Source: https://docs.modx.pro/components/myfavorites

Example template logic for displaying a list of favorite products or an empty state message.

```smarty
{if $ids != '-0'}
<div class="row">
    {$_modx->runSnippet('!pdoPage', [
    'element'=>'msProducts',
    'parents' => 0,
    'resources' => $ids,
    'limit' => 12,
    ])}
</div>
<div class="row">
    <div class="col">
        <button class="btn btn-primary" data-myfavorites-clear>{'myfavorites_clear_list' | lexicon}</button>
    </div>
</div>
<div class="row">
    <div class="col text-center">
        {'page.nav' | placeholder}
    </div>
</div>
{else}
<div class="alert alert-primary d-flex align-items-center" role="alert">
    <svg class="bi flex-shrink-0 me-2" width="24" height="24" role="img" aria-label="Info:"><use xlink:href="#info-fill"></use></svg>
    <div>{'myfavorites_info_list_empty' | lexicon}</div>
</div>
{/if}
```

--------------------------------

### MyFavorites.ids Usage Examples

Source: https://docs.modx.pro/components/myfavorites

Examples for retrieving favorite IDs, including standard MODX syntax and Fenom syntax.

```modx
[[!MyFavorites.ids? &toPlaceholder=`myf.ids`]]
[[!+myf.ids:is=`-0`:then=`
<div class="alert alert-primary d-flex align-items-center" role="alert">
    <svg class="bi flex-shrink-0 me-2" width="24" height="24" role="img" aria-label="Info:"><use xlink:href="#info-fill"></use></svg>
    <div>[[%myfavorites_info_list_empty]]</div>
</div>
`:else=`
<div class="row">
    [[!pdoPage?
    &element=`msProducts`
    &parents=`0`
    &limit=`12`
    &resources=`[[!+myf.ids]]`
    ]]
</div>
<div class="row">
    <div class="col">
        <button class="btn btn-primary" data-myfavorites-clear>[[%myfavorites_clear_list]]</button>
    </div>
</div>
<div class="row">
    <div class="col text-center">
    [[!+page.nav]]
    </div>
</div>
`]]
```

```modx
{set $ids = $_modx->runSnippet('!MyFavorites.ids')}
```

--------------------------------

### POST /api/mgr/import/start

Source: https://docs.modx.pro/components/minishop3/interface/utilities/import

Initiates the product import process using a specified CSV file and mapping configuration.

```APIDOC
## POST /api/mgr/import/start

### Description
Initiates the import process for product data from a CSV file.

### Method
POST

### Endpoint
/api/mgr/import/start

### Request Body
- **importfile** (string) - Required - Path to the CSV file (e.g., "assets/import/products.csv")
- **mapping** (string) - Required - JSON string mapping CSV columns to product fields (e.g., "{\"0\":\"pagetitle\",\"1\":\"parent\",\"2\":\"price\"}")
- **delimiter** (string) - Optional - CSV delimiter character (default: ";")
- **skip_header** (boolean) - Optional - Whether to skip the first row of the CSV
- **update** (boolean) - Optional - Whether to update existing products
- **key** (string) - Optional - Field used as a unique identifier for updates (e.g., "article")
- **scheduler** (boolean) - Optional - Whether to run via scheduler
- **debug** (boolean) - Optional - Enable debug mode

### Request Example
{
  "importfile": "assets/import/products.csv",
  "mapping": "{\"0\":\"pagetitle\",\"1\":\"parent\",\"2\":\"price\"}",
  "delimiter": ";",
  "skip_header": true,
  "update": true,
  "key": "article",
  "scheduler": false,
  "debug": false
}
```

--------------------------------

### Implement ms3Confirm usage examples

Source: https://docs.modx.pro/components/minishop3/development/frontend-js

Demonstrates basic usage and customization of the confirmation dialog, including setting button styles.

```javascript
// Простое подтверждение
const ok = await ms3Confirm('Вы уверены?')
if (!ok) return

// С красной кнопкой (для деструктивных действий)
const ok = await ms3Confirm('Удалить адрес?', {
  confirmClass: 'danger'
})
```

--------------------------------

### JavaScript Fetch Examples

Source: https://docs.modx.pro/components/geolocation2/api-action

Examples of using the fetch API to perform search and save operations against the GeoLocation2 endpoint.

```javascript
fetch('/assets/components/geolocation2/action.php?action=search&query=каз', {
  headers: { 'X-Requested-With': 'XMLHttpRequest' },
}).then((r) => r.json());
```

```javascript
const body = new URLSearchParams({
  action: 'save',
  csrf: document.querySelector('[data-gl2-csrf]').dataset.gl2Csrf,
  city_id: '8',
});
fetch('/assets/components/geolocation2/action.php', {
  method: 'POST',
  headers: { 'X-Requested-With': 'XMLHttpRequest' },
  body,
});
```

--------------------------------

### Initialize PromoCodeService

Source: https://docs.modx.pro/components/ms3promocode/development/services

Retrieve the PromoCodeService instance from the MODX services container.

```php
/** @var \ms3PromoCode\Services\PromoCodeService $svc */
$svc = $modx->services->get('ms3promocode_promo_code_service');
```

--------------------------------

### MyFavorites.btn Usage Examples

Source: https://docs.modx.pro/components/myfavorites

Examples for rendering the favorites button, including removing HTML elements and passing labels for analytics.

```modx
<div id="product-item-[[+id]]">
[[!MyFavorites.btn? &id=`[[+id]]` &remove=`product-item`]]
.
.
.
</div>
```

```modx
[[!MyFavorites.btn? &id=`[[+id]]` &label=`[[+pagetitle]]`]]
```

--------------------------------

### Manual Initialization

Source: https://docs.modx.pro/components/minishop3/development/javascript

Example of how to manually initialize the MiniShop3 API core modules and perform a cart operation.

```APIDOC
## Manual Initialization

### Description
Initialize the MiniShop3 API core by configuring the `TokenManager` and `ApiClient`, then instantiating the API modules.

### Code Example
```javascript
// Configuration
const config = {
  apiUrl: '/assets/components/minishop3/api.php',
  tokenName: 'ms3_token'
}

// Initialization
const tokenManager = new TokenManager(config)
const apiClient = new ApiClient({ baseUrl: config.apiUrl, tokenManager })
tokenManager.setApiClient(apiClient)

// Ensure token
await tokenManager.ensureToken()

// API modules
const cart = new CartAPI(apiClient)
const order = new OrderAPI(apiClient)
const customer = new CustomerAPI(apiClient)

// Usage example
const response = await ms3.cartAPI.add(123, 2, { color: 'red' })
```
```

--------------------------------

### API response example for payment link

Source: https://docs.modx.pro/components/msfastorder/integration

Example of the JSON response returned by the connector when an order is created with a payment link.

```json
{
  "success": true,
  "data": {
    "order_id": 15,
    "method": "MS",
    "payment_link": "https://yoomoney.ru/checkout/payments/..."
  }
}
```

--------------------------------

### Image Thumbnail Generation Examples

Source: https://docs.modx.pro/components/migxpageconfigurator/media

Examples of HTML markup and the resulting Fenom template output for image thumbnail processing.

```html
<img data-mpc-field="img" src="assets/img/cover.png" width="320" height="200" alt="">
```

```fenom
<img
  src="assets/components/migxpageconfigurator/images/fake-img.png"
  data-lazy="{'mpcThumb' | snippet: ['input' => $img[0].src, 'options' => 'q=90&zc=1&f=webp&w='~$img[0].width~'&h='~$img[0].height]}"
  alt="{$img[0].title}">
```

--------------------------------

### Initialize and Render msBundles

Source: https://docs.modx.pro/components/msbundles/frontend

Examples of initializing the msBundles component and rendering the bundle list alongside the cart using Fenom or standard MODX tags.

```fenom
{extends 'file:templates/base.tpl'}

{block 'head'}
  {'!msBundles.initialize' | snippet}
{/block}

{block 'content'}
  <h1>{$_modx->resource.pagetitle}</h1>

  {'!msBundles' | snippet : [
    'product' => $_modx->resource.id,
    'tpl' => 'tplMsBundlesItem',
    'wrapperTpl' => 'tplMsBundlesList',
    'emptyTpl' => 'tplMsBundlesEmpty',
    'activeOnly' => true,
    'quantity' => 1
  ]}

  <section id="ms-cart" data-ms-cart aria-live="polite">
    {'!msCart' | snippet : [
      'tpl' => 'tpl.msCart',
      'return' => 'tpl',
      'selector' => '#ms-cart'
    ]}
  </section>
{/block}
```

```modx
[[!msBundles.initialize]]

[[!msBundles?
  &product=`[[*id]]`
  &tpl=`tplMsBundlesItem`
  &wrapperTpl=`tplMsBundlesList`
  &emptyTpl=`tplMsBundlesEmpty`
  &activeOnly=`1`
  &quantity=`1`
]]

<div id="ms-cart" data-ms-cart aria-live="polite">
  [[!msCart?
    &tpl=`tpl.msCart`
    &return=`tpl`
    &selector=`#ms-cart`
  ]]
</div>
```

--------------------------------

### tpl.ffCheckbox Markup Example

Source: https://docs.modx.pro/components/flatfilters/chunks

Example of a single checkbox input chunk for filtering, utilizing the key placeholder and lexicon for labels.

```fenom
<div class="col-md-3 mb-3">
    <div class="form-check col-auto">
        <input class="form-check-input" type="checkbox" data-ff-filter="{$key}" name="{$key}" value="1" id="{$key}" {$.get[$key] ? 'checked' : ''}>
        <label class="form-check-label" for="{$key}">
            {('ff_frontend_'~$key) | lexicon}
        </label>
    </div>
</div>
```

--------------------------------

### Install CommerceBridge 1C via CLI

Source: https://docs.modx.pro/components/commercebridge1c/installation

Automated installation command for deploying the component via the command line interface.

```bash
php core/components/CommerceBridge1C/setup/install.php exchange 'сложный-пароль' 12
```

--------------------------------

### Applying filters with MFilter

Source: https://docs.modx.pro/components/mfilter/development/services

Demonstrates initializing the filter service and applying specific criteria to retrieve and iterate over resource items.

```php
$filter = $mfilter->getFilter();

$result = $filter->apply(5, [
    'vendor_id' => ['12'],
    'price' => ['10000', '50000'], // [min, max] для number-фильтра
], [
    'sortBy' => 'price',
    'sortDir' => 'ASC',
    'limit' => 24,
    'offset' => 0,
]);

echo "Найдено: {$result['meta']['total']}\n";
foreach ($result['items'] as $item) {
    echo "{$item['pagetitle']}\n";
}
```

--------------------------------

### Configure Warehouse GUIDs

Source: https://docs.modx.pro/components/commercebridge1c/exchange-setup

Specify the GUIDs of the required warehouses separated by commas in the commerceml_warehouse_ids setting to filter stock levels.

```text
7f2a...,b91c...
```

--------------------------------

### Initialize pdoTools

Source: https://docs.modx.pro/components/pdotools/classes/pdotools

Basic initialization of the pdoTools service.

```php
$pdoTools = $modx->getService('pdoTools');
```

--------------------------------

### Display all product options

Source: https://docs.modx.pro/components/minishop3/snippets/msproductoptions

Basic usage to output all available options for the current product.

```fenom
{'msProductOptions' | snippet}
```

--------------------------------

### Listen for MiniShop3 initialization

Source: https://docs.modx.pro/components/minishop3/frontend/cart

Execute custom logic once the MiniShop3 library has finished initializing.

```javascript
document.addEventListener('ms3:ready', function() {
    console.log('MiniShop3 готов к работе');
});
```

--------------------------------

### msGetOrder with Product Previews

Source: https://docs.modx.pro/components/minishop3/snippets/msgetorder

Include product thumbnails by specifying the thumb size.

```fenom
{'msGetOrder' | snippet : [
    'includeThumbs' => 'small'
]}
```
Tokens:
Raw