Bitrix Taxidermist Laravel Package

Getting Started

This release is primarily an expansion of the Bitrix class surface available to Laravel applications: new \Bitrix\Main\Data\Cache output-control methods ($hasOutput, output(), noOutput()) and a large batch of classes from the main and sale modules.

Minimal steps:

1. Update the dependency and refresh autoloading:

   composer update <vendor>/<package>
   composer dump-autoload
   

2. Confirm the new API is visible before writing code:

   var_dump(method_exists(\Bitrix\Main\Data\Cache::class, 'output'));
   var_dump(property_exists(\Bitrix\Main\Data\Cache::class, 'hasOutput'));
   

3. Look first at the package source/class map for the main and sale namespaces, then compare against the Bitrix documentation for \Bitrix\Main\Data\Cache. The added classes are the best indicator of what is now considered supported.
4. First practical use case: wrap an expensive HTML fragment in Bitrix-style output caching and let the cache decide whether to replay buffered output:

   $cache = \Bitrix\Main\Data\Cache::createInstance();
   
   if ($cache->initCache(3600, 'home_banner_' . $locale, '/pages')) {
       $cache->output();          // emit cached output when available
   } elseif ($cache->startDataCache()) {
       $cache->noOutput();        // suppress buffering for this path if desired
       // ... render/collect data ...
       $cache->endDataCache(['html' => $html]);
   }
   

Implementation Patterns

Output-aware caching. Use $hasOutput / output() / noOutput() when a cache layer needs to control whether buffered HTML is replayed. A common pattern is a small service that encapsulates init/start/end and returns a consistent result to controllers or Blade composers:

final class BitrixCache
{
    public static function remember(string $key, int $ttl, string $dir, callable $callback): mixed
    {
        $cache = \Bitrix\Main\Data\Cache::createInstance();

        if ($cache->initCache($ttl, $key, $dir)) {
            return $cache->getVars();
        }

        if ($cache->startDataCache()) {
            $vars = $callback();
            $cache->endDataCache($vars);
            return $vars;
        }

        return null;
    }
}

Use output()/noOutput() only around code paths that intentionally produce HTML; keep data-only caching on getVars()/endDataCache() to avoid surprising buffering behaviour.

Controller/Blade integration. For page fragments, resolve the cache in a controller and pass the resulting HTML or vars to the view. For full responses, wrap the response body and use the output methods so cached fragments are replayed without re-rendering.

Sale module usage. The newly added sale classes make it practical to model orders, baskets, and related entities in Laravel services. Keep Bitrix sale interactions behind your own repository/service layer so controllers remain framework-agnostic:

final class OrderService
{
    public function find(int $id): ?\Bitrix\Sale\Order
    {
        return \Bitrix\Sale\Order::load($id);
    }
}

Testing workflow. Because the class surface grew significantly, add smoke tests that assert the classes and methods you depend on are present and callable. This catches regressions when a future release reshuffles stubs or implementations.

Incremental adoption. Treat each newly available module as opt-in. Build a thin adapter per module (Main, Sale) rather than calling Bitrix classes directly throughout the application; this limits the blast radius of future releases.

Gotchas and Tips

• Stubs vs. runtime. A large "many new classes" addition often means IDE/autoload surface rather than fully implemented behaviour. Verify each method you rely on with a real call, not just method_exists().
• Autoload staleness. After upgrading, run composer dump-autoload. Missing classes after an update are usually a class-map issue, not a package bug.
• Output buffering side effects. output() and noOutput() interact with PHP output buffering and with startDataCache(). Mixing them with Laravel's response/streamed responses can produce duplicated or swallowed output. Test with real HTTP responses, not just unit tests.
• Cache identity. initCache($ttl, $cacheId, $initDir) keys on all three values. Vary the cache ID by locale, user group, or other dimensions explicitly; otherwise stale cross-context output is easy to introduce.
• Cache invalidation. Pair endDataCache() with an explicit clear strategy (clearCache with matching ID/dir) on content updates. The output helpers do not add invalidation semantics.
• Version pinning. Given the breadth of new classes, pin the package version in composer.json and review release notes before minor upgrades; newly added module classes can change behaviour in adapters.
• Extension point. If the package exposes config or a class map, prefer registering your own bindings/aliases there rather than editing vendor files, so upgrades remain clean.
• Debugging. When a cache path behaves unexpectedly, log $cache->initCache(...) and $cache->startDataCache() return values plus $hasOutput around the call; most issues are a false startDataCache() or an unexpected hasOutput state.