Максим Кузнецов

[Инструкция] Как работать с Git

Максим Кузнецов — Tue, 15 Jul 2025 11:15:15 +0300

(Это инструкция, которую приходится копировать из проекта в проект, поэтому размещаю и в блоге.)

Gitflow

Идейно система работы с ветками берётся из Gitflow, но с упрощениями.

Общее

В нашем проекте ветка develop — ветка, которая содержит стабильный результат, который можно зарелизить на прод.

Следуя этому принципу, в рамках работы по спринту в ветку develop вливаются фичи/задачи:

стабильного качества (по мнению разработчика (всегда) и менеджера (аппрув менеджера требуется, если этого требует конкретная задача);
из спринта, который в работе (то есть те задачи, которые должны быть в ближайшем релизе).

Если ведется работа по фиче, которая не войдет в ближайший релиз, она не вливается в develop. Тестирование такой задачи можно проводить, подключая ветку фичи на свободную дев площадку (не вливая ее в develop ветку).

Правила именования

Каждый коммит и пулл-реквест должны именоваться в следующем формате:

[Sentry] EDS-1004: <пояснение>

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

EDS-1004 — даёт понимание по какой задаче была изменена строка в кода (через git blame), а потом по задаче можно найти ПОЧЕМУ это было сделано.
Плюс почти все таск-трекеры позволяют сконнектиться с Gitlab/Github/etc, и тогда коммиты и ПРы будут показываться в таск-трекре. А в Gitlab/Github все упоминания задач будут отображаться ссылками на таск-трекер автоматически.

Работа с ветками

Из ветки main (или аналогичных prod/master) создается ветка develop.
На каждую фичу создаётся новая ветка вида feature/XXX-short-description от ветки develop. XXX — номер задачи из таск-трекера, — краткое описание задачи на английском языке. Например: `feature/TASK-1777-change-forms-for-clients`.
Когда фича готова (это значит, что разработчик считает, что фича выполнена корректно и протестирована локально) ветка фичи отправляется через Пулл-реквест в ветку develop. При создании Пулл-реквеста обязательно нужно выбрать галку «удалить ветку после мерджа», чтобы не разводить кладбище веток в git.
Разработчик не забывает регулярно подтягивать ветку develop в свою ветку фичи в процессе разработки, чтобы уменьшить количество конфликтов при последующем MR в develop.
Для релиза ветку develop мерджим в ветку main через MR в Gitlab/Githab/etc.
Если в ветке prod обнаруживается критичный баг, то от main создается ветка hotfix/XXX-short-description.
Как только исправление на ветке hotfix завершено, она мержится с ветками main, а затем с develop.
После каждого мерджа тестируем в первую очередь новый функционал, потом все остальное.
Если разработчик не успевает сделать свою задачу до релиза, то ветка фичи не мерджится в ветку develop.
Если фича большая и не попадает в ближайший релиз, то разработку продолжаем в той же ветке под фичу, пока ее полностью не сделаем. Не забываем делать git pull, чтобы подтягивать все изменения c ветки develop. Это позволит подтягивать все изменения текущего спринта и разрешать конфликты как можно быстрее. Свою задачу можно протестировать на стейдже, залив её туда без мерджа.

[Инструкция] Как деплоить проект через Deployer

Максим Кузнецов — Tue, 15 Jul 2025 10:54:36 +0300

(Инструкция, которую приходится копировать из проекта в проект, поэтому пусть будет и в блоге.)

Предполагается, что Deployer доступен уже в проекте, либо как файл `./dep`, либо как установленный composer пакет через `./vendor/bin/dep`. Он добавляется и хранится в гит-репозитории.

Также важно настроить конфиги, указав хост в `./deploy.php`. Они также хранятся в репозитории.

Обычные / регулярные деплои

`./dep deploy `, где в качестве можно выбрать любой хост из deploy.php файла. В этом файле у хоста указана нужная ветка. Однако, делать это обычно не нужно, так как на проекте настрое Gitlab CI (см файл `.gitlab-ci.yaml`), который зарелизит код по коммиту.

Как сменить деплой-ветку для хоста

Предположим, вы хотите сменить на `dev` ветку с `develop` на `feature/TASK-82-history-mypractice`.

Простой и быстрый вариант для быстрых тестов

Вы можете это сделать, поменяв `→set(’branch’, ’feature/TASK-82-history-mypractice’)` в deploy.php для хоста `dev`, а потом запустить `./dep deploy dev`.

Этот способ хорош, если хочется быстро показать ветку, и мы не ожидаем, что будет много фиксов, так как Gitlab CI всё ещё останется настроен на `develop` ветку. И поэтому:

при коммите в `develop` ветку, Gitlab CI запустит `./dep deploy dev` и задеплоит `feature/TASK-82-history-mypractice` на `dev`. Но это неправильно, так как мы не хотим деплоить эту ветку на дев по коммиту в `develop`, мы хотим деплоить по коммиту в ветку `feature/TASK-82-history-mypractice`
при коммите в `feature/TASK-82-history-mypractice` ветку CI ничего не сделает, так как в версии конфига `.gitlab-ci.yaml` из этой ветки нет никакого правила для ветки `feature/TASK-82-history-mypractice`.

Правильный вариант с обновлением Gitlab CI правил

Переключиться в `develop` ветку, изменить branch в deploy.php для нужного хоста и в `.gitlab-ci.yaml` изменить параметр `only:` для этого же хоста.
Закоммитить. CI теперь не запустит деплой на `dev`, так как мы поменяли ветку на `feature/TASK-82-history-mypractice`.
Переключиться в ветку `feature/TASK-82-history-mypractice` в git и вмерджить в неё свежий `develop`. Вместе с develop придут изменения для `deploy.php` и `.gitlab-ci.yaml`. Поэтому если сразу закоммитить вмёрдженное, то Gitlab CI запустит деплой feature-ветки на `dev`.
Важно! Перед мерджем ветки в `develop` нужно изменить `deploy.php` и `.gitlab-ci.yaml` и заменить feature-ветку в них обратно на `develop`. Потом смерджить и Gitlab CI, увидев этот коммит в develop, сразу продеплоит `develop` на `dev`.

Как переключить хост с feature1-ветки на другую feature-2 ветку:

Переключиться в develop ветку и изменить в ней `deploy.php` и `.gitlab-ci.yaml`, указав feature2 вместо feature1 для нужного хоста.
Вмерджить develop ветку сначала в feature1 ветку, потом в feature2 ветку.

Удобные команды

`./dep ssh ` — команда подключится к хосту по конфигу из deploy.php и сделает перейдёт в папку current релиза.
`./dep run «»` — запускает команду на удалённых серверах. После запуска она спросит на каких серверах запустить.
`./dep ` — запускает любую определённую в deploy.php `task(’’, )` на нужно сервере.
Можно указать «теги» для серверов и запускать всё выше написанное сразу пачками.

Первый деплой / создание окружения

`./dep deploy develop2` — первый раз закончится с ошибкой, но Deployer создаст структуру файлов по пути из deploy.php для develop2. Он создаст папки
1. `/var/www/dev.project.name/releases` — тут будут располагаться папки с каждым новым релизом и копиться последние N штук.
2. `/var/www/dev.project.name/shared` — тут хранятся файлы, которые должны быть сохранены и перенесены между релизами. Например, логи, web/assets, storage, etc. Эти папки задаются в deploy.php как shared_folder и shared_files. Во время деплоя эти папки будут заменены на симлинки из shared папки.
3. `/var/www/dev.project.name/current` — симлинк на последний успешный релиз из папки releases.
После создания структуры нужно перенести/создать файлы в shared:
1. `./shared/.env`
2. `./shared/web/XXXXXXX` — можно посмотреть, какие папки создадутся на сервере, либо какие папки указаны в shared_folder в deploy.php (с учётом тех, что указаны во фреймворк-специфичном recipe, подключённом в deploy.php).
Повторить деплой `./dep deploy develop2`
Также нужно залить данные в БД / импортнуть из sql дампа по параметрам из `.env`.

Удаление старых локальных веток в Git-репозитории

Максим Кузнецов — Thu, 27 Feb 2025 22:57:05 +0300

На долгих проектах при следовании gitflow или похожих подходов с feature-ветками часто накапливаются локальные ветки, которые уже были смёрджены в develop.

Старые ненужные ветки можно удалить одной командой:

git branch --merged develop | grep -v "^\*\\|develop\\|main\\|master" | xargs -n 1 git branch -d

При этом текущие ветки, несмердженные в develop, останутся.

Установка и настройка Clickhouse на EC2

Максим Кузнецов — Mon, 13 Nov 2023 15:14:10 +0300

Нашёл отличный и исчерпывающий гайд по установке и подготовке Clickhouse для продакшена на AWS EC2.
Допустим, у нас уже есть VPC, в которую хочется добавиться сервер с CH.
Единственно, в качестве инстанса я взял машину попроще — m7g.large (~$60/mo) на Ubuntu и Arch64 архитектуре.

https://anthonynsimon.com/blog/clickhouse-deployment/

Как узнать общий вес базы данных и найти самые тяжёлые таблицы

Максим Кузнецов — Tue, 31 Oct 2023 12:13:08 +0300

Вес баз данных

SELECT table_schema AS "Database", 
ROUND(SUM(data_length + index_length) / 1024 / 1024 / 1024, 2) AS "Size (GB)" 
FROM information_schema.TABLES 
GROUP BY table_schema;

Размер таблиц, включая отдельно данные и отдельно индексы.

SELECT CONCAT(table_schema, '.', table_name),
       CONCAT(ROUND(table_rows / 1000000, 2), 'M')                                    `rows`,
       CONCAT(ROUND(data_length / ( 1024 * 1024 * 1024 ), 2), 'G')                    DATA,
       CONCAT(ROUND(index_length / ( 1024 * 1024 * 1024 ), 2), 'G')                   idx,
       CONCAT(ROUND(( data_length + index_length ) / ( 1024 * 1024 * 1024 ), 2), 'G') total_size,
       ROUND(index_length / data_length, 2)                                           idxfrac
FROM   information_schema.TABLES
ORDER  BY data_length + index_length DESC
LIMIT  20;

Как добавить новый сервис в systemd/systemctl и запускать его при старте Ubuntu

Максим Кузнецов — Wed, 10 May 2023 17:35:55 +0300

Задача

Есть docker-compose файл, поднимающий Zabbix. Есть небольшая обёртка в виде Makefile, которая позволяет запускать и останавливать docker-compose. Нужно добавить запуск этой команды при старте/рестарте системы.

Дано

Всё лежит в `/var/www/zabbix-server/`.
Содержание файла Makefile:

...
docker-up:
        docker-compose up -d

docker-down:
        docker-compose stop

Решение

Создать новый файл `vim /etc/systemd/system/zabbix.service`.

[Unit]
Description=Run Zabbix Docker Containers on Startup

[Service]
RemainAfterExit=True
Restart=always
RestartSec=1
WorkingDirectory=/var/www/zabbix-server
ExecStart=/usr/bin/make docker-up
ExecStop=/usr/bin/make docker-down

[Install]
WantedBy=default.target

chmod 644 /etc/systemd/system/zabbix.service
systemctl enable zabbix.service
systemctl start zabbix.service

Ubuntu: Running Out of Space и количество inodes

Максим Кузнецов — Sun, 13 Mar 2022 04:25:22 +0300

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

Проверить количество используемых inodes можно командой:

root@ec2-consumer:~# df -ih
Filesystem     Inodes IUsed IFree IUse% Mounted on
/dev/root        2.5M  2.1M  419K   84% /
devtmpfs         482K   349  482K    1% /dev
tmpfs            484K     5  484K    1% /dev/shm
tmpfs            484K   602  483K    1% /run
tmpfs            484K     4  484K    1% /run/lock
tmpfs            484K    18  484K    1% /sys/fs/cgroup
/dev/loop1         16    16     0  100% /snap/amazon-ssm-agent/4046
/dev/loop5        11K   11K     0  100% /snap/core18/2253
/dev/nvme1n1      25M  462K   25M    2% /var/www
tmpfs            484K    22  484K    1% /run/user/0

Видим 84% около /dev/root — процент очень большой, это свидетельствует о проблеме. Обычно должно быть не больше 50%, а 80% — это верхний предел.

Причин может быть несколько, например, у вас есть какой-то скрипт, пишущий много логов или временных файлов в /tmp. В моём случае это была библиотека phrets, которая создаёт много пустых временных файлов в /tmp.

Если не знаете, где превышаете лимит по количеству файлов, запустите команду (может занять несколько минут):

du --inodes -d 3 / | sort -n | tail

Быстрое решение

Просто удалите лишние файлы. Это можно сделать по шаблону regexp:

find /tmp -type f -mtime +0 -name 'phrets*' -execdir rm -- '{}' \;

Здесь -mtime +0 фильтрует все файлы, которые были созданы больше суток назад — я не хотел удалять все файлы, так как не был уверен, что библиотека phrets не использует самые свежие для чего-то нужного (хотя они все и были пустыми). Почитайте про значения параметра mtime, чтобы фильтровать как давно созданные файлы, так и недавно.

Долгое решение

Нужно увеличить количество inodes. Это крайне редкое и радикальное решение, которое хорошо описано тут — https://www.ctrl.blog/entry/how-to-all-out-of-inodes.html.

Как узнать размер бакета на AWS S3

Максим Кузнецов — Tue, 19 Oct 2021 18:00:43 +0300

К сожалению, AWS консоль (дэшборд) не даёт возможность узнать количество файлов и занимаемый объём. Это можно сделать через консоль:

aws s3 ls --summarize --human-readable --recursive s3://<bucket-name>

Бесплатный wildcard SSL-сертификат для поддоменов

Максим Кузнецов — Sun, 02 May 2021 18:05:26 +0300

Для простых веб-приложений достаточно одного домена (example.com). Однако для сложных систем, с разделением на бэкенд и фронтенд части, с лендингами, микросервисами и т. п. нужны поддомены, например: api.example.com, app.example.com, cdn.example.com.

Вместо того, чтобы выпускать отдельные сертификаты на каждый поддомен, мы можем выпустить один сертификат, покрывающий сразу все кейсы — *.example.com. Такой тип сертификатов называется Wildcard.

Как и в предыдущей статье про выдачу бесплатного SSL-сертификата, мы воспользуемся утилитой Certbot, который поможет нам выпустить и установить бесплатные SSL-сертификаты для наших поддоменов через центр Let’s encrypt.

Предполагаю, что вы уже настроили ваш сервер, чтобы поддомены были доступны по http (80 порт). Если вы не знаете, как это сделать, поищите статью по вашим ОС и веб-серверу на Digitalocean. Например, вот статья про установку и настройку Nginx на Ubuntu 20.04.

Заходим на сайт Certbot’а и выбираем ОС нашего сервиса и веб-сервер. Ниже в примере будет Ubuntu 20.04 и Nginx. Дальше выбираем таб Wildcard.

Предположим, что нам нужны следующие домены: example.com, api.example.com и app.example.com.
Запускаем по инструкции первые 8 шагов для установки самой утилиты:

// Удаляем snap, если он был установлен ранее
$ sudo apt-get remove certbot
// Устанавливаем snap
$ sudo snap install core; sudo snap refresh core
// Устанавливаем certbot
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot
$ sudo snap set certbot trust-plugin-with-root=ok

// Проверяем, что certbot установлен
$ certbot --version
> certbot 1.14.0

Для того, чтобы выпустить сертификаты, мы должны доказать удостоверяющему центру Let’s Encrypt, что мы действительно владеем данными доменами и сабдоменами. Есть два способа это сделать.

Добавить в DNS специальные txt записи, которые попросит нас добавить Let’s Encrypt, после этого он их проверит, и если записи будут обнаружены, это подтвердит факт владения (или по крайней мере доступа к ним). С чужими доменами так сделать не получится.
Webroot. Аналогичный способ, но специальные уникальные строки добавляются в файлы, которые потом должны быть доступны через URL, например: http://api.example.com/.well-known/acme-challenge/JH1kjoemxaS33d. Поскольку такой файл сможет добавить только владелец домена, этого тоже достаточно, чтобы Let’s Encrypt удостоверился в факте нашего владения.

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

Certbot поддерживает из коробки несколько популярных DNS-регистраторов (те сервисы, где можно купить домен), и тогда можно следовать по инструкции, однако в моём случае регистратором был Godaddy, который не поддерживается. Поэтому я воспользовался вторым способом и он оказался даже проще первого. Кроме того, данный способ надёжнее, так как не зависит, повезёт ли вам с поддержкой вашего регистратора или нет.

Для верификации доменов по webroot нам нужно настроить каждый домен/поддомен, чтобы он отдавал директорию /.well-known/acme-challenge/. В эту папку certbot запишет то, что нужно Let’s Encrypt, чтобы мы прошли проверку, поэтому убедитесь, что certbot имеет туда доступ.

Есть небольшой лайфхак, как упростить работу с этой папкой в конфигах сервера. Для этого мы создадим отдельный файл конфига, который будем подключать для каждого домена/поддомена. Пример для Nginx:

// создаём файл "/etc/nginx/letsencrypt.conf"
location /.well-known/acme-challenge {
    # Вместо `/var/www/acme-challenge` можно указать любую папку.
    # Она может быть недоступна извне, это неважно. Главное, чтобы туда имел доступ ваш текущий юзер.
    alias /var/www/acme-challenge/.well-known/acme-challenge;
}

Подключаем этот файл в конфигах доменов и поддоменов. Допустим, у вас есть файл /etc/nginx/sites-available/api.example.com (с остальными аналогично).

server {
    server_name api.example.com;
    include letsencrypt.conf;
    ...
}

Готово. Теперь домен будет все запросы, начинающиеся на /.well-known/acme-challenge будут направлены в папку /var/www/acme-challenge/.well-known/acme-challenge, общую для всех доменов/поддоменов.

Далее запускаем certbot, чтобы он пообщался с Let’s Encrypt, подтвердил наши домены, выпустил сертификаты и даже настроил наш веб-сервер на их использование.

certbot run -a webroot -i nginx -w /var/www/acme-challenge -d example.com -d api.example.com -d app.example.com

Разберём эти конфиги:

-a webroot — это способ аутентификации (подтверждение, что мы владеем доменами)
-i nginx — один из доступных способов установки сертификатов. В данном случае это nginx, так как именно этот веб-сервер мы используем. Certbot вам задаст несколько вопросов и после этого обновит конфиги. Делает он это очень умно, так что без разницы как эти конфиги у вас написаны. И даже устанавливает редирект http на https.
-w /var/www/acme-challenge — путь до папки, которая будет использоваться для webroot аутентификации. Обратите внимание, что именно эта папка прописана в /etc/nginx/letsencrypt.conf.
-d example.com -d api.example.com -d app.example.com — указываем все необходимые поддомены, обязательно первым указываем основной домен (не поддомен), иначе ничего не получится.

Всё, certbot всё сделал сам, даже перезагрузил веб-сервер. Можно зайти через браузер на поддомены и убедиться, что всё работает.

p.s. если браузер выдаёт ошибку, что такой домен не найден, то проверьте, что файрволл настроен на выдачу https трафика. Например, в Ubuntu 20.04 это делается через UFW:

// Проверяем, есть ли HTTPS в активных правилах
$ sudo ufw status
// Смотрим, какие правила могут быть включены
$ sudo ufw app list
// Включаем Nginx https
$ sudo ufw allow 'Nginx HTTPS'
// Проверяем, что правило появилось в активных
$ sudo ufw status

Как настроить php-cs-fixer и phpstan на локалке

Максим Кузнецов — Tue, 01 Dec 2020 17:34:55 +0300

Проблема 1

При совместной разработке (от 2х человек) code style становится критичным. Если каждый будет писать в своём стиле, вскоре проект превратится в бардак, где по разному стилю можно будет оценивать возраст кода будто по кольцам на деревьях.

На собеседованиях я часто слышу от кандидатов, что мы пользуемся проверками, встроенными в IDE. Но это полрешения, так как такие проверки носят рекомендательный, а не обязательный характер. Очень легко не заметить предложение по правке от IDE. А кроме того, приходится синхронизировать настройки IDE между всей командой. А что делать, если у кого-то другой редактор? Результат непредсказуем, а значит и ненадёжен.

Проблема 2

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

Решение

Нужно договориться об общих правилах с командой и автоматизировать процесс проверки кода, сделав её независимой от IDE, платформы, настроения, желания и внимательности человека.

Такие инструменты уже есть — code style и статические анализаторы кода.

Единый стиль кода

Поскольку я специализируюсь на Symfony, то для код-стайла выбираю PHP-CS-Fixer. Он написан при участии создателя Symfony и имеет из коробки поддержку рекомендованного сообществом Symfony Code Standards. Есть ещё PHPCodeSniffer, но он умеет только обнаруживать ошибки, но не исправляет их автоматически, поэтому я рекомендую именно PHP-CS-Fixer.

Совет: обязательно изучите и следуйте code style и рекомендациям вашего фреймворка. С большой вероятностью в будущих проектах вам встретится именно общепринятый в сообществе фреймворка code style, поэтому будет проще вписаться в новую команду, если вы придёте к этому стилю как можно раньше. К тому же, уже принятый в сообществе стиль поможет избежать ненужных холиваров внутри команды.

Устанавливаем через composer и настраиваем PHPCSFixer в Symfony-проекте:

cd /ваш/проект
composer req --dev friendsofphp/php-cs-fixer
# Если используете docker-compose, то устанавливайте в нём
docker-compose exec web composer req --dev friendsofphp/php-cs-fixer

Создаём в корне проекта файл .php_cs:

<?php

$finder = PhpCsFixer\Finder::create()
    ->in([
        __DIR__ . '/src',
        __DIR__ . '/tests'
    ])
;

return PhpCsFixer\Config::create()
    ->setRules([
        '@Symfony' => true,
        'array_syntax' => ['syntax' => 'short'],
        'concat_space' => ['spacing' => 'one'],
        'increment_style' => ['style' => 'post'],
        'no_extra_blank_lines' => ['tokens' => [
            'extra',
            'parenthesis_brace_block',
            'square_brace_block',
            'throw',
            'use',
        ]],
        'no_superfluous_phpdoc_tags' => false,
        'phpdoc_align' => false,
        'phpdoc_annotation_without_dot' => false,
        'trailing_comma_in_multiline_array' => false,
        'yoda_style' => false
    ])
    ->setFinder($finder)
;

Теперь вы можете запустить проверку всего проекта (или конкретного пути) с помощью команды

# только поиск ошибок
./vendor/bin/php-cs-fixer  fix --dry-run --diff ./
# поиск ошибок и их автоматический фикс
./vendor/bin/php-cs-fixer fix ./

Ошибки и качество кода

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

Самые популярные статичиские анализаторы кода:

Я покажу, как настроить и внедрить PHPStan, а вы можете добавить в проект все три по аналогии. Устанавливаем через composer сам PHPStan и несколько полезных плагинов — PHPUnit, Symfony, Doctrine.

cd /ваш/проект
composer req --dev phpstan/phpstan phpstan/phpstan-doctrine phpstan/phpstan-phpunit phpstan/phpstan-symfony

Должен создаться в корне проекта файл .phpstan.neon.dist, редактируем его:

includes:
    - vendor/phpstan/phpstan-doctrine/extension.neon
    - vendor/phpstan/phpstan-phpunit/extension.neon
    - vendor/phpstan/phpstan-phpunit/rules.neon
    - vendor/phpstan/phpstan-symfony/extension.neon
parameters:
    reportUnmatchedIgnoredErrors: false     #to avoid throwing of errors ... if no errors matching the ignored one is raised
    scanFiles:  #we need this for some twig based functions
        - '%rootDir%/../../../vendor/twig/twig/src/Extension/CoreExtension.php'
    bootstrapFiles:
        - '%rootDir%/../../../vendor/bin/.phpunit/phpunit-X.X.X/vendor/autoload.php'
    ignoreErrors:
        - message: '/^Service "[^"]+" is private.$/'
          path: '%rootDir%/../../../tests/'
    level: 0 
    symfony:
        container_xml_path: '%rootDir%/../../../var/cache/development/App_KernelDevelopmentDebugContainer.xml'

Внимательно пройдитесь по этим настройкам и укажите корректные пути. Особое внимание:

bootstrapFiles — включает путь до текущего phpunit. Если его не используете, то можете закоментить.
level — уровень строгости проверок от 0 до 8. 0 — самый слабый уровень, подходит для первого внедрения.

Теперь вы можете запустить проверку всего проекта (или конкретного пути) с помощью команды

./vendor/bin/phpstan analyse src tests

Советы по внедрению

Несколько советов по внедреню PHP-CS-Fixer в существующий проект с большой командой.

Выберите одного ответственного, кто запустит скрипты и пофиксит весь проект у себя на локалке, а потом создаст ПР / смерджит в develop или master.
Лучшее время — первое утро нового спринта. Обычно после спринта все ветки смёрджены, и это позволит залить все найденные правки в основную ветку проекта без конфликтов.
В статических анализаторах используйте для начала минимальный уровень строгости проверок. У каждого анализатора для этого своя школа, читайте документацию.
Первый фикс — самый критичный момент, так как правок может быть очень много. Все последующие фиксы обычно не создают ощутимых конфликтов и гит их смёрдживает самостоятельно.

Чтобы не запоминать длинные пути до скриптов, мы добавим несколько задач (tasks) в composer.json:

{
    "require": { ... },
    "require-dev": { ... },
    ...
    "scripts": {
        ...
        "csfix": "./vendor/bin/php-cs-fixer fix",
        "csfix-validate" : "./vendor/bin/php-cs-fixer fix --dry-run --diff",
        "phpstan": "./vendor/bin/phpstan analyse src tests",
        "code-quality": [
            "@phpcsfixer-validate",
            "@phpstan"
        ]

Теперь мы можем запускать проверки в упрощённом формате:

composer csfix
composer phpstan
composer code-quality

Обязательный запуск проверок перед коммитом

Внедрение этих инструментов позволяет удостовериться, что код соответствует принятому в команде стилю и не имеет очевидных опечаток и синтаксических ошибок. Однако это ещё не решает проблему забывчивости программистов и необязательности проверок.

Воспользуемся Git-хуками (git hooks) — это скрипты, которые мы можем попросить git выполнить при возникновении какого-то события: момент перед созданием коммита, момент после создания коммита, момент добавления сообщения в коммит и т. п.

Полный список git-хуков вы можете увидеть у себя в репозитории:

$ ls -al .git/hooks
-rwxr-xr-x   1 mk  staff   478 Jul 13 13:04 applypatch-msg.sample
-rwxr-xr-x   1 mk  staff   896 Jul 13 13:04 commit-msg.sample
-rwxr-xr-x   1 mk  staff  3327 Jul 13 13:04 fsmonitor-watchman.sample
-rwxr-xr-x   1 mk  staff   189 Jul 13 13:04 post-update.sample
-rwxr-xr-x   1 mk  staff   424 Jul 13 13:04 pre-applypatch.sample
-rwxr-xr-x   1 mk  staff   382 Dec  1 14:46 pre-commit
-rwxr-xr-x   1 mk  staff  1638 Jul 13 13:04 pre-commit.sample
-rwxr-xr-x   1 mk  staff   416 Jul 13 13:04 pre-merge-commit.sample
-rwxr-xr-x   1 mk  staff  1348 Jul 13 13:04 pre-push.sample
-rwxr-xr-x   1 mk  staff  4898 Jul 13 13:04 pre-rebase.sample
-rwxr-xr-x   1 mk  staff   544 Jul 13 13:04 pre-receive.sample
-rwxr-xr-x   1 mk  staff  1492 Jul 13 13:04 prepare-commit-msg.sample
-rwxr-xr-x   1 mk  staff  3610 Jul 13 13:04 update.sample

Создадим скрипт, который будет запускать проверки каждый раз перед попыткой создать коммит.

vim .git/hooks/pre-commit

Добавляем внутрь файла:

#!/bin/sh
export PATH=/usr/local/bin:$PATH
# Если вы используете docker-compose (рекомендуется), то добавьте
export COMPOSE_INTERACTIVE_NO_CLI=1

if [ -t 1 ]; then
    # If we're in a terminal, redirect stdout and stderr to /dev/tty and
    # read stdin from /dev/tty. Allow interactive mode for CaptainHook.
    exec >/dev/tty 2>/dev/tty </dev/tty
fi

errors=0

composer code-quality
# или, если вы используете docker-compose (рекомендуется), то
docker-compose exec -T web php bin/composer code-quality

if [ "$?" -ne 0 ]; then
    errors=1
fi

if [ "$errors" -eq 1 ]; then
    echo "Errors detected!"
    exit 1
fi

Теперь можете попробовать сделать ошибку в .php файле и создать коммит. Git должен ругнуться:

Устанавливаем git-hook автоматически

Финальный шаг — добавить git-hook в .git/hooks/ папку при запуске composer. Тогда ни один разработчик не сможет пропустить запуск проверок по невнимательности. Для этого добавим в composer.json такую строку:

{
    ...,
    "scripts": {
        "post-autoload-dump": "mkdir -p .git/hooks && cp config/pre-commit .git/hooks/pre-commit",
        ...
    }
}

Итог

Мы добавили в проект PHPCsFixer для код-стайла и PHPStan для поиска ошибок и опечаток.
Запускаем их при каждой попытке создать коммит.
И всё это начинает работать автоматически после первого же composer install.

Deployment: настраиваем пользователей

Максим Кузнецов — Fri, 27 Nov 2020 04:17:56 +0300

Проблема

Под root-пользователем работать небезопасно, равно как и делать весь проект доступным www-data.
Кроме того, во многих веб-приложениях пользователи имеют возможность загружать свои файлы. И очень часто с такими файлами возникают конфликты, так как пишутся они под www-data:www-data, а деплоим под другим пользователем. Даже если деплоить под root, то скорее всего права на папку перепишутся и www-data потеряет доступ к нужным файлам.

Решение

Создать нового пользователя deploy с правами на коннект к серверу по ssh, доступом только к папке с проектом и возможностью изменять файлы в ./public/uploads и ./var.

Создаём на сервере пользователя deploy из-под root:

ssh root@вашсервер
useradd --create-home -s /bin/bash deploy

Настроим доступ по ssh через ключи

mkdir /home/deploy/.ssh
touch /home/deploy/.ssh/authorized_keys

Вставьте содержимое одного из публичного ключа своего локального пользователя в файл authorized_keys и сохраните. Вывести публичный ключ локально можно командой: cat ~/.ssh/id_rsa.pub (название ключа id_rsa.pub у вас может отличаться).

vim /home/deploy/.ssh/authorized_keys

Меняем права на более строгие

chown -R deploy:deploy /home/deploy
chmod 600 /home/deploy/.ssh/authorized_keys

Определим пользователя нашего веб-сервера (в примере ниже это www-data)

ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1
> www-data

Добавляем пользователя deploy в группу www-data (группа веб-сервера)

usermod -a -G www-data deploy

Выставляем права на папку проекта

chown -R deploy:deploy /var/www/project
chmod -R 0775 /var/www/project

Проверим, есть ли setfacl в системе setfacl -h и установим, если его нет. Команда для Ubuntu:

sudo apt-get install acl

Выдадим права на папки с кэшем, логами и загруженными пользовательскими файлами

sudo setfacl -dR -m u:www-data:rwX -m u:deploy:rwX /var/www/project/var /var/www/project/public/uploads
sudo setfacl -R -m u:www-data:rwX -m u:deploy:rwX /var/www/project/var /var/www/project/public/uploads

Готово.

Для самого деплоймента я обычно использую Deployer c параметром writable_mode=acl.

Фавиконки для сайтов

Максим Кузнецов — Mon, 23 Nov 2020 16:01:47 +0300

Такая мелочь, как иконка сайта в табе браузера, не является критичной, но тем не менее влият на внешний вид вашего сайта и на его респектабельность.

Проблема

Почти у каждого браузера и ОС есть свои любимые размеры и форматы. Чтобы сайт выглядел хорошо на всех устройствах, нужно нарисовать несколько иконок.

Решение

https://realfavicongenerator.net/ — создаёт все эти варианты иконки по одному файлу и генерирует HTML.

Наконец-то, роботы трудятся на благо человека!

Как прокачать Vim за 1 минуту

Максим Кузнецов — Thu, 28 May 2020 19:02:48 +0300

Можно долго спорить о лучших IDE и редакторах для разработки кода, но если вы работаете в консоли или подключаетесь к серверу по SSH, то удобнее vim ничего нет. Он установлен по умолчанию на большинстве хостингов, так что имеет смысл его изучить и полюбить.

Настройка vim происходит в файле ~/.vimrc. Его может не быть, это нормально, тогда нужно создать.

Открываем ~/.vimrc

$ vim ~/.vimrc

Добавляем в файл следующее содержимое и сохраняем (команда «:wq»):

set ttyfast
set showmode
set showcmd
set title
set hidden
set ffs=unix,dos,mac

" Показывать нумерацию строк
set number

" Чтобы не было проблем с swp-файлами, которые создаются во время редактирования
set nobackup
set nowritebackup
set nowb
set noswapfile

" Глубина истории
set undolevels=1000

syntax on
" Цветовая схема
set t_Co=256

" monokai не идёт по умолчанию, но мы его установим чуть позже
colorscheme monokai

" Рисовать вертикальную линию для отображения границы в 120 символов — строки длинее хуже читаются
set colorcolumn=120
highlight ColorColumn ctermbg=238 guibg=#232728

" Настройка табов
set expandtab
set tabstop=4
set shiftwidth=4

" Отображать скрытые символы, табы и висящие пробелы
set list
set listchars=tab:→\ ,trail:·,nbsp:·

Я использую тёмную тему monokai. Её нет среди тем по умолчанию, но установить её несложно:

ls —l /usr/share/vim/vim*/colors покажет все предустановленные в системе темы

$ mkdir -p ~/.vim/colors
$ curl -o ~/.vim/colors/monokai.vim https://raw.githubusercontent.com/sickill/vim-monokai/master/colors/monokai.vim

Имя этого файла с темой нужно указать в ~/.vimrc в строке

colorscheme <monokai>

Как подружить docker, localhost и HTTPS

Максим Кузнецов — Tue, 26 May 2020 22:29:08 +0300

Когда разрабатываешь веб-сервис, который крутится на проде по HTTPS, есть большой соблазн не запариваться и работать локально по HTTP. Потому что так проще, да и в целом же всё работает плюс-минус одинаково. Если сервис простой, то скорее всего никаких проблем не всплывёт, но если сервис не монолитный и зависит от внешних сервисов или сам предоставляет АПИ клиентам, то проблемы с CORS неизбежны. И обычно эти проблемы обнаруживаются слишком поздно — либо на стейджинге, либо даже после релиза на продакшен.

Браузер начинает ругаться, что запросы с HTTPS на HTTP или наоборот не безопасны, сторонние сервисы перестают отвечать, так как по HTTP работали только тестовые стенды, с которыми вы и работали.

Решение простое — нужно не лениться и максимально приблизить локальную среду к боевой. Благо это задача из серии один раз сделал и используешь для всех последующих проектов.

Docker на продакшене

Если у вас продакшен без Docker, то вам поможет статья — Как получить бесплатный SSL-сертификат и установить его на Nginx.

В этой статье я рассматриваю только локальную сборку через docker-compose, потому что на продакшене, как ни странно, это немного проще. Достаточно выполнить понятную инструкцию по настройке Certbot и/или добавить соответствующий докер-образ с Docker Hub.

Docker на localhost

См. как запустить сайт через docker-compose на примере докеризации Эгеи.

На локалхосте Certbot не подойдёт, так как ему нужно реально существующее доменное имя и доступный через интернет сайт. Поэтому прописать локальный адрес в /etc/hosts не поможет. Решение — выпустить свой самоподписанный сертификат. Да, он не будет приниматься никем, кроме нашей системы, но для локальной разработки этого и не нужно.

Создаём доменное имя

Во-первых, создадим локально доменное имя, чтобы оно было похожим на боевое, а не обычный и скучный localhost. Например, docker.loc для основного сайта и api.docker.loc для API:

$ sudo vim /etc/hosts
127.0.0.1       localhost
127.0.0.1       docker.loc
127.0.0.1       api.docker.loc
...

Если для вашего сервиса необходимо несколько доменов, то пропишите их ниже по аналогии.

Выпускаем свой SSL-сертификат

Для реальных сайтов SSL-сертификаты выдаются специальными сертификационными центрами за деньги. За это они потом могут подтвердить верность домена по запросу любого браузера. Мы же выпустим свой сертификат и сами его подтвердим.

SSL-сертификат создаётся одной командой и состоит из двух частей: публичного сертификата и секретного ключа.

openssl req -x509 -out docker.loc.crt -keyout docker.loc.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=docker.loc' -extensions EXT -config <( \
   printf "[dn]\nCN=docker.loc\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:docker.loc\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

Файлы docker.loc.crt и docker.loc.key будут сохранены в той папке, откуда вы запускаете команду.

Добавляем сертификаты в ОС

Ниже пример, как это сделать на Mac OS X.

Найдите сертификат docker.loc.crt в Finder (или можно в нужной папке консоли ввести «open .»)
Дважды кликните по нему, появится окно.

Введите пароль администратора
Теперь нужно найти этот сертификат в Keychain Access и выбрать Trust Always

Добавляем сертификаты в docker-compose сборку

Сертификаты нужно положить в контейнер с веб-сервером. Я приведу пример для Nginx и сборки по типу https://github.com/pluseg/e2-docker.

Расположение сертификатов и конфигов

В этой сборке папки из app/docker/nginx монтируются прямо в nginx-контейнер. Поэтому удобно расположить файлы так:

<project root>
- app
--- docker
----- nginx
------- conf.d
--------- docker.loc.conf
------- ssl
--------- docker.loc.crt
--------- docker.loc.key

Пример docker.loc.conf (проект на PHP + Symfony)

# лучше с php соединять через socket
upstream php-upstream { server web:9000; }

# Редиректим HTTP на HTTPS
server {
       listen         80;
       listen    [::]:80;
       server_name    docker.loc;
       return         301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    root /var/www/html/docs;

    server_name            docker.loc;
    ssl_certificate          /etc/nginx/ssl/docker.loc.crt;
    ssl_certificate_key   /etc/nginx/ssl/docker.loc.key;
    ssl_protocols           TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers         EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;

    location / {
    	try_files $uri /index.php$is_args$args;
    }

    location ~ ^/(index|app|app_dev|config)\.php(/|$) {
        fastcgi_pass php-upstream;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param  SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        fastcgi_read_timeout 300;
    }

    error_log /var/log/nginx/docker.loc-error.log;
    access_log /var/log/nginx/docker.loc-access.log;
}

Пример docker-compose.yml

Добавляем 443 порт и несколько volume с конфигами и сертификатами.

version: '3.2'
services:
    ...
    nginx:
        image: nginx:latest
        ports:
            - 80:80
            - 443:443
        volumes:
            - ./app/docker/nginx/conf.d:/etc/nginx/conf.d
            - ./app/docker/nginx/ssl:/etc/nginx/ssl
            - ./:/var/www/html
            - ./var/logs/nginx:/var/log/nginx
        command: /bin/bash -c "exec nginx -g 'daemon off;'"

Запускаем и проверяем

docker-compose up -d --build

Как установить расширение в Postgres

Максим Кузнецов — Sat, 02 May 2020 00:05:16 +0300

Переключаемся в юзера Postgres:

$ su postgres

Заходим в базу и выполняем следующие команды (на примере установки uuid-ossp):

ALTER USER myuser WITH SUPERUSER;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
ALTER USER myuser WITH NOSUPERUSER;

Как быстро изучить Git с нуля

Максим Кузнецов — Tue, 28 Apr 2020 16:22:21 +0300

Git — это система версионирования документов. Она позволяет пользователям создавать несколько параллельных версий, независимо управлять ими и сливать друг в друга с автоматическим нахождением конфликтных строк.

Когда документ правит один человек, то никаких проблем не возникает, хотя иногда хочется видеть историю изменений с возможностью вернуться на предыдущую версию. А что, если над документом работают два человека?

— Вась, только что залил новую версию отчёта. Добавил одну страницу в третью главу.
— Ёпт, а я третью главу уже с нуля переписал...
— ...
— Ладно, давай подходи к моему компу со своим файлом, счас вместе глянем как это разрулить.

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

А что, если документ содержит сто страниц и его будут править десять человек?

Git

Первая версия Git была создана Линусом Торвальдсом — автором операционной системы Linux. Собственно, с помощью Git она и разрабатывалась.

Первыми с проблемой параллельного редактирования файлов столкнулись программисты, они и разработали решение — Git. Он позволяет хранить файлы в общем хранилище, а также каждому участнику создавать их копию локально. Можно менять файлы, создавать свои версии, откатываться на предыдущие, а потом отправлять финальную версию в хранилище. Гит самостоятельно объединит версии разных людей, либо укажет на конфликт, если, например, оба человека изменили одну и ту же строку. По такому же принципу работает Google Docs и подобные сервисы.

Курсы

Для изучения Git достаточно изучить

[4h] Githowto — курс на русском, нужно пройти хотя бы первые 38 уроков, чтобы можно было использовать git в реальной жизни.
[15m] Шпаргалка по gitflow — способ организации веток, чтобы в них не запутаться на средних и больших проектах.

В Githowto сразу же рассказывают, как установить git. Иногда git уже включён в систему по умолчанию, поэтому можно и не устанавливать. Проверить его наличие можно командой в терминале:

$ git --version
git version 2.24.1 (Apple Git-126)

Если ничего не вывелось, значит git не установлен.

Вопросы для самопроверки после курса

Что такое unstaged, staged и commited состояния у файлов?
Что такое ветки, как создавать их, переключаться между ними и объединять?
Как нужно именовать ветки согласно gitflow (master, develop, feature, hotfix, release)?
В каких случаях git самостоятельно сливает файлы, а в каких создаёт конфликты?
Как выглядит конфликт и что нужно сделать, чтобы его разрешить?
Как откатить изменения закоммиченного файла?
Как откатить изменения закоммиченного и запушенного в удалённый реп файла?
Что такое git stash и как им пользоваться?
Что такое репозитории — локальные и удалённые? Как склонировать репозиторий? Как запушить в реп?
Для каких файлов GIT подходит, а с какими работает плохо: текстовые и бинарные файлы?
Как исключить файлы из-под контроля Git (.gitignore)?
Установите алиасы для частых комманд: git ci, git st, git hist, git br, git co.

Дополнительная практика [1h]

Для начала создайте папку проекта с двумя файлами в разметке Markdown. Если не работали с markdown, то считайте их обычными текстовыми файлами.

README.md

# Знакомство с GIT
Есть отличные курсы:
- http://gitimmersion.com/
- https://githowto.com/ru

А также статья в блоге https://maxkuznetsov.ru/.

CHANGELOG.md

- Изучен курс GitHowTo
- Ознакомился с Git flow подходом
- Прочитал статью https://maxkuznetsov.ru/all/git-intro и сделал задания

Задачи

Добавьте поддержку Git в этот проект. Сделайте первый коммит, включающий оба этих файла.
Создайте от мастера новую feature/md-updates-vasya.
В реальной жизни master используется только для продакшена, а для основной разработки — ветка develop. Новые правки лучше всегда делать в отдельной feature/* ветке, а потом сливать её в develop или master, если вы работаете без develop.
Зарегистрируйтесь в github.com и создайте пустой репозиторий.
Запушьте локальный репозиторий в созданный удалённый репозиторий.
Измените первые строки в обоих файлах. Сделайте коммит, включив в него только изменения из CHANGELOG.md.
Случай из жизни: мы сделали кучу изменений в файлах, а потом поняли, что надо бы сохранить последнюю рабочую версию, но без последних лишних измнений.
Откатите (soft) последний коммит и сделайте новый, но уже с изменениями из обоих файлов. Попробуйте также вариант без отката: «git commit —amend».
Запушьте ветку в удаленный репозиторий и создайте там Pull Request в master.
Создайте локально новую папку, куда склонируйте ваш удалённый репозиторий. У вас должно быть на компьютере две папки, смотрящие на один и тот же репозиторий. Этим мы имитируем ситуацию, когда два человека с разных компьютеров работают с одним репом. Назовём эти два локальных репозитория: первый — репозиторий Васи, второй — Пети.
В новом репо Пети создайте ветку feature/md-updates-petya из master.
Измените первые строки в обоих файлах (иначе, чем в feature/md-updates-vasya), закоммитьте, запушьте и создайте PullRequest на Github.
В интерфейсе Github примите первый Pull-Request из ветки Васи, а потом убедитесь, что получили конфликт в Пулл-реквесте от Пети.
Так часто бывает в жизни, когда над одним кодом работает больше одного человека. Чем больше команда, тем чаще конфликты.
Разрулите конфликт в локальном репозитории в ветке Пети и обновите Пулл-реквест.
Примите в github.com обновлённый Пулл-реквест от Пети.
В репозитории Васи переключитесь в master и сделайте git pull. Убедитесь, что ветка feature/md-updates-vasya удалена.
Оказалось, что вмёрдженная ветка от Пети содержала баги, поэтому нужно её откатить. Откатите её в репозитории Пети с помощью revert и c полной перезаписью публичной истории. Можно делать без Пулл-реквеста в этот раз.
Посмотрите, как изменилась история в репозитории Васи до git pull и после git pull.
В репозитории Васи добавьте в .gitignore файл CHANGELOG.md, чтобы Git перестал его отслеживать. (Подсказка: «git rm» с флагом «—cached».) Запушьте в удалённый реп.
Зайдите в Github и проверьте, что CHANGELOG.md больше нет в репозитории.

GUI клиенты

В реальной жизни работать с гитом через консоль приходится редко. Есть клиенты Git с визуальным интерфейсом, например:

встроенные в IDE
Sourcetree — мой личный выбор
Git Kraken
Git Tortoise

Но ими проще пользоваться, когда ты понимаешь, что они делают под капотом.

Запускаем Эгею через Docker и забываем про технические проблемы на 10 лет вперёд

Максим Кузнецов — Tue, 28 Apr 2020 01:37:47 +0300

Про работу с Docker можно посмотреть часовое видео. С Docker вам не нужно заботиться о конфигурациях веб-сервера, базы данных и правах доступа к файлам и папкам. Одна команда — и готово.

В официальной документации Эгеи есть две ссылки на запуск блога с помощью Докера, но оба способа имеют свои недостатки. По крайней мере один из них устарел и просто не заведётся из коробки, плюс используется старый, медленный ПХП 5, а второй использует веб-сервер caddle, который не столь популярен и хорошо описан, как Nginx или официально поддерживаемый Эгеей Apache.

Блог за 5 шагов

Вот, что вам нужно, чтобы установить последнюю версию блога.

Установленные на целевой машине docker и docker-compose — это может быть и локальная машина, и продакшн. А также наличие домена, если поднимаете на продакшене.
Склонировать репозиторий https://github.com/pluseg/e2-docker

git clone git@github.com:pluseg/e2-docker.git /path/to/blog/folder

Создать файл .env

cp .env.example .env

И указать в нём нужные версии PHP, MySQL, Эгеи (на сегодняшний день они актуальные и их менять и не надо) и домен VIRTUAL_HOST (для локали можно оставить localhost.
Запускаем всё это хозяйство с помощью docker-compose

docker-compose up -d --build

Заходим на домен, указанный в VIRTUAL_HOST, и заполняем небольшую форму

DB Host: db
   DB User: root
   DB Pass: egeya
   DB Database: <выбрать из списка "egeya">
   Admin pass: <укажите ваш админский пароль>

Готово.

Дополнительные плюшки

В этой сборке я вынес версии всех зависимостей в .env файл, так что теперь обновить версию блога, ПХП или mysql — дело одной минуты. Достаточно обновить их в .env файле и перезапустить контейнеры с флагом пересборки:

docker-compose up -d --build

Если понадобится перенести блог в другое место — не проблема. Достаточно перенести папку с блогом куда нужно и запустить ту же самую команду docker-compose.

Все файлы, которые должны сохраниться между обновлениями сохранятся. Они лежат в папке ./data:

data/pictures — картинки
data/user — всё, что касается пользователя, включая shared шаблоны и настройки
data/theme — ваша кастомная тема, если понадобится. Она добавляется в папку к остальным комплектным темам /themes
data/mysql — данные из базы

Удерживаем читателей блога, увеличиваем ретеншн

Максим Кузнецов — Tue, 14 Apr 2020 23:13:32 +0300

Одна из проблем всех self-hosted блогов, что их приходится самостоятельно раскручивать. Даже если вы хорошо пишете и вас приходят читать, вы не сможете удержать читателей. Они просто не узнают о том, что у вас что-то вышло.

Есть несколько решений.

Завести аккаунты в соц.сетях и постить там анонсы статей. Тогда читатели блога смогут узнавать о ваших статьях в удобной платформе и приходить их дочитывать к вам в блог.
Сделать емейл подписку, чтобы периодически слать подборку новых статей.

Оба способа хороши и стоит использовать их оба. Но в этой статье покажу, как добавить в Эгею блок с подпиской на емейл рассылку и как управлять ею.

Выбор сервиса по рассылке емейлов

Для начала нам нужно зарегистрироваться в любом сервисе, работающего с емейл-рассылками. При выборе сервиса важно понимать, что емейлы бывают

транзакционными — это письма для конкретного пользователя. Например, подтверждение регистрации, письмо о произошедших с его аккаунтом событиях, о новом сообщении.
маркетинговыми — массовые рассылки одного письма. Например, новостная рассылка сайтов, емейл-курс Максима Ильяхова «Сильный текст». В таких письмах нет ничего персонального, но они и не для этого.

Нам нужно, чтобы сервис умел отправлять именно маркетинговые рассылки. Тогда нашу рассылку никто не заблочит, а мы ещё сможем и аналитику проводить.

Mailchimp — один из лидеров рынка емейл рассылок. У них есть тысячи интеграций как с популярными движками, CMS, платформами и соц.сетями, так и с частными сайтами, что нам и подходит.

Я выбрал Mailchimp. Для небольшого блога достаточно бесплатного плана: 2000 подписчиков на рассылку, которым можно слать 10 тысяч писем каждый месяц. Кроме того, у него много интеграций, кастомизаций, есть удобный функционал по управлению подписчиками и созданию емейлов в онлайн редакторе. И возможность подписчикам отписываться от рассылки в любой момент — это важно, так как спам никто не любит. Вот моя честная реферральная ссылка — http://eepurl.com/gZRNX1, мне будет приятно, если вы зарегистрируетесь по ней.

Регистрация в Mailchimp

Указываете емейл, юзернейм пароль.
Вам приходит письмо для подтверждением емейла, проходим по ссылке из него.
Выбираем бесплатный план (справа).
Дальше нас спросят имя и фамилию, а затем название бизнеса. Это название будет показываться во всех формах с подпиской/отпиской на вашу рассылку, поэтому укажите что-то вразумительное. Я указал: «Блог Макса Кузнецова»

Удивительно, но им нужен ещё и адрес с индексом. В принципе, можно указывать что угодно, в формах мы потом это скроем.
Шаг с загрузкой контактов, которые уже готовы подписаться на нашу рассылку. Скорее всего им придёт письмо с просьбой подтвердить этот факт.
Ещё пара вопросов и всё готово.

Настройка Mailchimp

Нам нужно зайти в Audience, а затем в Settings.

Дальше выбираем Signup forms. Здесь нам нужно кастомизировать и перевести все возможные формы на русский (если блог русскоязычный). Для этого зайдём в Form Builder и по очереди будем выбирать шаблоны форм в выпадающем списке. Нам нужны все формы в Subscribe и Unsubscribe разделе. В разделе Build можно увидеть предпросмотр и убрать или добавить лишние поля. В раздале Translate It — указать переводы всех текстов с английского на любой другой. В принципе, можно оставить английский вариант или авто-перевод на русский, но выглядит это не айс, местами хуже гугл-транслейта:

Возвращаемся обратно в Signup forms, заходим в Embedded forms и выбираем в верхних полях предустановленный вид, который подходит нам. Нам подойдёт Horizontal — мы её кастомизируем под нас чуть позже. А сейчас копируем весь код из поля «Copy/paste onto your site».

Обратите внимание на раздел Signup Forms > Subscriber Pop-up. Он позволяет добавить небольшой javascript-код на ваш сайт подобно Яндекс.Метрике или Гугл Аналитике, а затем управлять видом и структурой формы и условиями её показа прямо из Мейлчимпа. Вполне удобно, но я против назойливых попапов. Кроме того, если пользователь его скроет, то он больше не сможет подписаться на вашу рассылку позже, если передумает. Поэтому я предлагаю разместить статичный блок с подпиской в футере

Добавляем блок с формой подписки в Эгею

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

Нам нужно создать новый файл footer-pre.tmpl.php и залить его на сервер с блогом (по ftp или с помощью scp) в папку /путь/до/блога/user/extras/.

Внутри этого файла помещаем тот код, что мы скопировали в MailChimp, только меняем стили внутри тега style, а также текст внутри тега label и подпись на кнопке Subscribe. У меня получилось так:

<link href="//cdn-images.mailchimp.com/embedcode/horizontal-slim-10_7.css" rel="stylesheet" type="text/css">
<style type="text/css">
  #mc_embed_signup{
    background:antiquewhite; 
    clear:left; 
    font:14px Helvetica,Arial,sans-serif; 
    width:100%;
    margin: 0 0 40px 0; 
    padding: 20px;
  }
  #mc_embed_signup label {
    font-weight: 400;
    line-height: 24px;
  }
  #mc_embed_signup input[type=submit] {
    text-align: center;
  }
}
</style>
<div id="mc_embed_signup">
<form action="ВАША ССЫЛКА" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate="">
    <div id="mc_embed_signup_scroll">
  <label for="mce-EMAIL">Оставьте свой емейл, чтобы изредка получать подборку новых статей</label>
  <input type="email" value="" name="EMAIL" class="email" id="mce-EMAIL" placeholder="Email" required="">
    <!-- real people should not fill this in and expect good things - do not remove this or risk form bot signups-->
    <div style="position: absolute; left: -5000px;" aria-hidden="true"><input type="text" name="b_ed0df51ffed55c354e5eeb476_d4231642b3" tabindex="-1" value=""></div>
    <div class="clear"><input type="submit" value="Подписаться" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
    </div>
</form>

Результат

Что дальше

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

Пишите полезно, пишите вкусно.

Эгея. Как починить комментарии, если у вас Nginx

Максим Кузнецов — Tue, 14 Apr 2020 15:17:56 +0300

Если вы подняли блог на Nginx по документации Эгеи, то вероятнее всего у вас не работает авторизация через кнопки соц.сетей в комментариях. Даже если визуально всё работает, попробуйте авторизоваться там сами. Это критично, если у вас в настройках выбрано «комментировать могут только авторизовавшиеся пользователи», тогда вам даже не смогут написать про эту проблему.

Решение

Обновляем одну строку в файле Nginx-конфига, соответствующего блогу на Эгее.

location / {
    log_not_found off;
    # Было:
    # try_files $uri $uri/ /index.php?go=$uri;
    # Стало:
      try_files $uri $uri/ /index.php?go=$uri&$query_string;
  }

Перезагружаем веб-сервер.

$ nginx -s reload

Причина

Эгея обрабатывает все запросы путём пробрасывания через фронт-контроллер index.php. При этом первоначальный URI передаётся как GET-параметр «?go=».

Исходный запрос Обработанный запрос

/tags/ /index.php?go=/tags/

/all/how-web-works/ /index.php?go=all/how-web-works/

/sign-in-done/vk/?data={«user»: ...} /index.php?go=sign-in-done/vk/

В последнем случае исходный запрос уже содержит GET-параметры, которые до php не дойдут.

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

ps.: большое спасибо Евгению Степанищеву, что обнаружил этот баг и не поленился написать мне на почту.

Что такое HTTP, или как браузеры общаются с веб-серверами

Максим Кузнецов — Tue, 14 Apr 2020 04:07:59 +0300

В статье про устройство веба и как происходит серфинг я упомянул, что браузер отправляет запрос к веб-серверу. Но что представляет из себя запрос? Это куча машиночитаемых квантовых кодов и сингулярных шифров? Программистская магия? Вовсе нет.

Что такое HTTP

HTTP — это протокол передачи данных для клиент-серверных приложений.

Не нужно пугаться слова «протокол». Это значит лишь то, что разработчики встретились и договорились о возможных форматах запросов и ответов на них. Вокруг нас множество таких протоколов-договорённостей.

При встрече на протянутую руку принято отвечать рукопожатием. Отсутствие рукопожатия — это тоже ответ, иногда даже более красноречивый, чем само рукопожатие.
Девушкам же руку не протягивают — это тоже часть протокола. Можно и им руку протянуть, но в большинстве случаев не поймут, а в некоторых странах заставят жениться.
Электрические розетки — хотя в разных странах они разные, внутри одной страны они одинаковы.
Разъёмы для кабелей — USB type B, USB type C, mini USB, micro USB. Производители приняли внегласный протокол и производят кабели и устройства именно таких форматов, иначе при прочих равных пользователи их не поймут и не будут покупать их продукцию (исключение — Apple).
Правила дорожного движения — знаки, разметка и светофоры помогают пешеходам дойти, а автомобилистам доехать до места назначения без происшествий.
Формы налоговых деклараций и прочих бюрократических документов.

Любой из протоколов нас ни к чему не обязывает, это не ГОСТ, он лишь рекомендует поступать так или иначе, если мы хотим добиться желаемой цели — понимания от окружающих людей, одобрения от покупателей, сохранения продаж, избежания аварий и штрафов, получения веб-страницы от сервера.

HTTP — это набор некоторых правил, которым должны следовать клиенты и сервера, если они хотят, чтобы их правильно поняли.

HTTP-клиентами чаще всего являются браузеры — Google Chrome, Mozilla Firefox, Safari, Opera, Yandex Browser и другие. А серверами являются веб-сервера. Вот эта приставка «веб-» и указывает на то, что это не просто какой-то сервер, а сервер, который умеет принимать запросы и отвечать на них по протоколу HTTP. Как он будет устроен внутренне — не определено и не важно. Наиболее популярными в мире веб-серверами являются Nginx, Apache2, но вы можете написать и свой — в некоторых языках это делается крайне легко, см. пример на Golang.

Прикидываемся браузером, или делаем HTTP-запрос из терминала

Чтобы понять, как браузер общается с сервером, нужно думать как браузер, нужно стать браузером.

Попробуем обратиться к веб-странице http://http.maxkuznetsov.ru так, как это делают браузеры под капотом. Для этого отправим запрос из терминала/командной строки с помощью утилиты netcat. Чаще всего она установлена по умолчанию: в Mac OS X — это «nc», в других ОС может быть «ncat» или «netcat». (Или воспользуйтесь онлайн-сервисом https://reqbin.com/u4178vu3, в котором слева и справа выберите табы Raw для отображения «голых» запросов и ответов. Но из терминала получится нагляднее.)

nc http.maxkuznetsov.ru 80

Дальше ничего не произойдёт, терминал подвиснет — это нормально. Команда netcat подключилась к серверу по адресу http.maxkuznetsov.ru к 80-му порту, и сервер ждёт от нас текст запроса.

Порты — это как номера квартир в доме. Чтобы доставить письмо, почтальону нужно знать не только дом, но и номер квартиры. Причём в некоторых квартирах почтальону ответят, если он в них постучится, а другие — нет, потому что там никто не живёт. А кто-то ответит, что адресат уже давно здесь не живёт и дадут новый адрес почтальону (редирект запроса).

В компьютерных сетях всё точно также. На одном адресе (IP или доменном имени) могут висеть и ожидать запросов несколько портов одновременно. Чтобы избежать путаницы, сообщество разработчиков договорилось для наиболее популярных серверов выделять одни и те же порты: SSH — 22, FTP — 21, база данных MySQL — 3306, веб-сервера — 80. Это лишь соглашение и рекомендация, можно поднять какой угодно сервер на каком угодно порту, но для клиентов это скорее всего станет неожиданностью.

Когда в браузере мы вбиваем в адресной строке http.maxkuznetsov.ru, браузер подставляет порт 80 незаметно для нас. Вы можете убедиться в этом, вбив в адрес не http.maxkuznetsov.ru, а http.maxkuznetsov.ru:80 — результат не изменится.

Введём в терминале такие строки запроса.

$ nc http.maxkuznetsov.ru 80
GET / HTTP/1.1
Host: http.maxkuznetsov.ru

После Host нужно ввести две пустые строки: одна строка отступа, вторая содержит тело запроса, но в данном примере оно пустое. Такие правила протокола HTTP. Получив вторую пустую строку, веб-сервер поймёт, что запрос завершён, обработает его и пришлёт ответ, включающий интересующую нас веб-страницу с html.

$ nc http.maxkuznetsov.ru 80
GET / HTTP/1.1
Host: http.maxkuznetsov.ru

HTTP/1.1 200 OK
Server: nginx/1.10.3 (Ubuntu)
Date: Mon, 13 Apr 2020 20:10:04 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive

<html>
<head>
  <title>This is a test page for Max's blog article about http</title>
</head>
<body>
  <h1>Hello HTTP world!</h1>
  <form method="POST" action="/">
    <input name="name" type="text" placeholder="Name" />
    <button type="submit">Submit</button>
  </form>
</body>
</html>

После этого браузер разбирает ответ, убирает техническую информацию и отображает html-страницу в кодировке UTF-8 — так ему сказал сервер в заголовке Content-Type. Если в HTML включены CSS, Javascript, картинки, то браузер запросит их отдельными запросами ровно таким же образом. Если он их уже запрашивал раньше, то возьмёт из локального кэша. Поэтому первый раз страницы грузятся визуально дольше.

Разберём структуру запроса и ответа более детально.

Структура HTTP-запроса

Каждый запрос имеет один и тот же формат:

метод /путь протокол
Host: <site.ru>
заголовок1: значение
заголовок2: значение
заголовокN: значение

<тело_запроса_в_одну_строку или пустая_строка_если_тело_пустое>

протокол

Указывает, какая конкретная версия протокола HTTP будет использоваться. Чаще всего 1.0 и 1.1, но могут встречаться устаревшая 0.9 или новая 2.0. Однако, веб-сервер может не поддерживать указанную версию и вернуть ошибку. На практике подавляющее количество веб-серверов поддерживают 1.0 и 1.1.

/путь

Относительный путь (без доменного имени) до документа. В нашем примере указан корень /, но путь может быть любым: /index.php, /catalog/food/milk. Под документом понимаются не только файлы с расширением .html, но и любые другие файлы, например картинки, .css, .js.

метод

Определяет, что веб-сервер должен сделать с документом, найденным по указанному «/пути».

GET — вернуть документ — GET /messages/1.
HEAD — вернуть только заголовки без самой страницы. Это подходит для случая, когда мы хотим проверить, что ссылка на документ валидная. Пример: HEAD /messages/1
POST — отправить данные для создания документа — POST /messages (и детали нового сообщения).
PUT — заменить документ
PATCH — частично обновить документ
DELETE — удалить документ
TRACE, CONNECT — технические методы, которые можно пропустить.
OPTIONS — просьба к веб-серверу вернуть разрешённые настройки для запросов к указанному документу. Ответ включает в себя в том числе список разрешённых методов.

На практике примерно 80% запросов приходится на GET, 15% — на POST и 5% — на все остальные методы.

Заголовки

Они опциональны (в нашем примере их не было вовсе) и подсказывают веб-серверу, как именно нужно обработать запрос. Например, что клиент отправляет запрос в виде текста с кодировкой utf-8, а ожидает получить json в кодировке cp1251.

Наиболее частые на практике заголовки:

Accept — в каком формате ожидаем ответ: обычный текст, html, xml, json, что угодно ещё.
Accept-Charset — кодировка тела запроса: utf8, cp1251, koi8.
Authorization — данные для авторизации между запросами. Здесь чаще всего передаются токены API. Авторизация между запросами будет рассмотрена ниже.
Accept-Language — список языков, которые нас бы устроили. Например: «Accept-Language: ru».
Cache-Control — настройки кэширования страниц
Cookie — известные браузеру куки. В них сохраняются идентификаторы сессий и пользовательские предпочтения.
Referrer — с какой страницы был сделан текущий запрос. Полезно для аналитики сайта и для возвращения юзера на первоначальную страницу после регистрации, например.
User-Agent — тип клиента (чаще всего тип вашего браузера). Пример: «Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.163 Safari/537.36». Это поле часто используется на сервере, чтобы отслеживать количество запросов с одного устройства и блокировать их при превышении лимита. Однако это не панацея, ведь после блокировки злоумышленник может поменять User-Agent на любой другой.

Тело

Для GET-запросов тело не имеет смысла, так как всё, что нужно — это путь в стартовой строке и заголовки. Но что происходит, когда мы хотим отправить информацию на сервер? Логин-пароль, форма обратной связи, форма создания поста? Для этого используется POST-запрос.

Каждый элемент формы имеет аттрибут name. В нашем примере страница http://http.maxkuznetsov.ru содержит форму с единственным тегом input, который имеет name=«name». Именно это имя и введённое пользователем в инпут значение будут отправлены на сервер. В консоли такой браузерный запрос будет выглядеть так:

$ nc http.maxkuznetsov.ru 80
POST / HTTP/1.1
Host: http.maxkuznetsov.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 8

name=Max

Обратите внимание, что POST запрос очень похож на GET, мы даже обращаемся к тому же документу «/». Однако есть и отличия:

вместо второй пустой строки в конце запроса содержатся данные: «name=Max»
эти данные могут быть в разном формате, поэтому мы должны явно указать веб-серверу, что это данные из формы — application/x-www-form-urlencoded
также мы сообщаем серверу, что в теле запроса содержится ровно 8 символов — «Content-Length: 8». Это техническое поле, которое браузер выполняет на лету, а нам приходится считать самим.

В ответ придёт знакомая страница, но с другим h1 заголовком — php-скрипт, обрабатывающий страницу, подставил вместо «http world» введённое нами имя.

HTTP/1.1 200 OK
Server: nginx/1.10.3 (Ubuntu)
Date: Mon, 13 Apr 2020 22:26:19 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Content-Encoding: gzip

<html>
<head>
  <title>This is a test page for Max's blog article about http</title>
</head>
<body>
  <h1>Hello Max</h1>
  <form method="POST" action="/">
    <input name="name" type="text" placeholder="Name" />
    <button type="submit">Submit</button>
  </form>
</body> 
</html>

Структура HTTP-ответа на основе примера выше

Можно заметить, что структура ответа похожа на структуру запроса. Но есть несколько нюансов. Первая строка ответа выглядит иначе:

HTTP/1.1 200 OK
протокол статус пояснение

протокол

Значение поля то же самое, что и в запросе. Но может отличаться от версии, что запросил браузер, если веб-сервер её не понимает.

статус и пояснение

HTTP-статус из трёх цифр и короткая поясняющая фраза. Все фразы стандартизированы и чётко соответствуют статусу.

Статусов больше сотни, но не все их них используются браузерами. Некоторые предусмотрены на далёкое будущее, а некоторые слишком специфичны.

Первая цифра статуса указывает на класс:

1xx — информационные — технические статусы, вероятнее всего вы их не увидите в реальной жизни
2xx — успешно обработанные запросы с детализацией. Наиболее частые: 200 — всё ок, 201 — документ был создан, 204 — запрос завершился успешно, но ответ содержит заголовки и пустое тело. На практике реальные API не парятся и в 95% случаев возвращают код 200, а детали успешной операции отсылаются в теле.
3xx — перенаправление — запрос следует выполнить по другому адресу, который передаётся в заголовке Location. Частые: 301 — документ перенесён навсегда, 302 — документ перенесён временно. Они довольно критичны для поисковых ботов, которые индексируют ваш сайт. 301 говорит боту, чтобы он запомнил новый адрес страницы, а прежний забыл.
4xx — ошибка клиента — запрос содержит не все или некорректные данные (400), требуется аутентификация (401) или не хватает прав на выполнение операции (403), запрошенной страницы не существует (404) или http метод запроса для этой страницы запрещён (405).
5xx — ошибка на сервере — сервер не справился или произошла непредвиденная ошибка (500), ошибка обработки запроса вышестоящим сервером, например php-fpm не отвечает nginx’у (502), сервер временно не отвечает по техническим причинам (503), сервер не дождался ответа и запрос отвалился по таймауту (504). Например, стандартное ограничение на время выполнения php-скрипта — 30 секунд. Если скрипт делает запрос к стороннему ресурсу, который под нагрузкой, то nginx покажет 504ю ошибку.

При этом даже неуспешный статус не запрещает серверу вернуть веб-страницу, которую браузер отобразит как ни в чём не бывало. Попробуйте зайти на несуществующую страницу моего блога: https://maxkuznetsov.ru/non-existed-page. Сервер вернёт 404 вместо 200, но мы всё равно можем показать пользователю что-то полезное.

заголовки

Заголовки сервера выполняют ту же роль, что и заголовки запроса. Есть общие заголовки, как Cache-Control, но есть и свои уникальные.

Allow — определяет список разрешённых http методов для запросов
Location — адрес для перенаправления.
WWW-Authenticate — информация про метод аутентификации, запрос должен послать соответствующую информацию в хедере Authorization.

тело

Тело ответа также отделяется от группы заголовков пустой строкой. При этом в теле может передаваться что угодно — текст, html, json, xml, картинки и прочие файлы. Все они отдаются браузеру в одинаковом формате, но с отличающемся заголовком Content-Type, который и поясняет браузеру, как отобразить контент пользователю: как html-страницу, как картинку, показать встроенный в браузер PDF-просмотрщик или начать скачивание файла.

Про аутентификацию и авторизацию

Если посмотреть на структуру HTTP запросов и ответов становится понятно, что каждый запрос для веб-сервера является изолированным и не сохраняет состояния. То есть если вы сделаете два одинаковых запроса с одного браузера, веб-сервер обработает их так, будто они были присланы разными пользователями.

В жизни это ограничение обходят двумя путями:

хранят уникальный идентификатор сессии в куках (cookies), которые браузер по требованию сервера сохраняет локально и затем прикрепляет к каждому запросу в виде заголовка «Cookie». Cервер при каждом запросе разбирает заголовок с куками и по сохранённому там идентификатору «узнаёт» пользователя.
через заголовок Authorization браузер посылает серверу в каждом запросе токен (форматы могут быть разными), по которому сервер определяет пользователя аналогично сессиям. Этот способ чаще всего используется в API.

Поскольку http протокол передаёт все данные в незащищённом виде, то ни один из этих способов не является безопасным, а идентификатор сессии или токен могут быть легко перехвачены злоумышленником. В качестве решения проблемы следует использовать более безопасного брата HTTP — HTTPS.

Что важно понимать про HTTP

HTTP — это протокол общения клиент-серверных приложений в вебе. Набор правил, который помогает клиентам (прежде всего браузерам) и веб-серверам понимать друг друга.
HTTP — это про формат общения, а не про управление сервером HTTP-командами. Клиент может отправить что угодно: удали страницу сайта, создай нового пользователя, выдай список всех пользователей — но сервер не обязан их выполнять, он лишь обязан ответить в формате HTTP, чтобы клиент его понял. То есть благодаря HTTP сервер поймёт, что клиент хочет, а потом уже решит, как это обработать и вернёт результат. Может быть удалит страницу, а может и нет.
В HTTP общение всегда начинает клиент. А веб-сервер висит и ждёт. Сейчас есть способы инициировать запрос с сервера, но изначально протокол для этого не предназначен.
HTTP-протокол не имеет шифрования, поэтому передавать персональные данные и прочие приватные данные через него не безопасно. В таком случае нужно использовать HTTPS.
Простой способ изучить заголовки запроса и ответа — открыть консоль браузера на нужной странице и обновить её. В разделе Network/Сеть отобразятся все запросы с этой страницы, включая запросы на картинки и статические файлы.

Несколько слов о наступающем будущем — HTTP/2

Первая версия протокола HTTP была принята 20 лет назад. После этого 10 лет была тишина, пока Google не стал разрабатывать свой протокол SPDY поверх HTTP, что дало ускорение работе над HTTP/2. После серёзных подвижек Google отказался от разработки SPDY в пользу HTTP/2.

Вторая версия протокола отличается от первой чуть меньше, чем полностью.

Протокол уже стал бинарен, а значит человеко нечитаемый.
Несмотря на возможность работать без шифрования, все современные браузеры будут поддерживать именно вариант с шифрованием.
В протоколе предусмотрена возможность push-сообщений, инициированных сервером.
Протокол позволяет мультиплексирование — отправку нескольких запросов внутри одного соединения.
Умеет сжимать данные заголовков.

Новый протокол безопаснее и в несколько раз быстрее. Самое приятное, что последние версии современных браузеров понимают http2, и половина наиболее крупных и популярных сайтов уже готовы к переходу на него. С приходом http2 веб станет ещё более интерактивным, а приложения приблизятся к десктопным.

Исходный запрос	Обработанный запрос
/tags/	/index.php?go=/tags/
/all/how-web-works/	/index.php?go=all/how-web-works/
/sign-in-done/vk/?data={«user»: ...}	/index.php?go=sign-in-done/vk/