PHPTime

Правила именования CSS-классов и организации файлов стилей

Хаотичные имена классов и бессистемное подключение стилей превращают поддержку интерфейса в угадайку. Правила ниже проверены на крупных проектах и помогают исключить конфликты, упростить отладку и сделать поведение вёрстки предсказуемым. Они не гонятся за идеалом для браузерного рендеринга: накладные расходы минимальны, а выгода для команды ощутима сразу.

Базовые соглашения: классы и имена файлов

Все имена CSS-классов и файлов пишем в нижнем регистре. Слова внутри имени разделяем дефисом. Такой подход совпадает с тем, как большинство разработчиков именуют директории и PHP-файлы, поэтому порог входа практически нулевой.

CSS
/* Хорошо */
.widget-latest-comments {}
.post-view {}

/* Плохо */
.widgetLatestComments {}
.post_view {}

Имена файлов оформляем по тому же принципу: post.css, widget-latest-comments.css, markdown.css. Никаких camelCase, нижних подчёркиваний и пробелов.

Структура CSS-файлов в проекте

Раскладываем стили по отдельным файлам с чёткой зоной ответственности. Это упрощает навигацию и ревью. Рекомендуемая структура для типичного PHP-приложения на фреймворке:

  • global.css — глобальные стили: сброс, типографика, кнопки, утилиты. Всё, что переиспользуется в разных местах.
  • layout.css — стили базовых макетов: шапка, подвал, боковые колонки, основная сетка.
  • ControllerID.css — файл, привязанный к конкретному контроллеру. Для PostController создаём post.css.
  • widget-WidgetClass.css — стили конкретного виджета. Например, LatestComments обращается к widget-latest-comments.css.
  • FeatureName.css — крупные обособленные функции. Например, редактор Markdown использует markdown.css.

Отдельно подключаем файлы сторонних библиотек и CSS-фреймворков — их не смешиваем с собственным кодом.

Правила именования CSS-классов

Для стилизации элементов используем классы, а не id. Идентификатор может встречаться на странице только один раз, класс — сколько угодно. Это особенно важно в PHP-шаблонах, где один и тот же блок часто рендерится в цикле.

Общие классы

Переиспользуемые классы начинаем с префикса g- и размещаем в global.css:

CSS
.g-submit-button {
    padding: 0.5rem 1.25rem;
    border-radius: 6px;
}

.g-link-button {
    text-decoration: none;
}

Префикс сразу подсказывает, что класс лежит в глобальном слое и его изменение может затронуть весь проект.

Корневой контейнер представления

Каждый файл, который выводит контент, оборачиваем в корневой контейнер с классом, повторяющим путь до шаблона. Это создаёт локальное пространство имён для стилей и исключает конфликты между разными разделами.

Для представления post/index.php корневой контейнер выглядит так:

PHP
<div class="post-index">
    <?php foreach ($posts as $post): ?>
        <article class="item">
            <h2><?= htmlspecialchars($post->title, ENT_QUOTES) ?></h2>
        </article>
    <?php endforeach; ?>
</div>

Стили размещаем в post.css, и каждое объявление начинается с имени корневого контейнера:

CSS
/* post.css */
.post-index .item {
    margin-bottom: 1.5rem;
}

Виджеты

Для виджетов работает та же схема. Виджет LatestComments получает корневой класс widget-latest-comments и обращается к файлу widget-latest-comments.css:

PHP
<aside class="widget-latest-comments">
    <?php foreach ($comments as $comment): ?>
        <div class="comment">
            <?= htmlspecialchars($comment->text, ENT_QUOTES) ?>
        </div>
    <?php endforeach; ?>
</aside>
CSS
/* widget-latest-comments.css */
.widget-latest-comments .comment {
    border-left: 3px solid #e2e8f0;
}

Макеты

Файл макета тоже получает корневой контейнер с префиксом layout-. Макет main использует класс layout-main. Чтобы избежать конфликтов с контентными классами, внутренние элементы макета начинаются с имени корневого контейнера:

PHP
<body class="layout-main">
    <header class="layout-main-header">...</header>
    <main class="layout-main-content">...</main>
    <footer class="layout-main-footer">...</footer>
</body>

Это правило удерживает стили макета от пересечения со стилями внутренних представлений.

Подключение CSS-файлов в PHP-контроллере

Современные PHP-приложения управляют ассетами через встроенный механизм фреймворка. Жёстко прописывать <link> в шаблоне не нужно — вместо этого регистрируем файлы в коде.

Пример регистрации набора стилей через абстрактный менеджер ассетов:

PHP
declare(strict_types=1);

final readonly class AssetManager
{
    /**
     * @param list<string> $cssFiles
     */
    public function register(array $cssFiles): void
    {
        foreach ($cssFiles as $file) {
            if (!str_ends_with($file, '.css')) {
                throw new InvalidArgumentException(
                    "Некорректный CSS-файл: {$file}"
                );
            }
            // Здесь — добавление в очередь вывода или регистрация в шаблоне
        }
    }
}

В конфигурации приложения храним список файлов отдельно от логики:

PHP
return [
    'assets' => [
        'css' => [
            'global.css',
            'layout.css',
            'post.css',
            'widget-latest-comments.css',
        ],
    ],
];

Продакшен: объединение и сжатие

В режиме разработки подключаем каждый CSS-файл отдельно — так проще отлаживать. В продакшене объединяем и минифицируем стили в один файл. Это сокращает число HTTP-запросов и ускоряет загрузку страницы.

Итоговому файлу даём имя с временной меткой, например styles-202611221550.css. Браузер кэширует такой файл и не запрашивает его повторно, пока не изменится имя.

Собираем файл консольной PHP-командой. Логика простая: читаем список из конфигурации, склеиваем содержимое, прогоняем через минификатор и записываем результат:

PHP
declare(strict_types=1);

final class CssBuildCommand
{
    public function run(): void
    {
        $files = [
            'global.css',
            'layout.css',
            'post.css',
        ];

        $combined = '';
        foreach ($files as $file) {
            $content = file_get_contents(__DIR__ . '/css/' . $file);
            if ($content === false) {
                throw new RuntimeException("Не удалось прочитать {$file}");
            }
            $combined .= $content . PHP_EOL;
        }

        // Здесь вызывается минификатор — например, класс-обёртка над библиотекой
        $minified = (new CssMinifier())->minify($combined);

        $filename = 'styles-' . date('YmdHi') . '.css';
        file_put_contents(__DIR__ . '/css/' . $filename, $minified);

        // Обновляем параметр в конфигурации приложения
        $this->updateConfig($filename);
    }
}

В основном макете проверяем, собран ли общий файл. Если да — подключаем только его, если нет — перебираем список из конфигурации:

PHP
<head>
    <?php if ($cssCompressed): ?>
        <link rel="stylesheet" href="<?= htmlspecialchars($cssBaseUrl . '/' . $cssCompressed, ENT_QUOTES) ?>">
    <?php else: ?>
        <?php foreach ($cssFiles as $css): ?>
            <link rel="stylesheet" href="<?= htmlspecialchars($cssBaseUrl . '/' . $css, ENT_QUOTES) ?>">
        <?php endforeach; ?>
    <?php endif; ?>
</head>

Именование jQuery- и JS-селекторов

Правила для CSS-классов распространяются и на селекторы в JavaScript. При выборке элементов начинаем с имени корневого контейнера, а не с голого класса .item или тега a.

Если нужно повесить обработчик клика на ссылки внутри новостных блоков, селектор строится с учётом контекста:

JS
// Привязываемся к контексту представления
$('.news-index .item a').on('click', function () {
    // ...
});

Такой подход гарантирует, что обработчик не зацепит случайные элементы из других разделов, даже если там встречаются те же классы.

Чек-лист внедрения

  • Классы и файлы называем строчными буквами через дефис.
  • Общие переиспользуемые стили кладём в global.css с префиксом g-.
  • Каждое представление оборачиваем в корневой контейнер с классом, совпадающим с путём до шаблона.
  • Стили представления начинаются с имени корневого контейнера.
  • Виджеты получают префикс widget- и отдельный файл.
  • Макеты используют префикс layout-, внутренние элементы наследуют корневое имя.
  • В разработке подключаем файлы по отдельности, в продакшене — один минифицированный файл с временной меткой.
  • Селекторы в JavaScript строим от корневого контейнера.

Частые вопросы

Почему для стилей лучше использовать классы, а не id?

Идентификатор может встречаться на странице только один раз, а класс — сколько угодно. В PHP-шаблонах один и тот же блок часто выводится в цикле, поэтому классы гораздо практичнее и не создают ограничений.

Зачем нужен префикс g- у глобальных классов?

Он сразу показывает, что класс лежит в global.css и используется в разных местах. При правке таких классов разработчик понимает, что изменения могут затронуть весь проект, а не только отдельный раздел.

Как правильно подключать CSS в продакшене?

Стили объединяют в один файл, минифицируют и добавляют в имя временную метку. Браузер кэширует такой файл и не запрашивает его повторно, пока не изменится имя. Подключение лучше выполнять через менеджер ассетов фреймворка.

Нужно ли следовать этим правилам в JavaScript-селекторах?

Да. Селекторы следует строить от имени корневого контейнера представления. Это привязывает выборку к конкретному разделу и предотвращает случайное срабатывание обработчиков на элементах из других блоков.

Справка по теме

Ещё в разделе «Фронтенд»

Система сборки фронтенда для PHP-проекта: от Grunt до современных таск-раннеров

Как подключить систему сборки CSS и JavaScript к бэкенду на PHP 8.3–8.5: минификация, конкатенация, версионирование ассетов и автодеплой в 2026 году.

6 мин

Stylus в 2026 году: стоит ли использовать CSS-препроцессор в современной разработке

Разбираем CSS-препроцессор Stylus в реалиях 2026 года: установка, синтаксис, БЭМ, миксины, подводные камни и сравнение с Sass. Практический чек-лист для разработчика.

5 мин

HTML5-видео на сайте: форматы, кодеки, конвертация ffmpeg и оптимизация загрузки

Практический разбор HTML5-видео в 2026: конвертация в MP4/H.264, WebM/VP9/AV1 через ffmpeg, тег source, постер и lazy-loading для быстрой загрузки.

8 мин

Генерация спрайтов в Stylus: практическое руководство для PHP-разработчика

Как автоматизировать генерацию CSS-спрайтов при работе со Stylus в 2026 году. Обзор актуальных инструментов, настройка сборки и примеры кода для PHP-разработчика.

8 мин