SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbitrix-best-practice-core

bitrix-best-practice-core

Design & creation

View repository

Updated 10-15 17:27

About this skill

Bitrix Core Best Practice

The skill helps you understand which Bitrix/PHP best practices to use.

How to use

  1. Identify the architectural layer that the task affects.
  2. Open only those rule files that directly relate to this layer.
  3. First, follow the stricter repository rules and module constraints.
  4. Prefer framework-native Bitrix patterns over your own abstractions.

Choosing a rule file

When to read controller.md

Read controller.mdif the task affects at least one of these areas:

  • a class extending Bitrix\Main\Engine\Controller or a descendant thereof;
  • any *Action()method;
  • filters, attributes, prefilters, and Engine Controller responses.

When to read error.md

Read error.mdif the task affects at least one of these areas:

  • Bitrix\Main\Error, Bitrix\Main\ErrorCollection or application error classes on top of them;
  • getErrors(), getError(), getErrorCollection() or getErrorByCode() in a service, controller, or response flow;
  • choosing code, customData and the public error contract for UI, AJAX, or another client;
  • transferring already created errors between Result, controller lifecycle и AjaxJson.

When to read result.md

Read result.mdif the task affects at least one of these areas:

  • Bitrix\Main\Result, isSuccess(), setData(), getData(), addError() or addErrors();
  • returning Result from a service, command, handler, or integration layer as an outcome contract;
  • choosing between Bitrix\Main\Result, a custom *Resultclass, and an implicit array as a return DTO;
  • the payload composition in Result::setData() and the boundary between success data and error flow.

When to read request.md

Read request.mdif the task affects at least one of these areas:

  • Bitrix\Main\Request, HttpRequest, $this->getRequest() or Context::getCurrent()->getRequest();
  • choosing between get(), getQuery(), getPost(), getHeader(), getCookie() or getJsonList();
  • replacing $_REQUEST, $_GET, $_POST, $_COOKIE и php://input with the framework-native request API;
  • JSON body, JsonPayload, decodeJson() or decodeJsonStrict().

When to read response.md

Read response.mdif the task affects at least one of these areas:

  • Bitrix\Main\Response, HttpResponse, addHeader(), setStatus(), addCookie() or redirectTo();
  • Bitrix\Main\Engine\Response\Json, AjaxJson, Redirect, File, HtmlContent or render-response helpers;
  • replacing manual header(), Set-Cookie, setcookie() or json_encode() with the standard Bitrix response layer;
  • choosing the HTTP response type for a controller action or another infrastructure endpoint.

When to read routing.md

Read routing.mdif the task touches at least one of these areas:

  • file in <module>/install/routes/ or route registration in /bitrix/routes/ и /local/routes/;
  • RoutingConfigurator, prefix, group, route HTTP methods, where, default, name;
  • PublicPageController or migrating legacy URLs from urlrewrite.php to modern routing;
  • site-guard and routes for a specific site in a multisite installation;
  • array [Controller::class, 'action'] in the route.

When to read loader.md

Read loader.mdif the task touches at least one of these areas:

  • Loader::includeModule() or Loader::requireModule();
  • CModule::IncludeModule() or CModule::IncludeModuleEx();
  • optional module integration with fallback when the module is absent;
  • fail-fast dependency, where the absence of a module should lead to an error rather than a silent skip.

When to read geo-ip.md

Read geo-ip.mdif the task touches at least one of these areas:

  • Bitrix\Main\Service\GeoIp\Manager, getRealIp(), getDataResult() or convenience getters like getCountryCode() / getCityName();
  • Bitrix\Main\Web\IpAddress in the context of GeoIP lookup, range cache, or differences between IPv4 and IPv6 for geodata;
  • custom GeoIP handler, a descendant of Bitrix\Main\Service\GeoIp\Base or registration via onMainGeoIpHandlersBuildList;
  • post-processing of the GeoIP result via onGeoIpGetResult;
  • choosing between a simple string lookup and a full Result-based GeoIP lookup.
  • geolocation determination

When to read uri.md

Read uri.mdif the task touches at least one of these areas:

  • Bitrix\Main\Web\Uri, new Uri($url), getQuery(), addParams(), deleteParams(), toAbsolute() or resolveRelativeUri();
  • parsing, modifying, or rebuilding a URL / URI / redirect URL in Bitrix code;
  • choosing between Uri, parse_url() и parse_str() for query string, host, path, fragment, or absolute URL;
  • query parameters with dots or spaces, where preserveDots.

When to read http-client.md

Read http-client.mdif the task touches at least one of these areas:

  • Bitrix\Main\Web\HttpClient, new HttpClient(), get(), post(), query() or download();
  • outbound HTTP(S) requests, webhook sender, remote download/upload, or external API integration;
  • replacing file_get_contents($url) / stream_context_create() for remote http/https URL;
  • replacing curl_init, curl_setopt, curl_exec and other raw curl_* calls with framework-native transport.

When to read jwt.md

Read jwt.mdif the task touches at least one of these areas:

  • Bitrix\Main\Web\JWT, JWT::encode(), JWT::decode(), JWT::urlsafeB64Encode() or JWT::urlsafeB64Decode();
  • Bitrix\Main\Web\JWK, JWK::parseKeySet() or JWK::parseKey();
  • issuing, verifying, or parsing JWT / JWK / JWKS / JOSE-compatible data;
  • choosing between the framework-native JWT/JWK API and manually assembling the token, key parsing, or a Base64 URL-safe helper.

When to read date-time.md

Read date-time.mdif the task touches at least one of these areas:

  • Bitrix\Main\Type\Date or Bitrix\Main\Type\DateTime;
  • createFromUserTime(), tryParse(), toUserTime(), toString(), createFromTimestamp() or createFromPhp();
  • parsing, formatting, or timestamp conversion for date and time in Bitrix code;
  • choosing between Bitrix date types and \DateTime / \DateTimeImmutable.

When to read option.md

Read option.mdif the task touches at least one of these areas:

  • Bitrix\Main\Config\Option, Option::get(), set(), getRealValue(), getForModule() or delete();
  • COption::GetOptionString(), SetOptionString(), GetOptionInt() or RemoveOption() as a legacy trigger;
  • default_option.php, module options.php, a site-specific setting or a feature flag / policy in the DB;
  • choosing between permanent configuration in Option, deploy-time config в .settings.php and temporary runtime state.

When to read logger.md

Read logger.mdif the task touches at least one of these areas:

  • Bitrix\Main\Diag\Logger, Bitrix\Main\Diag\LoggerFactory, LoggerRegistry, FileLogger or LogFormatter;
  • Psr\Log\LoggerInterface, PSR-3 levels (info, warning, error, debug) и structured context;
  • registering a logger id in .settings.php via the loggers section or DI via constructorParams;
  • replacing AddMessage2Log(), Logger::create() or ad hoc file_put_contents() / error_log() with a framework-native logging path;
  • choosing between a named logger id, default logger fallback, and a legacy logging boundary.

When to read uuid-generator.md

Read uuid-generator.mdif the task touches at least one of these areas:

  • Bitrix\Main\UuidGenerator or UuidGenerator::generateV4();
  • generating UUID v4 for a session id, correlation id, upload token, public proxy id, or another random opaque identifier;
  • choosing between UuidGenerator, uniqid(), Random::getBytes(), manually assembling a UUID, or a local helper generator;
  • a legacy boundary where a UUID is needed in a wrapper such as {uuid}, but the canonical generator must remain unified.

When to read validation.md

Read validation.mdif the task touches at least one of these areas:

  • Bitrix\Main\Validation\Rule\... on the parameters *Action() or properties of the input object;
  • ValidationParameter, ValidationService, ValidationResult, ValidationError or ValidationGroup;
  • automatic input validation before entering the action or manual validation of a DTO / command in the service layer;
  • choosing between validation attributes, ValidationParameter and explicit ValidationService::validate();
  • custom validators and custom validation attributes on top of Bitrix\Main\Validation.

When to read service-locator.md

Read service-locator.mdif the task touches at least one of these areas:

  • Bitrix\Main\DI\ServiceLocator, ServiceLocator::getInstance(), get(), has(), addInstance() or addInstanceLazy();
  • {module}/.settings.php, service registration, service id, FQCN binding or interface binding for DI;
  • choice between action autowiring, explicit ServiceLocator::get(...) and manual new MyService() for a shared service;
  • replacing ad hoc creation of a service class with the framework-native container path.

When to read persistent-storage.md

Read persistent-storage.md, if the task touches at least one of these areas:

  • Bitrix\Main\Data\Storage\PersistentStorageInterface, StorageInterface, DeferredStorageDecorator or ServiceLocator::get(PersistentStorageInterface::class);
  • Bitrix\Main\Config\Option::get() / Option::set() in a scenario where you need to understand whether it is configuration or temporary runtime-state;
  • TTL state, progress/checkpoint, one-time token, upload/import session, rate-limit counter, or other temporary server-side state between requests;
  • choice between Option, persistent storage и cache (Bitrix\Main\Data\Cache / ManagedCache) for storing data.

When to read cache.md

Read cache.md, if the task touches at least one of these areas:

  • Bitrix\Main\Data\Cache, ManagedCache, TaggedCache, Cache::createInstance(), initCache(), startDataCache(), endDataCache() or abortDataCache();
  • Application::getInstance()->getCache(), getManagedCache(), getTaggedCache() or container binding of cache services in main/.settings.php;
  • choice between a simple TTL-cache, managed invalidation by key/dir, and tag-based invalidation;
  • CPHPCache, CCacheManager, $CACHE_MANAGER or CStackCacheManager as a legacy trigger;
  • derived read-cache that can be lost and recalculated, unlike runtime-state and permanent configuration.

When to read event.md

Read event.md, if the task touches at least one of these areas:

  • Bitrix\Main\Event, EventResult, EventManager, send() or getResults();
  • generation of event and handler classes via Bitrix CLI;
  • creating a custom event, the contract of handler parameters and responses, or canceling an operation based on event results;
  • addEventHandler(), registerEventHandler(), compatible variants, call order, and unsubscribing;
  • AddEventHandler() or RegisterModuleDependences() as a legacy trigger and migrating positional handlers to D7.