MageOS Blog

A blog module for Mage-OS and Magento 2. Posts, categories, tags, authors, scheduled publishing, RSS, sitemap, 6 storefront widgets, SEO (meta tags, Open Graph, Twitter Cards, JSON-LD), and a full GraphQL API. Works with Luma and Hyvä themes.

Install

composer require mageos/module-blog
bin/magento module:enable MageOS_Blog
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean

For Hyvä storefronts, also install the companion template package:

composer require mageos/module-blog-hyva

Enable

The module ships disabled. Turn it on under Stores → Configuration → MageOS → Blog → General → Enabled (or set mageos_blog/general/enabled = 1).

Key admin settings

All settings live under Stores → Configuration → MageOS → Blog.

Compatibility

Requires magento/module-url-rewrite-graph-ql for the GraphQL URL resolver integration.

Storefront URLs

By default:

• Post: /blog/{url-key}
• Category: /blog/category/{url-key}
• Tag: /blog/tag/{url-key}
• Author: /blog/author/{slug}
• RSS: /blog/rss
• Search: /blog/search?q=...

URL shape is driven by mageos_blog/permalink/* config. URL rewrites populate on save via the repository plugins in Plugin/Repository/.

GraphQL

Queries: blogPost, blogPosts, blogCategory, blogCategories, blogTag, blogTags, blogAuthor, blogAuthors. Each list query accepts filter, sort, pageSize, currentPage and returns items + page_info + total_count.

Mutations: createBlogPost, updateBlogPost, deleteBlogPost (and the equivalent for category / tag / author). Every mutation requires an admin token and passes through Magento\Framework\AuthorizationInterface against the entity's ACL resource (MageOS_Blog::post, MageOS_Blog::category, MageOS_Blog::tag, MageOS_Blog::author).

urlResolver(url: "/blog/my-post") returns { type: BLOG_POST, id, relative_url }. Supported types: BLOG_POST, BLOG_CATEGORY, BLOG_TAG, BLOG_AUTHOR.

Full schema: etc/schema.graphqls.

Upgrade notes

v1.0.0 is a greenfield rewrite. There is no migration path from any v0.x fork, including the original Magefan-derived codebase that lived under this package name before the rewrite. To move off a v0 install, export content from the old admin, fresh-install v1, and re-import via the admin or GraphQL.

Development

composer install
vendor/bin/phpunit --testsuite unit
vendor/bin/phpstan analyse --memory-limit=1G
vendor/bin/phpcs --standard=phpcs.xml.dist
vendor/bin/php-cs-fixer fix --dry-run --diff
vendor/bin/infection --min-msi=75 --threads=4

Integration tests live under Test/Integration/ and run in CI against a live Magento install via graycoreio/github-actions-magento2.

Contributing

Issues and PRs welcome at https://github.com/mage-os/module-blog. Please follow Conventional Commits, include tests for new behavior, and keep PRs small and reviewable.

License

OSL-3.0. See LICENSE.

Attribution

Design inspired by Magefan Blog (OSL-3.0). v1 is an independent implementation with no shared code.

Changelog

All notable changes to this project are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.0 - 2026-04-20

First release of the greenfield rewrite. No migration path from pre-v1 forks.

Added

• Content model. Four entities (blog_post, blog_category, blog_tag, blog_author) with DB-level foreign keys and cascading deletes. Store-view scoping via pivot tables. Fulltext indexes on post and category content for search.
• Admin UI. UI-component grids and forms for posts, categories, tags, authors. Image upload (featured image, OG image, gallery) via a single MageOS\Blog\ImageUpload virtualType. Related-posts and related-products pickers on the post form.
• Storefront. Custom router with URL-rewrite integration. Post detail, category detail, tag detail, author detail, blog index, search, pagination. Luma template set under view/frontend/templates/; Hyvä template set ships in the companion package mageos/module-blog-hyva.
• Scheduled publishing. Cron\PublishScheduledPosts runs every minute, finds posts whose publish_date just passed, and re-saves them to invalidate FPC. Gated by mageos_blog/general/enabled.
• SEO. meta title, meta description, meta keywords, meta robots, canonical link, Open Graph, Twitter Cards, and Article JSON-LD on post detail pages. Configurable defaults under mageos_blog/seo/*.
• RSS. /blog/rss emits RSS 2.0 XML. Limit configurable via mageos_blog/rss/limit.
• Sitemap. Three ItemProviders (post, category, tag) wired into Magento\Sitemap\Model\ItemProvider\Composite. Per-entity enable / frequency / priority under mageos_blog/sitemap/*.
• Search. DB-fulltext-backed search against the MAGEOS_BLOG_POST_FULLTEXT index. Controller at /blog/search?q=.... OpenSearch / Magento_Search integration deferred to v1.1.
• Widgets. 6 storefront widgets: recent posts, featured post, post list, post link, category link, tag link. Admin chooser blocks for picking a post / category / tag from grids.
• GraphQL. Queries (blogPost, blogPosts, blogCategory, blogCategories, blogTag, blogTags, blogAuthor, blogAuthors). Mutations (create / update / delete for all four entities). URL resolver integration: urlResolver(url:"/blog/my-post") returns type: BLOG_POST. Mutations require admin token plus ACL.
• Hyvä support. A Plugin\Magento\Framework\View\TemplateEngine\Php plugin injects a HyvaThemeDetection helper into every .phtml scope. Plugin\Magento\Framework\View\Element\TemplateRewrite remaps MageOS_Blog::X paths to MageOS_Blog::hyva/X on Hyvä themes.
• i18n. Seed i18n/en_US.csv with 236 phrases.
• Quality gates. PHPStan level 8, PHPCS (Magento2 ruleset), PHP-CS-Fixer, PHPUnit unit suite (57 tests), Infection mutation testing (baselines: MSI 54%, Covered MSI 70%).

Notes on design

Design inspired by Magefan Blog (OSL-3.0). v1 is an independent implementation with no shared code.

Deferred to v1.1

• Comments (native, moderation, spam, email).
• Content importers from Mageplaza, Magefan, Aheadworks, Mirasvit, WordPress. Will ship as a separate mageos/module-blog-migration package.
• OpenSearch / Magento_Search indexer + mview + etc/search_request.xml.
• PageBuilder content editing.
• Hyvä-native .phtml set (detection plugin is in place; the companion package is empty until v1.1).
• Configurable URL prefix, custom per-page CSS, preview-token model, Commerce-only AdminGWS plugin, MFTF tests, gravatar autofetch, per-post multi-language content variants.
• Infection MSI ≥ 75% / Covered MSI ≥ 80%. v1.0 ships at 54% / 70% respectively; raising the floor depends on expanding unit-test coverage into ViewModel/Post/Detail (JSON-LD shape edge cases) and Model/HyvaThemeDetection (theme-chain walking).