💁🏽‍♂️ Почему для поддержки CMS-agnosticism Gato GraphQL был разделён на ~90 пакетов, и каковы преимущества и недостатки этого подхода

На прошлой неделе я опубликовал статью 💁🏻‍♀️ Почему Gato GraphQL нужен монорепозиторий и как он оптимизирован, объясняющую, как и почему монорепозиторий GatoGraphQL/GatoGraphQL, в котором хранится код Gato GraphQL, может эффективно управлять кодовой базой плагина.

Я поделился своей статьёй на Reddit и получил следующий комментарий:

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

Более интересной была бы статья, объясняющая, почему вы решили, что CMS-agnosticism требует разделения всего на отдельные маленькие пакеты, и почему вы посчитали, что каждому из более чем 200 пакетов нужен свой отдельный репозиторий.

Это интересный вопрос. Поэтому я решил написать данную статью, чтобы рассмотреть его подробнее.

Но сначала я остановлюсь на двух смежных темах: сколько пакетов реально требуется плагину и почему я утверждаю, что лежащий в основе GraphQL-сервер является CMS-agnostic.

Из скольких пакетов состоит плагин

Хотя я упоминал более 200 PHP-пакетов, это относится к монорепозиторию; для плагина их значительно меньше.

Монорепозиторий GatoGraphQL/GatoGraphQL охватывает 5 проектов:

PoP — серверная библиотека компонентной модели (как React, но для бэкенда)
GraphQL by PoP — CMS-agnostic GraphQL-сервер для PHP
Gato GraphQL
конструктор сайтов (WIP)
Wassup — тема сайта на основе конструктора сайтов (WIP)

Размещение этих проектов в монорепозитории упрощает работу с ними благодаря их взаимозависимостям:

GraphQL by PoP основан на PoP
Gato GraphQL основан на GraphQL by PoP
Конструктор сайтов использует библиотеку компонентной модели в качестве движка (аналогично Gatsby, использующему GraphQL)
Wassup основан на конструкторе сайтов

Именно в отношении кода всех 5 проектов GatoGraphQL/GatoGraphQL содержит более 200 PHP-пакетов. Что касается Gato GraphQL, их «всего» 91. А GraphQL by PoP, лежащий в основе GraphQL-сервер, содержит «всего» 98 пакетов.

(Плагин Gato GraphQL требует меньше пакетов, чем его базовый GraphQL-сервер, потому что некоторые пакеты, например директива @strTranslate Google Translate, ещё не добавлены в плагин.)

Как GraphQL by PoP является CMS-agnostic? В чём его отличие от webonyx?

Я утверждаю, что GraphQL by PoP является CMS-agnostic. Но что это означает?

Для справки: webonyx/graphql-php тоже является CMS-agnostic. В чём же тогда их отличие?

webonyx/graphql-php является CMS-agnostic в том смысле, что это пакет, распространяемый через Composer, содержащий исключительно «ванильный» PHP-код. Однако сам по себе он не является GraphQL-сервером; скорее, это реализация спецификации GraphQL на PHP, предназначенная для встраивания в какой-либо GraphQL-сервер на PHP.

При этом GraphQL-серверы, реализующие эту спецификацию, такие как Lighthouse или WPGraphQL, не являются CMS-agnostic. Мы не можем запустить Lighthouse на WordPress или WPGraphQL на Laravel.

Именно в этом смысле GraphQL by PoP является CMS-agnostic: это «почти готовый» GraphQL-сервер, практически готовый к работе с любой CMS или фреймворком — будь то Laravel, WordPress или что-то иное. (Для краткости далее под словом «CMS» я буду подразумевать «CMS или фреймворк».)

Чтобы сделать его окончательным для конкретной CMS, GraphQL-серверу всё равно потребуется немного специфичного для этой CMS кода, реализованного в соответствующем пакете.

Теперь перейдём к вопросам из комментария.

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

Потому что Packagist (реестр PHP-пакетов для Composer) требует указать URL репозитория для публикации/распространения пакета.

(Кстати, моя статья Hosting all your PHP packages together in a monorepo, также опубликованная на прошлой неделе, посвящена именно этой проблеме.)

Почему CMS-agnosticism требует разделения всего на отдельные маленькие пакеты

Тому есть несколько причин.

Позволить CMS внедрять собственный код

Создать GraphQL-сервер, работающий везде и использующий 100% одного и того же PHP-кода, невозможно.

Например, чтобы дать любому фрагменту кода возможность изменять значение какой-либо переменной в другом месте, WordPress использует filter hooks, Symfony применяет компонент EventDispatcher, а Laravel имеет собственную систему событий и слушателей. PHP-код для этих трёх различных механизмов также будет различаться.

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

Чтобы это работало, каждая функциональность должна быть разделена на 2 пакета:

CMS-agnostic-пакет, содержащий всю бизнес-логику и использующий только «ванильный» PHP-код. Этот пакет будет включать контракты, которые должен выполнить CMS-специфичный пакет
CMS-специфичный пакет, выполняющий контракты для данной CMS

Например, GraphQL by PoP имеет пакет hooks, содержащий следующий контракт:

interface HooksAPIInterface
{
  public function addFilter(string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1): void;
  public function removeFilter(string $tag, callable $function_to_remove, int $priority = 10): bool;
  public function applyFilters(string $tag, mixed $value, mixed ...$args): mixed;
  public function addAction(string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1): void;
  public function removeAction(string $tag, callable $function_to_remove, int $priority = 10): bool;
  public function doAction(string $tag, mixed ...$args): void;
}

А пакет hooks-wp выполняет контракт для WordPress:

class HooksAPI implements HooksAPIInterface
{
  public function addFilter(string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1): void
  {
    \add_filter($tag, $function_to_add, $priority, $accepted_args);
  }
  public function removeFilter(string $tag, callable $function_to_remove, int $priority = 10): bool
  {
    return \remove_filter($tag, $function_to_remove, $priority);
  }
  public function applyFilters(string $tag, mixed $value, mixed ...$args): mixed
  {
    return \apply_filters($tag, $value, ...$args);
  }
  public function addAction(string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1): void
  {
    \add_action($tag, $function_to_add, $priority, $accepted_args);
  }
  public function removeAction(string $tag, callable $function_to_remove, int $priority = 10): bool
  {
    return \remove_action($tag, $function_to_remove, $priority);
  }
  public function doAction(string $tag, mixed ...$args): void
  {
    \do_action($tag, ...$args);
  }
}

Теперь, хотя концепция хуков пришла из WordPress, она может работать и с другими CMS (например, с помощью событий и слушателей для реализации хуков). Таким образом, мы можем заменить hooks-wp на hooks-laravel, hooks-symfony, hooks-drupal, hooks-octobercms или любой другой, чтобы выполнять контракты с использованием кода, специфичного для каждой CMS.

Позволить CMS отказаться от функциональности, которую она не поддерживает

Не все CMS поддерживают весь функционал. Например, WordPress позволяет сортировать записи по значению meta_value, а OctoberCMS — нет.

Именно поэтому GraphQL by PoP содержит пакет metaquery (реализованный для WordPress через metaquery-wp). GraphQL-сервер, реализованный для WordPress, будет включать этот пакет, а сервер для OctoberCMS — нет.

Преимущества этого подхода

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

Отделение бизнес-логики от CMS-специфичного кода

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

Например, для получения списка записей приложение может вызвать метод getPosts из некоторого интерфейса в CMS-agnostic-пакете posts. Тогда записи будут извлекаться всегда одинаково, независимо от реализации в конкретной CMS.

Обход технического долга и использование современных стандартов

Следуя приведённому выше примеру, мы получаем записи, вызывая метод getPosts, соответствующий соглашению PSR-4, вместо вызова get_posts, как это определено в WordPress.

Аналогично, мы можем вызывать getCustomPost для получения custom post вместо неточного get_post (это часть технического долга WordPress).

Простота скоупинга

Использование PHP-Scoper для скоупинга WordPress-плагина не является простой задачей, и даже когда это возможно, процесс чреват ошибками.

Тщательное разделение CMS-специфичного кода и бизнес-логики приложения позволяет применять PHP-Scoper только к одному набору пакетов (тем, что содержат бизнес-логику), избегая его для других (тех, что содержат WordPress-код). Я подробно описал эту стратегию здесь.

Кроме того, подобно PHP-Scoper, могут существовать и другие инструменты, которые дают сбой при применении к CMS-специфичному коду (например, WordPress). В таких случаях детализированное разделение пакетов может спасти положение.

Мы можем создавать различные приложения, каждое из которых содержит только нужный код

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

Например, личному блогу могут понадобиться только posts, tags и categories, поэтому он может не использовать функционал users или user-login.

Действительно, я планирую воспользоваться этой возможностью в ближайшее время: сейчас я работаю над «Private GraphQL API» — самодостаточным GraphQL-движком, который будет доступен разработчикам WordPress-плагинов для включения в их плагины, предоставляя GraphQL API для блоков Gutenberg.

Я могу без труда создать «Private GraphQL API», просто удалив из плагина Gato GraphQL те пакеты, которые не нужны (отвечающие за UI, клиенты, custom endpoints, HTTP-кэширование, persisted queries и некоторые другие).

Наконец, поскольку скоупинг выполняется легко (как было показано выше), я могу снабдить все необходимые пакеты префиксом, чтобы Private GraphQL API работал без конфликтов (которые могут возникнуть, когда 2 разных плагина включают разные версии Private GraphQL API).

Недостатки этого подхода

Излишне говорить, что этот подход далёк от совершенства.

Больше усилий, код становится более многословным

Как правило, если наше приложение работает на WordPress, для получения списка записей мы просто вызываем get_posts. Просто и удобно.

Переход к CMS-agnostic-подходу существенно усложняет ситуацию. Чтобы получить список записей, необходимо:

Создать пакеты posts и posts-wp
Создать контракт с функцией getPosts в пакете posts
Выполнить контракт через get_posts в пакете posts-wp
Всегда вызывать функциональность через контракт, а не напрямую

getpop/access-control
getpop/cache-control
getpop/component-model
getpop/definitions
getpop/engine
getpop/engine-wp
getpop/field-query
getpop/guzzle-helpers
getpop/hooks
getpop/hooks-wp
getpop/loosecontracts
getpop/mandatory-directives-by-configuration
getpop/modulerouting
getpop/query-parsing
getpop/root
getpop/routing
getpop/routing-wp
getpop/translation
getpop/translation-wp
graphql-api/markdown-convertor

Функциональность API:

getpop/api
getpop/api-clients
getpop/api-endpoints
getpop/api-endpoints-for-wp
getpop/api-graphql
getpop/api-mirrorquery

Функциональность GraphQL-сервера:

graphql-by-pop/graphql-clients-for-wp
graphql-by-pop/graphql-endpoint-for-wp
graphql-by-pop/graphql-parser
graphql-by-pop/graphql-query
graphql-by-pop/graphql-request
graphql-by-pop/graphql-server

Модель данных:

pop-schema/basic-directives
pop-schema/categories
pop-schema/categories-wp
pop-schema/comment-mutations
pop-schema/comment-mutations-wp
pop-schema/commentmeta
pop-schema/commentmeta-wp
pop-schema/comments
pop-schema/comments-wp
pop-schema/custompost-mutations
pop-schema/custompost-mutations-wp
pop-schema/custompostmedia
pop-schema/custompostmedia-mutations
pop-schema/custompostmedia-mutations-wp
pop-schema/custompostmedia-wp
pop-schema/custompostmeta
pop-schema/custompostmeta-wp
pop-schema/customposts
pop-schema/customposts-wp
pop-schema/generic-customposts
pop-schema/media
pop-schema/media-wp
pop-schema/menus
pop-schema/menus-wp
pop-schema/meta
pop-schema/metaquery
pop-schema/metaquery-wp
pop-schema/pages
pop-schema/pages-wp
pop-schema/post-categories
pop-schema/post-categories-wp
pop-schema/post-mutations
pop-schema/post-tags
pop-schema/post-tags-wp
pop-schema/posts
pop-schema/posts-wp
pop-schema/queriedobject
pop-schema/queriedobject-wp
pop-schema/schema-commons
pop-schema/tags
pop-schema/tags-wp
pop-schema/taxonomies
pop-schema/taxonomies-wp
pop-schema/taxonomymeta
pop-schema/taxonomymeta-wp
pop-schema/taxonomyquery
pop-schema/taxonomyquery-wp
pop-schema/user-roles
pop-schema/user-roles-access-control
pop-schema/user-roles-wp
pop-schema/user-state
pop-schema/user-state-access-control
pop-schema/user-state-mutations
pop-schema/user-state-mutations-wp
pop-schema/user-state-wp
pop-schema/usermeta
pop-schema/usermeta-wp
pop-schema/users
pop-schema/users-wp