Bitrix Hermitage Laravel Package

Getting Started

Hermitage is a thin OOP page/controller layer for 1C-Bitrix — think "Laravel controllers and views, but the framework underneath is Bitrix." If you're coming from Laravel, map it mentally as: a page class ≈ an invokable controller, a Hermitage view ≈ a Blade template (plain PHP, no Blade syntax), and urlrewrite.php ≈ routes/web.php.

Minimal setup:

1. composer require arrilot/bitrix-hermitage (the package is archived and its last release is from March 2018 — pin the version and be prepared to vendor-fork it if you hit PHP 8 issues).
2. Make sure Composer's autoloader is wired into Bitrix, typically by requiring vendor/autoload.php from /local/php_interface/init.php.
3. Register your page(s) with the package — usually a small config/bootstrap file under /local that maps a URL pattern or a symbolic page code to a page class.
4. Hook the dispatcher into Bitrix's routing. The idiomatic place is /urlrewrite.php (or 404.php/a front controller) so that a request matching your rule instantiates the page class instead of executing a plain PHP file.
5. Write your first page class with a handler method and a view file, then hit the URL.

First real use case: take one existing procedural page in the site root (say catalog/index.php) that is a soup of $APPLICATION->SetTitle(), component includes, and inline HTML, and port it to a single page class with a handle()-style method plus a view. Don't migrate the whole site — pick one page, get the dispatch path working end to end, then expand.

Where to look first: the package's README and its base page class (that's the contract you'll subclass), then your project's urlrewrite.php and /local/php_interface/init.php, since 90% of integration bugs live at that seam.

Implementation Patterns

Page-as-class, one class per route. Each page class owns its data fetching, its Bitrix calls ($APPLICATION->SetTitle, SetPageProperty, breadcrumbs), and its view. This is the biggest win over procedural Bitrix: the page's inputs, outputs, and side effects are in one readable unit instead of scattered across include files.

Views as dumb templates. Keep Bitrix component calls ($APPLICATION->IncludeComponent(...)) in the view where they're markup-shaped, and keep querying/business logic in the page class. Pass data into the view explicitly rather than relying on globals bleeding through — this is the habit that makes the code testable later.

Layered adoption. Hermitage is best used as an outer shell over legacy Bitrix. New pages are full page classes; legacy pages stay as-is behind separate urlrewrite rules. You can also have a page class delegate to an existing IncludeComponent call for a subsystem you don't want to rewrite yet — that gives you a gradual migration path without a big-bang.

AJAX / JSON endpoints. The same page-class pattern is handy for AJAX handlers: a class that reads $_REQUEST, validates, returns JSON, and sets the correct content type. Centralizing this avoids the classic Bitrix problem of dozens of ad-hoc ajax.php files with inconsistent error handling.

Shared behavior via a base class. Put cross-cutting concerns — auth checks, layout selection, common view variables, redirect helpers — in one project-level abstract page class that all your pages extend. That's the closest analog to Laravel middleware, and it's the main extension point you'll actually use.

Composition over inheritance for reusable chunks. For repeated page fragments prefer view partials or plain helper classes rather than deep page-class hierarchies; Bitrix's own component system already covers the "reusable widget" niche, so don't rebuild it.

Gotchas and Tips

• Archived and stale. Last release 2018, 11 stars, no maintainer. Treat it as vendored code you own. Expect friction on PHP 8+ (typed properties, create_function-era patterns, deprecated notices). Audit before adopting on a new project; on an existing one, isolate it behind your own base class so you can replace it.
• Autoloader collisions. Bitrix has its own autoload conventions and a lot of global classes. Namespace your page classes properly and confirm Composer's autoloader is actually loaded before the dispatcher runs — a silently missing autoloader shows up as a blank page or a 404, not a clear error.
• urlrewrite.php is cached. Bitrix caches the rewrite rules; after editing them, clear the managed cache (/bitrix/admin/cache.php or $GLOBALS['CACHE_MANAGER']->cleanAll()). A "my route doesn't work" report is usually a stale rewrite cache, not a code bug.
• Composite cache can bypass your page class. If the site uses composite caching, the cached HTML is served before your PHP runs at all. Anything dynamic (per-user content, CSRF-ish tokens) needs to be excluded from the composite cache for that page, or you'll chase ghosts.
• Global state, not request state. $USER, $APPLICATION, and $DB are process-wide globals. Code that's clean in a Laravel request lifecycle can leak here — especially if you test multiple pages in one PHP process, or under Bitrix's CLI/agent runners. Prefer passing dependencies in over reading globals deep inside helper methods.
• Error visibility. Bitrix's exception handling will often swallow or genericize errors into an error page. During development, turn on debug in .settings.php / dbconn.php ('debug' => true, exception handling off) — otherwise a bug in a page class looks identical to a 404.
• Testing. The usual Laravel toolkit (HTTP tests, factories) doesn't transfer. arrilot/bitrix-test (same author, also stale) is the pragmatic option for unit-testing page classes; without it, keep page classes free of direct global access so they're at least testable in isolation.
• Extension points to rely on: your own abstract base page class (auth, layout, shared vars), view resolution overrides if you want a different template layout convention, and the dispatcher registration file. Avoid patching the package in vendor/ — fork it into a local path repository instead so updates (if any ever land) don't clobber you.
• Don't fight Bitrix's component system. Hermitage orchestrates pages; it does not replace components, the cache manager, or the module system. Teams that try to route everything through page classes end up reimplementing half of Bitrix badly.