З Elementor у Laravel Blade: як перевести сайт на конструкторі скриптом
Конвертер, шар рядків і перемикання на віртуальному хостингу, з кодом із робочого проєкту
Це технічний бік проєкту, який ми для клієнтів описали в кейсі IFHRS. Міжнародна федерація товариств із дослідження волосся (IFHRS) мала сайт на WordPress 7.1, зібраний в Elementor Pro, ACF Pro та Unlimited Elements. Федерації потрібен був сайт шістьма мовами її товариств і місце під особистий кабінет згодом. Ми перевели його на Laravel 13.42 і PHP 8.3, власного PHP вийшло близько 2200 рядків.
Увесь код нижче взято з цього проєкту. Для статті окремо нічого не писали.
ЗАВДАННЯ
Що мало лишитися незмінним
Завдання вміщалося в одне речення: відвідувачі й пошуковики не мають помітити нічого, крім того, що сайт став швидшим і заговорив більшою кількістю мов. На ділі це означало чотири незмінні точки.
- Той самий дизайн до пікселя, разом із розміткою та CSS самого Elementor.
- Ті самі 39 адрес, зі слешем у кінці, бо саме так їх проіндексував Google.
- Той самий віртуальний хостинг: один корінь сайту, Apache, ні другого сервера, ні конвеєра викладання.
- Повернення за хвилини, без відновлення з бекапу.
Хто йшов із конструктора, знає звичний шлях: наново зверстати дизайн у новій темі, а потім тижнями ловити візуальні розбіжності. Такі умови цей шлях відсікають. Перезібрана тема ніколи не збігається до пікселя, а де саме вона розходиться, видно лише тоді, коли на сайт заходять живі люди.
СПЕЦИФІКАЦІЯ
Опублікований HTML як специфікація
Ми почали з єдиної версії дизайну, яка гарантовано правильна: з того, що WordPress справді віддає анонімному відвідувачу. Ми зберегли HTML кожної сторінки саме в тому вигляді, у якому його віддає сайт, і вважали ці файли специфікацією.
Збережені файли працювали двічі. Вони були входом конвертера й еталоном, з яким звірялася кожна наступна перевірка. Розмітка Elementor багатослівна, зате детермінована, і її класи, обгортки та вбудовані налаштування саме те, чого чекає його CSS. Зберегти їх означало зберегти вигляд задарма.
Сайт на конструкторі не перемальовують. Переносять те, що він уже публікує.
Змінити треба було місце, де живуть слова. У WordPress вони лежать усередині JSON-дерева Elementor у базі, упереміш із налаштуваннями верстки. У Laravel вони мали стати рядками, які перекладач править, не торкаючись розмітки.
КОНВЕРТЕР
Текст назовні, токени всередину
Конвертер написаний на Python і Beautiful Soup. Він проходить кожну збережену сторінку й замінює видимий текст викликами хелпера Blade tx(). Найцікавіше рішення тут у тому, що вважати одним рядком.
Перекладач має бачити ціле речення з посиланням і виділенням, а не три уривки. Тому скрипт працює одиницями: елемент, усередині якого лише рядкові теги й текст, стає одним рядком разом із цими тегами.
INLINE = {"a", "span", "strong", "b", "em", "i", "br", "sup", "sub", "small", "u", "mark", "abbr", "time", "code", "wbr"}
def is_unit(self, el):
has_text = False
for d in el.descendants:
if isinstance(d, Comment):
continue
if isinstance(d, NavigableString):
if d.strip():
has_text = True
elif isinstance(d, Tag) and d.name not in INLINE:
return False
return has_text
Сам обхід короткий. Голі текстові вузли стають токеном, одиниці очищуються й отримують один токен, усе інше обходиться глибше. Скрипти, стилі, SVG, iframe і поля форм пропускаються.
def walk(self, el):
for c in list(el.children):
if isinstance(c, NavigableString):
t = c.strip(WS)
if t and not LITERAL.match(t):
c.replace_with(NavigableString("{!! tx('%s') !!}" % self.key(t)))
continue
if self.is_unit(c): # only inline tags and text inside
inner = "".join(str(x) for x in c.contents).strip(WS)
c.clear()
c.append(NavigableString("{!! tx('%s') !!}" % self.key(inner)))
else:
self.walk(c)
Ще три правила тримають результат чистим:
- Текст в атрибутах, який читають люди (
alt,title,aria-label,placeholder), отримує екрановану форму{{ tx('...') }}. - Ключі короткі й свої в кожної сторінки (
p.1,p.2і далі). Функція ключа спершу шукає значення, тож речення, що повторюється на сторінці, отримує той самий ключ і перекладається один раз. - Рядки, де нічого перекладати (числа, дати цифрами, роздільники), збігаються з шаблоном
LITERALі лишаються в розмітці.
У підсумку вийшов один шаблон Blade на сторінку й один JSON-файл рядків на сторінку й мову: близько 1130 рядків на мову в 40 файлах.
ПОСИЛАННЯ
Два види внутрішніх посилань
Внутрішні посилання змінюються разом із мовою, тож жодна адреса не може лишитися зашитою. Конвертер переписує кожне посилання на відому сторінку й записує його в одній із двох форм, залежно від того, де воно стоїть.
if k:
return ("[[url:%s]]" % k if in_text else "{{ lurl('%s') }}" % k) + frag
return path + frag
У шаблоні href стає викликом Blade {{ lurl('mission') }}. Усередині рядка для перекладу він стає токеном [[url:mission]], який підставляється під поточну мову під час виведення. Перекладач ніколи не править адресу, а перенесення сторінки ніколи не вимагає чіпати шість перекладів. Посилання на завантаження й файли теми лишаються звичайними шляхами, посилання на інші сайти не змінюються.
Хелпер адрес зберігає звичку WordPress ставити слеш у кінці кожної сторінки:
public static function url(string $page, ?string $locale = null): string
{
$locale ??= app(self::class)->locale;
$path = $page === 'home' ? '' : $page;
$prefix = $locale === config('ifhrs.default_locale') ? '' : $locale;
$u = '/'.trim($prefix.'/'.$path, '/');
return $u === '/' ? $u : $u.'/'; // /mission/, /uk/mission/, /uk/
}
Усе, на що раніше відповідав WordPress, отримує 301: адреси .html старої статичної версії, wp-sitemap.xml із дочірніми картами, стрічки, архіви рубрик і міток, а також /?s= для пошуку. Нова карта сайту містить 234 адреси, 39 сторінок шістьма мовами, із посиланнями hreflang між ними.
ПАСТКИ BLADE
Що Blade намагається скомпілювати
Саме тут найчастіше спотикаються ті, хто пробує те саме. Виведення Elementor повне тексту, який Blade читає як власний синтаксис. Вбудовані правила @media і @keyframes стають директивами. JSON в атрибутах data-settings може містити {{, а це для Blade виведення змінної. Шаблон, що вчора збирався, ламається, щойно редактор додає анімацію.
Рішення в тому, щоб до запису шаблону екранувати все, крім власних токенів конвертера. Роботу роблять описані в документації екрани Blade: @{{ виводить фігурні дужки як є, а @@ виводить буквальний @ перед словом.
TOKEN = re.compile(r"(\{!! tx\('[^']+'\) !!\}|\{\{ tx\('[^']+'\) \}\}|\{\{ lurl\('[^']+'\) \}\})")
def blade_safe(html):
out = []
for part in TOKEN.split(html):
if TOKEN.fullmatch(part or ""):
out.append(part) # our own tx() / lurl() calls
else:
part = part.replace("{{", "@{{").replace("{!!", "@{!!")
part = re.sub(r"(?<![\w@])@(?=[a-zA-Z])", "@@", part)
out.append(part)
return "".join(out)
Перевірка назад тут важлива. Без неї скрипт подвоїв би @ усередині адреси пошти, якої Blade і так не чіпає, і на сторінці з'явилося б name@@domain.
РЯДКИ
Шар рядків замість lang-файлів
__() і lang-файли Laravel зроблені для рядків інтерфейсу: підписів кнопок, повідомлень валідації. Тут рядки завбільшки з фрагмент сторінки, з HTML усередині, і сторінка може бути перекладена лише частково. Тому шаблони викликають невеликий хелпер, за яким стоїть один клас, що читає resources/content/<locale>/<page>.json.
На двох правилах тримається весь шар. Пропущений або порожній рядок береться з англійської версії по одному рядку, а не цілою сторінкою, тож наполовину перекладена сторінка однаково показує кожне слово, і нічого не віддає 404 через недописану мову. А токени [[url:...]] підставляються під час виведення під поточну мову.
Оскільки рядки містять HTML, недбалий переклад може загубити закривальний тег і зламати верстку довкола. Тому кожен перекладений рядок порівнюється з англійським за формою, тобто за відсортованим списком його тегів і токенів посилань:
public static function shape(string $html): array
{
preg_match_all('/<\/?([a-z][a-z0-9]*)\b[^>]*>|\[\[[^\]]+\]\]/i', $html, $m, PREG_SET_ORDER);
$out = [];
foreach ($m as $x) {
if (str_starts_with($x[0], '[[')) {
$out[] = preg_replace('/\s+/', '', $x[0]); // [[url:mission]]
} else {
$out[] = (str_starts_with($x[0], '</') ? '/' : '').strtolower($x[1]);
}
}
sort($out);
return $out;
}
Якщо форми різняться, адмінка не зберігає саме цей рядок. Вона позначає поле й просить зберегти всі теги та посилання англійської версії, а решта форми зберігається як зазвичай. Сортування робить перевірку поблажливою до порядку слів, який в англійській і японській різний, і суворою до того, що важить для розмітки.
ЗВІРКА
Порівняння, а не скриншот
Перенесення варте рівно стільки, скільки його доказ, а «виглядає так само» доказом не є. Перед кожним рефакторингом ми рендерили всі 234 адреси й зберігали HTML. Після нього скрипт наново забирав ті самі адреси й порівнював їх байт у байт, виводячи перше місце, де версії розходилися.
def one(u):
a = open(f'{D}/snap_before/{fname(u)}').read()
b = get(u) # the same URL from the new build
if a == b:
return u, 'same', ''
i = 0
n = min(len(a), len(b))
while i < n and a[i] == b[i]: i += 1 # first differing character
j = 0
while j < n - i and a[-1-j] == b[-1-j]: j += 1
return u, 'diff', f'A:{a[max(0,i-100):len(a)-j][:400]!r}\n B:{b[max(0,i-100):len(b)-j][:400]!r}'
Це грубо, і це саме те, що потрібно під час переїзду. Сміливі рефакторинги стали дешевими. Звести шістнадцять зроблених вручну шаблонів конгресів в один вдалося перевірити однією командою, так само як і перенесення розсилок у записи. Останній повний прогін, уже з готовою адмінкою, показав 228 із 234 сторінок, що збігаються до байта; решта шість були однією навмисною правкою описів картинок на сторінці одного конгресу шістьма мовами.
Та сама ідея лягає в тест Pest, якщо зручніше тримати її в наборі тестів: один раз зняти знімки відповідей, а потім перевіряти, що $this->get($url)->getContent() збігається зі збереженим файлом для кожної адреси з карти сайту. Цей метод ми вже застосовували на ранішому переїзді й описали його в статті про перенесення статичного сайту на Laravel байт у байт.
БЕЗ СЕСІЙ
Публічні маршрути поза web
Публічний сайт однаковий для всіх відвідувачів, тож йому не потрібні ні сесія, ні cookie, ні токен CSRF. Замість того щоб знімати middleware з маршруту за маршрутом, ми зареєстрували публічні маршрути взагалі поза групою web, у колбеку then методу withRouting():
return Application::configure(basePath: dirname(__DIR__))
->withRouting(
web: __DIR__.'/../routes/web.php', // admin only: session, CSRF
commands: __DIR__.'/../routes/console.php',
health: '/up',
then: function () {
// Public pages: no session, no cookies (cache-friendly, nothing written per visit).
Route::middleware([])->group(base_path('routes/public.php'));
},
)
Адмінка живе в routes/web.php із повним набором middleware, а її cookie сесії обмежена шляхом /admin. Публічна відповідь не несе заголовка Set-Cookie, тож будь-який CDN, поставлений перед сайтом пізніше, зможе кешувати її як є.
Публічні сторінки не чіпають і базу. Тексти й записи лежать у JSON-файлах, а в базі лише те, що потрібно адмінці: користувачі та історія правок. Там, де WordPress виконував від 160 до 210 запитів на головну, Laravel не виконує жодного, і сервер відповідає від п'яти до дев'яти разів швидше. Повна таблиця в кейсі.
ПЕРЕМИКАННЯ
Віртуальний хостинг без простою
У віртуального хостингу один корінь сайту й немає перемикача між серверами. Переїзд зробили безпечним три невеликі деталі.
Прокладка перед фронт-контролером. Застосунок Laravel лежить поруч зі старим коренем сайту, а файл із трьох рядків у цьому корені передає йому запити:
<?php
// www/_lv.php: every request routed here runs the Laravel app
require __DIR__.'/../app/public/index.php';
Попередній перегляд на справжньому домені. До перемикання хто що бачить, вирішувала cookie. Секретна адреса її ставила. Браузери з нею отримували Laravel, усі інші, разом із Googlebot, і далі отримували WordPress. Ми перевіряли новий сайт на його справжньому домені, зі справжніми файлами й адресами, стільки, скільки було треба.
RewriteRule ^_lv\.php$ - [L]
RewriteRule ^lv-preview-<secret>(-off)?$ /_lv.php [L]
RewriteCond %{HTTP_COOKIE} (^|;\s*)ifhrs_lv=1(;|$)
RewriteCond %{REQUEST_URI} !^/(wp-admin|wp-includes|wp-content|wp-json|wp-login\.php)
RewriteRule ^ /_lv.php [L]
Саме перемикання замінило цей блок правилом, яке відправляє на прокладку кожен нестатичний запит. WordPress переїхав на піддомен old. з тими самими файлами й базою, закритий заголовком X-Robots-Tag: noindex і без аналітики. Повернутися назад означає знову поміняти блок: хвилини, а не відновлення.
Фіксація платформи в Composer. Хостинг запускає PHP 8.3 для сайту й 8.4 у командному рядку. Без фіксації composer update у консолі підбирає пакети, яким потрібен 8.4, і сайт падає на наступному запиті з браузера. Одне налаштування в composer.json змушує Composer підбирати пакети під ту версію, що віддає сторінки:
"config": {
"platform": { "php": "8.3.36" }
}
На віртуальному хостингу Composer часто запускає не той PHP, що віддає сторінки.
ВИСНОВКИ
Що ми б повторили
Порядок виявився важливішим за будь-який окремий інструмент. Заморозити опубліковане, зробити порівняння автоматичним і лише потім покращувати. Кожен крок був достатньо малим, щоб його перевірити, і порівняння ловило кожну помилку раніше за відвідувача.
Поки що не змінилася вага сторінок у браузері. Сторінки досі вантажать CSS і JavaScript Elementor, бо цей етап обіцяв ті самі пікселі. Замінити їх власними файлами зі звіркою за скриншотами, а не за байтами, належить на наступному етапі. Після цього форми зворотного зв'язку переїдуть у Laravel, і стару копію можна буде вимкнути.
Якщо ваш сайт теж тримається на конструкторі й застарілому стеку, наші команди розробки на Laravel і модернізації сайтів роблять такий переїзд без редизайну.
FAQ
Часті запитання
Чи можна автоматично перевести сторінки Elementor у Blade?
Так, якщо переводити опублікований HTML, а не JSON Elementor. Скрипт може винести видимий текст у мовні файли й зберегти розмітку, якщо він екранує синтаксис Blade, захований у CSS і налаштуваннях Elementor.
Чи потрібен CSS Elementor після переведення?
Спочатку так: розмітка зберігає класи Elementor, і його стилі тримають вигляд. Заміна їх власним CSS іде окремим етапом зі звіркою за скриншотами, бо вона якраз має змінювати байти.
Чому не lang-файли Laravel для текстів сторінок?
Lang-файли пасують коротким рядкам інтерфейсу. Тексти сторінок це фрагменти HTML із посиланнями й оформленням, перекладені частково й редаговані людьми, тож їм більше пасує JSON-файл на сторінку з англійською підстановкою для кожного рядка.
Як довести, що після переїзду нічого не змінилося?
Зберегти HTML кожної адреси до змін, забрати ті самі адреси після й порівняти байт у байт. Тест Pest зі збереженими знімками робить те саме всередині набору тестів.
Джерела
- Laravel 13: налаштування маршрутизації
- Laravel 13: Blade і JavaScript-фреймворки
- Composer: налаштування platform
- Документація Beautiful Soup
Сайт застряг у конструкторі? Подивімося, що потрібно, щоб перевести його на Laravel.
Раз на тиждень одне сповіщення з новими статтями PERETZ. Нічого зайвого.