README

Blog articles, categories and comments for Drago Project.

The package adds a backend module for writing articles, managing categories and approving comments with their article, and a frontend with the article list, categories and article details with comments.

Requirements

PHP >= 8.3, < 9
Drago Project

Installation

composer require drago-ex/project-blog

Files copied into the project

The files are copied into the project by drago-ex/project-tools, as set in extra.drago-tools of this package's composer.json.

Database migration

php vendor/bin/migration db:migrate --packages

The migrations create the tables blog_article, blog_category and blog_comment.

Assets

The toolbar of the content field and the copy button of code blocks come from drago-ex/texy-toolbar; set them up as its README shows (admin.js for the toolbar, front.js for the toolbar of comments and the copy button). Without them the blog works too.

Backend

The backend presenter is available as:

{link :Backend:Blog:}            {* articles with their comments *}
{link :Backend:Blog:categories}  {* categories *}

With drago-ex/project-backend-ui, add the links to its menu (see its README).

A new category is written right in the article form ("+ New category"); the button "Categories" above the articles opens their list for renaming and deleting. The slug of a new category is made from its name with the PHP extension intl. Comments are managed with their article: the article list shows whether they are allowed (a click on the state switches it), their number and those waiting for approval, and an opened article has the tab "Comments" to approve or delete them. The number of all comments waiting for approval comes from CommentBadge, a service for the menu numbers and the navbar bell of project-backend-ui; register it as its README shows.

The module uses the permission resource Backend:Blog. The backend provider allows the administrator role.

Frontend

The routes /blog, /blog/kategorie/<slug> and /blog/<slug> (and with /en/) are added by app/Presentation/Front/Blog/7.conf.neon, before the front router.

{link :Front:Blog:}
{link :Front:Blog:detail, slug: 'first-article'}

Article content is written in Texy and printed safely by drago-ex/texy-toolbar; the perex is the meta description of the article.

The list shows the articles as cards side by side: a wide image, a relative date ({$date|ago}, e.g. "2 months ago") with the category, the title, the perex and the author with a Gravatar avatar (drago-ex/gravatar, registered in Front/Blog/7.conf.neon). The newest article is shown over the whole row with a large image beside the text (Front/Blog/@article-featured.latte), the others are cards (Front/Blog/@article-item.latte). Other pages show articles the same way with ArticleListFactory::create() and Front/Blog/@article-list.latte. The author is the signed-in user who created the article.

The cover image is uploaded in the article form. It is made smaller to fit 1600 × 1200 px and saved in www/upload/blog/; replacing or removing the image and deleting the article delete the file. Resizing needs the PHP extension GD (the Docker image of drago-ex/project-docker has it); without it the form offers no upload. Add /www/upload/ to .gitignore.

Anyone may write a comment; it is shown after an administrator approves it. Comments use basic Texy (no images, headings or HTML). Each article allows or disallows them by its own "Allow comments" switch. A signed-in user does not fill in the name and email, the comment gets those of the account. Approved comments are numbered (#1, #2, …) and "Reply" puts #2 Name into the form; such a number in a comment links the comment, which lists its replies. Putting the text into the form needs a small script of the project (without it the link only goes to the form).

The frontend permission provider uses the resource Front:Blog and allows it to guests.

Optional add-ons

The package works without them. Set them up by hand as described below when the project needs them.

Permissions

The blog works without permissions and without drago-ex/permission: the administration shows all its buttons.

For static permissions, the access rules are prepared in bin/create-blog-permission; drago-ex/permission generates a provider from it (set up as its README shows):

php vendor/bin/drago-commands

To show the add, edit and delete buttons only to roles with the privilege, add the WriteAccess trait of drago-ex/permission; its isWriteAllowed() asks for the {component}-write privilege. In app/Presentation/Backend/Blog/Component/BaseControl.php use the trait and pass the result to the template (with public bool $writeAllowed = false; in BaseTemplate):

use Drago\Permission\WriteAccess;

abstract class BaseControl extends ExtraControl implements OffcanvasHandle, ModalHandle
{
	use Component;
	use WriteAccess;

	public function createRender(): Template
	{
		// ...
		$template->writeAllowed = $this->isWriteAllowed();

then hide the grid actions by it and show the add button only when allowed:

$grid->addActionEdit(fn(int $id) => $this->handleEdit($id))
	->setVisible($this->isWriteAllowed());

{embed '../@datagrid-heading.latte', addButton: $writeAllowed}

In the article, show the approve and delete buttons of the comments tab (<div class="article-comment-actions …">) only with n:if="$writeAllowed", and let ArticleControl::getToggleCommentsLink() return null without the privilege, so the state of the comments in the grid is not clickable.

For dynamic permissions set in the administration, install drago-ex/project-permission and import the privileges of the blog into its resources table by hand, so roles can be given them (e.g. an editor who only views articles):

php vendor/bin/migration db:migrate vendor/drago-ex/project-blog/migrations-permission

drago-ex / project-blog

Package info

Security

Statistics