Релиз MoonShine v3. История и нововведения

Привет, коллеги!

Я, Данил Щуцкий (CutCode), уже более 2-х лет работаю над open-source админ-панелью для Laravel — MoonShine. Вот несколько материалов с Habr по MoonShine:

https://habr.com/ru/articles/833618/
https://habr.com/ru/articles/774832/
https://habr.com/ru/articles/760582/

10 декабря 2024 г. состоялся релиз MoonShine v3 (вот ссылка на стрим, где я делал релиз). В этой статье хотел рассказать о проделанной работе и основные нововведения по проекту.

Итак, MoonShine v3 это:

• полностью новая архитектура

• отсутствие привязки к Eloquent ORM и Laravel

• документация на собственной платформе в формате MD

• и много других фич

Расскажу поподробнее. 

Путь к MoonShine v3

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

Можно сказать последние месяцы я жил этим третьим релизом MoonShine. Засыпал, какие-то задачи в голове переваривал, просыпался, либо находил сразу ответы, бежал делать, либо продолжал вступать в какие-то челленджи, чтобы сделать MoonShine именно таким, каким я себе его вижу.

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

Казалось бы, сейчас для меня время выдохнуть. Релиз MoonShine v3 готов, но… думаю, что ближайшее время будет активный фидбэк: помощь по документации, по нахождению каких-то проблем, неудобств. 

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

MoonShine 3 стал намного больше. По моим прикидкам, раз в 10 больше по сравнению с v2. 

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

История релизов MoonShine

MoonShine v1

Давайте начнём с первой версии. Вот как выглядел MoonShine, когда он только появился:

Назывался он не MoonShine, а Laravel Admin Panel. Никакого MoonShine ещё не было. 

Напомню, изначально была идея в чате CutCode Laravel, где ребята написали: «Давайте собственный open-source придумаем. Это круто, вместе будем пилить!»

И вот в таком виде я его представил тогда на YouTube-канале: «Ребята, вот наш общий open-source. Давайте делать! Всё, как вы хотели.»

Логотип тоже был другим, я его сам рисовал. Вот такая вот была страница входа. Просто вырви глаз. 

Я тогда как раз в первый раз увидел Nova. Просто читал документацию и думал: «Как круто, все эти поля (Field), как это всё интересно сделано!» Но платить за неё не стал. И просто взял по документации и воспроизвёл свою версию.

Уже позже понял, что воспроизвёл так же плохо, как это сделано в Nova. Эта основа от Nova, которую я перенял к себе, мне потом аукнулось — не лучшая кодовая база и сильная привязка к Eloquent. В MoonShine v2 пришлось рефакторить — удалять и переделывать. Как раз в какой-то момент я и на Filament посмотрел, перенял некоторые идеи, и это тоже мне аукнулось. Что касается MoonShine v3, это уже уникальный продукт. Здесь ничего нет заимствованного. И я в целом пришёл к тому, что нужно идти своим путём.

В марте 2022 я познакомился с Александром, который сделал нам логотип:

И мы перекочевали на отдельный репозиторий. Почему я так сделал? Чтобы это не было привязано к моему личному аккаунту на GitHub. То есть если это общий проект, от комьюнити, то странно иметь авторство вендора. Поэтому я создал отдельный аккаунт на GitHub — MoonShine Software, создал там репозиторий MoonShine, и 12 мая 2022 г. мы всё перенесли в него (можно сказать официальный день рождения MoonShine).

И после нескольких месяцев работы вдвоём с Александром, у нас 8 июня 2022 г. появился еще один контрибьютор — nikitaMai. И, возможно, это повлияло на то, как в дальнейшем развивался MoonShine. Это был переломный момент, когда в принципе я увидел, что в чатах кто-то пользуется MoonShine. Мне этого было достаточно, чтобы продолжать его пилить.

Александр начал использовать MoonShine в коммерческих проектах. Но дизайн такой, что его серьёзному заказчику не покажешь. Было принято решение заказать дизайн.

И в середине июня 2022 г. мы сделали релиз 1.50 — с новым дизайном, таким как вы его видите сейчас. У нас появились контрибьюторы, пошёл какой-то прогресс. Дизайн новый это хорошо, но при этом всё, что под капотом, осталось тем же самым. То есть изменились только blade view. Да, визуально стало получше. Но под капотом оставался legacy артефакт от 0.9, который был сделан «на коленке». Ну ведь для этого и создан быть наш open-source проект MoonShine — чтобы была возможность поработать всем: и опытному разработчику и, человеку, который только прочитал там мою книжку «Laravel Ninja Guide», мог прийти в этот проект. 

И, кстати, ещё такой момент. У нас с Сашей была задача и идея 2.0 сделать раздельным. То есть и бэк, и фронт — это два разных проекта. Они полностью изолированы, чтобы, если кто-то захотел, мог там написать свой фронт на чём угодно, либо оставить только фронт, написать свой бэк. Но пока это так и осталось нереализованным.

MoonShine v2

Итак, с кодом у MoonShine v1 были большие проблемы и релиз v2 как раз должен был их закрыть. Помимо того, что нужно отрефакторить код, появились новые задачи. Одна из них, это был челлендж — отделиться от Eloquent ORM. Это, наверное, самая основная задача была для 2.0 — сделать админку, в которой не забетонирован Eloquent. 

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

Мы с ними начали общаться, им тоже понравилась идея MoonShine, и мы начали пилить вторую версию. Сперва я сделал ядро, сделал концепт таким, каким его вижу. И с августа 2022 г. я подключил уже остальных. Это было похоже на лавину, было очень мощно. Мы тогда работали просто как безумные. У нас появился еще один Александр, который занялся документацией, но помимо документации он кучу всего делал по фронтенду. От него лились pull-реквесты. Плюс Иван, автор нового пакета MoonShine Rush и множества фишек. И от него тогда тоже просто лавиной шли pull-реквесты. ShowWhen (позволяет динамически управлять отображением полей в зависимости от значений других полей ипозволяет скрывать или показывать поля в реальном времени без перезагрузки страницы), OnlyLink используется для отображения ссылки без возможности редактирования и позволяет вам показывать пользователям определенные данные в виде ссылки, но не дает им возможности изменять это значение) это всё сделано Иваном.

В разработке второй версии я чувствовал себя Taylor Otwell и делал ревью pull-реквестов, помогал ребятам, подсказывал. Так появился MoonShine v2. Появился он тоже не в том виде, как я планировал изначально, и часть фишек перекочевала в roadmap дальнейшей работы.

Отдельное слово по документации MoonShine — это очень сложная и важная работа. На самом деле написание документации гораздо сложнее, чем написание самого кода. И Саша написал большую часть документации для второй версии MoonShine.

Окей, MoonShine v2, готов в ноябре 2023. И я подумал: раз так сейчас кипит работа, то что будет на релизе 3.0?! Наверное, ещё больше разработчиков будет. Наверное, документация вообще пойдёт как по маслу!

MoonShine v3

Основная задача на v3 — это была уже изоляция от Laravel в каком-то виде. Чтобы это уже была монорепа, где всё будет в отдельных пакетах. Laravel просто как отдельный пакет, AssetManager, MenuManager, UI и т.д. В целом можно сказать что MoonShine мы отделили от Laravel. Но есть привязка ещё к коллекциям и контрактам. Я уже пробовал реализацию MoonShine на Symfony. Сейчас выйдет Yii3, почему бы и не подружить его с MoonShine. Но я сторонник разделять основной сайт и админку — и разворачивать MoonShine+Laravel на поддомене. 

Оставлю небольшой спойлер, после релиза v3 я вам покажу ещё интересную фишку MoonShine v3, которая просто изменит отношение к админкам — и фреймворки и языки программирования на которых реализованы проекты (проекты) не будут иметь особого значения.

С ноября 2023 по май 2024 я собирал фидбэк от пользователей и фиксировал свои мысли, каким должен быть v3. План на релиз MoonShine v3 был такой:

• с мая делаю концепт 

• июнь-июль подключаю остальных ребят допиливать код и доку

• к октябрю заканчиваем работу

Но всё пошло не по плану. Это как раз минусы open source, о которых мы сейчас с вами поговорим. 

Работы предстояло очень много. MoonShine v3 — это полностью переписанная админка. В мае провели кэмп MoonShine Dev. Было 11 активных разработчиков MoonShine, где я уже делился информацией о том, каким будет MoonShine, показал концепт и уже думал, что этот костяк команды разработки и который будем наращивать.

Но вот июнь, но никто, включая основных разработчиков, ничего не делал. Июль, август, всё в таком же состоянии. Я просто пилил MoonShine целыми днями, и никто не подтягивался.

Где-то в августе потянулся Иван. Поработал над ShowWhen(). Полностью её проапгрейдил. И ещё какие-то небольшие pull-реквесты.

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

Документация и PHPStan

Заняться документацией у Саши не хватало времени, а на него была основная надежда. Вариантов не оставалось, кроме как взяться самому за документацию. Также я создал группу из ребят, которые вызвались помогать по документации. Но всё тоже шло тяжело. И в итоге, мне кажется, процентов 90 документации тоже написал я. Понимая, что к 1 ноября с релизом не успеваем, и пришлось перенести релиз на 10 декабря.

Параллельно знакомый фронтендер делал платформу для документации и правки по самой админке. Также пришлось из-за сжатых сроков уменьшить количество задач по фронтенду, процентов на 50.

Последнюю неделю перед релизом была особенно напряженной, и 9 декабря мы с Иваном сделали финальный спринт по доке и закрыли основные разделы

Очень много времени потрачено на документацию, но мы не добили её! И мне кажется, что документация Moonshine сейчас больше, чем документация Laravel.

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

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

Что ещё по документации. Она полностью перекочевала на Markdown. У нас собственная платформа, которая их парсит и выглядит стильно. Сначала не хотел писать своё решение, рассматривал готовые: Mintlify, Docusaurus, GitBook и другие. Но везде были недостатки. Например, с версионированием или поддержкой языков. Многие думают, что существует только английский язык, и не заморачиваются с этим. В итоге пришлось писать свою платформу, потрачено много усилий на это опять же, но в итоге я очень доволен. Теперь мы можем делать с ней всё, что хотим.

Что ещё изменилось в плане кода? У нас помимо просто тестов, появились мутационные тесты. PHPStan вырос в уровне: был на первом, теперь на пятом. И я планирую увеличивать этот показатель. В целом, порог входа для контрибьюторов вырос.

MoonShine 3 на мой взгляд стал сложнее для пользователя. Я имею в виду, что к нему нужно будет привыкнуть. Раньше у нас все поля были в методе fields и внутри мы их разделяли через дополнительные методы — showOn/hideOn чтобы добиться того, что одни поля отображаются на странице списка, другие на форме и получалась каша, но в 3 версии все вынесено в отдельные методы, а методы полей showOn/hideOn удалены.

Домен

Кстати, что касается домена moonshine-laravel.com. Казалось, изначально это крутая идея, что прямо в имени домена понятна привязка к Laravel. Это самый популярный PHP-фреймворк, и админка будет на нём. Но с MoonShine v3 всё меняется, и уже админ-панель перерастает Laravel. И, возможно, имя домена нужно заменить. Так что пишите в комментариях идеи по новому домену.

В установленном MoonShine английский по дефолту

Сейчас в Moonshine из коробки есть только английский язык. Русского уже нет.

Почему? Потому что Moonshine сейчас пользуются не только русскоговорящие. Пользователи со всего земного шара. Снимаются гайды на английском и испанском. Зарубежное комьюнити растёт. И английский язык был выбран по умолчанию. 

А все языки вынесены в отдельные пакеты. Если нужно, зашли в раздел локализации маркетплейса, установили и всё готово.

Разные подходы

Что мне нравится в Moonshine v3 — это возможность применения разных подходов. Любите конфиги как привыкли в Laravel? Пожалуйста, пользуйтесь. Хотите через объекты? Пожалуйста, у нас есть объект конфига с fluent интерфейс.

Всё сделано для удобства разработчиков. Но у нас остается слабое место — это пакет Moonshine/Laravel. Там ещё есть хелперы, но в будущем мы их удалим, чтобы оставить только dependency injection.

Теперь всё проще: сделали inject конфигурации. Никаких ресурсов, никакого меню в провайдере — всё гибко и просто.

MoonShine меняет отношение к админкам

Обычно как проходит генерация админки для проекта? Это рутина. По крайней мере, для меня это всегда так было: либо писал какой-то свой велосипед (это было очень грустно), либо брал готовое решение и быстро генерировал. Мне это всё не нравилось. Лишь бы это работало, лишь бы это принял заказчик. Быстро с этим делом справиться и забыть, как страшный сон.

Что касается MoonShine, здесь своя атмосфера. Я прям кайфую. Для меня теперь создание админки — это интересное занятие. Написание админки на MoonShine аналогично собиранию конструктора. Мне нравится собирать конструкторы, даже недавно я купил себе большой конструктор с машинкой, я её собирал неделю, получил кучу удовольствия. Времени уходит немало, но при этом ты наслаждаешься. То же самое Moonshine: собираешь этот конструктор и наслаждаешься, пытаешься где-то сделать чище, придумать новые решения. Крутое чувство. И это именно та атмосфера — к которой я стремился. Чтобы MoonShine был не просто каким-то инструментом, который быстро генерирует, а чтобы его применение доставляла разработчикам удовольствие и делало их счастливее.

Комьюнити

Итак, всем понятно что MoonShine v3 — крутая админка😉. Но без комьюнити это ничто. Без продвижения это не взлетит. Нужно продвигать продукт, писать гайды, статьи, общаться с людьми. Важно, чтобы люди приняли эту «религию MoonShine» и тоже рассказывали, насколько это классно. Мы вкладываем в него душу. Я им сейчас живу.

Кто-то сказал, что на простую админку потратил три месяца, а когда попробовал MoonShine, сделал такую же за несколько дней! Мы стараемся делать разработчиков счастливее, а себя — чуть более уставшими😎. Когда вы пишете благодарности, это невероятно мотивирует.

Думаю, у меня впереди ещё много челленджей. Не думайте, что релиз версии 3 — это всё. Работы предстоит ещё очень много.

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

Иногда мне пишут: «Ой, да я там ничего не сделал. Я вот там символ, запятую поставил в документации или в коде doc block поправил. Какая-то мелочь». Но для меня такие PR имеют большую ценность, так как такие вещи часто не замечаешь, когда сконцентрировался на чем-то сложном, на каких-то челленджах, проблемах в ядре, и вот такая даже небольшая помощь очень важна!

Обновление с MoonShine v2 до v3

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

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

Я снял два видео гайда по обновлению — один (более расширенный) загрузил на boosty (можете поддержать MoonShine), второй (обновление проекта попроще) — на youtube.

Сравнение с Filament

Часто спрашивают о сравнении с Filament. Моё мнение: Filament — это суперлегкий инструмент с низким порогом входа, весь в «сахаре». Moonshine же рассчитан на более сложные задачи, требует от пользователя навыков разработки и при этом не ограничивает разработчика, а позволяет ему сделать админку быстрее. Да, работать с MoonShine, наверное, сложнее чем с Filament, но это того стоит. Но про новичков я ни в коем случае не забываю, и базовые функции с MoonShine (CRUD, кастомизация UI) сделать максимально просто.

MoonShine — просто для новичков, безгранично для профессионалов.

Но у меня в планах сделать качественное сравнение админок Laravel. Кто хорошо разбирается в Filament и готов выступить в роли его представителя в битве админок, напишите мне.

В целом популярность MoonShine растет. В недавнем голосовании за лучшую админку для Laravel в 2024 на Laravel World, MoonShine вошел в top-3 популярных админок!

Проголосовало более 2500 человек и MoonShine заняла 3-е место, меньше 1% уступив Filament и Nova. 

Marketplace Moonshine

Еще одно нововведение, которое появилось вместе с третьей версией MoonShine. Что он из себя представляет? Это место, куда разработчики смогут выкладывать свои пакеты. Конечно, мы будем модерировать контент, чтобы там не появлялись ненужные или уже существующие решения. Но если у вас есть что-то интересное, вы можете сделать пакет и выложить его сюда. Это может быть как бесплатное, так и платное решение. Marketplace создан для дополнительной мотивации для разработки своих полезных решений. Если вы хотите написать полезное дополнение для MoonShine (или уже написали), то можете мне в личку просто написать, пообщаемся, обсудим детали.

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

В итоге выигрывают все, в особенности разработчик, который использует MoonShine. 

Есть первый платный пакет от MoonShine — Rush. Это готовая интеграция веб-сокетов. Здесь все популярные драйверы под веб-сокеты. И Echo, и Centrifugo, и Socket.io, и любое свое решение. Я запишу отдельное видео более подробно о Rush — это огромный пакет, который дает возможность в MoonShine легко сделать «живые формы»: вы будете видеть кто именно редактирует форму, какое поле редактирует, могли заблокировать редактирование, чтобы исключить одновременное изменение записи. Динамический вывод метрик и значений — масса полезных вещей для реализации по-настоящему функциональной админки.

Спонсоры

На лендинге у нас появился блок со спонсорами MoonShine — это уважаемые в нашем комьюнити люди. В этом блоке мы показываем кто именно и сколько задонатил. Также есть отчет по донатам, который я регулярно обновляю. Фиксирую кто сколько донатил, сколько и на что мы тратим (дизайн, верстка, хостинг и т.д.). Есть уже немало постоянных спонсоров. А совсем недавно баланс проекта стал положительным. Это радует.

Пару слов о новых возможностях

MoonShine постепенно обретает новые возможности. Теперь не только админку и MVP, но и личные кабинеты можно создавать на базе Moonshine. Вкратце по возможностям:

• Отдельные layout’ы. Например, регистрация, восстановление пароля и профиль теперь имеют свои layout’ы, которые позволяют адаптировать страницы под конкретные задачи.

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

• В версии 3.0 появился CRUD-ресурс. Теперь можно использовать интерфейс CRUD-ресурса для полной реализации своего решения или воспользоваться готовой абстракцией. Это существенно упрощает работу с REST API. Таблицы поддерживают lazy-загрузку, что минимизирует нагрузку на сервер.

• Moonshine Builder. Пакет от Ивана автоматически генерирует ресурсы на основе структуры базы данных. Это упрощает процесс создания админки и экономит время.

Выводы

Объемная получилась статья, в которой я больше сделал упор на историю релиза MoonShine v3 и нововведения проекта в целом. Скоро сделаю еще статью, в которой подробно расскажу о возможностях новой версии админки. 

Спасибо за внимание. Используйте MoonShine и будьте счастливы!❤️

https://moonshine-laravel.com/
https://github.com/moonshine-software/moonshine
https://t.me/moonshine_ru